Google Workspace

This guide walks you through connecting a Google Workspace custom SAML application to Prelude Auth. Google is the Identity Provider (IdP); Prelude Auth is the Service Provider (SP).

Prerequisites

A Google Workspace account with super admin access
A verified custom domain on your Auth application

Because the SP endpoints embed the generated connection ID, the flow is: start the Google SAML app to obtain its metadata, create the Prelude connection from that metadata, then paste the generated SP values back into Google.

Configure Google Workspace SAML

Create a custom SAML app in Google

Open the Google Admin Console
Go to Apps > Web and mobile apps
Click Add app > Add custom SAML app
Enter an app name (e.g. “Prelude Auth”) and click Continue
On the Google Identity Provider details screen, click Download metadata (or copy the SSO URL, Entity ID, and Certificate). Click Continue.

Create the SAML connection in Prelude

Create the connection from Google’s metadata. Start it disabled — you will enable it once the SP URLs are wired back into Google. If you downloaded the metadata XML, base64-encode it and pass it as idp_metadata_xml:

curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/google \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Google Workspace",
    "enabled": false,
    "idp_metadata_xml": "'"$(base64 -w0 GoogleIDPMetadata.xml)"'",
    "behavior": {
      "jit_provisioning": true,
      "allow_email_account_merge": true,
      "email_domain_allowlist": ["acme.com"],
      "enforce_login": false,
      "default_redirect_uri": "https://app.acme.com/callback"
    }
  }'

Alternatively, supply the IdP values explicitly instead of the metadata XML:

"idp": {
  "entity_id": "https://accounts.google.com/o/saml2?idpid=C01abc234",
  "sso_url": "https://accounts.google.com/o/saml2/idp?idpid=C01abc234",
  "certificates": ["-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"]
}

Field	Description
`name`	A human-readable label for the connection.
`enabled`	Set to `false` while you finish IdP setup; flip to `true` at the end.
`idp_metadata_xml`	Base64-encoded (or raw) IdP metadata XML downloaded from Google. Provide exactly one IdP source.
`idp`	Explicit IdP block — an alternative to `idp_metadata_xml`.
`behavior.*`	Provisioning and enforcement options — see the Introduction.

The response contains an sp block with the values you need next (sp.entity_id and sp.acs_url).

Enter the SP details in Google

Back in the Google Admin Console, on the Service provider details screen:

Set ACS URL to the sp.acs_url from the response
Set Entity ID to the sp.entity_id from the response
Set Name ID format to EMAIL
Set Name ID to Basic Information > Primary email
Click Continue

Map attributes

On the Attributes screen, map Google directory fields to the attribute names Prelude expects. The Google provider defaults to snake_case names, so map:

Google directory field	App attribute
First name	`first_name`
Last name	`last_name`
Primary email	`email`

Click Finish.

If you use different attribute names on the Google side, override them in the connection’s mapping block via a PUT request.

Turn on access and enable the connection

In Google, open User access for the app and turn it ON for the relevant organizational units.
Enable the Prelude connection:

curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/google/${CONNECTION_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Delete the connection

curl -X DELETE https://api.prelude.dev/v2/session/apps/${APP_ID}/config/login/saml/google/${CONNECTION_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}"

Existing saml:<connection_id> user identifiers are retained so historical sessions stay auditable.

What’s next?

Now that the Google Workspace connection is configured, integrate the frontend using the Web Integration guide, or require this domain to use SSO with Enforce SSO login.

Documentation

API Reference

Prerequisites

Configure Google Workspace SAML

Delete the connection

What’s next?

​Prerequisites

​Configure Google Workspace SAML

​Delete the connection

​What’s next?

Prerequisites

Configure Google Workspace SAML

Delete the connection

What’s next?