Skip to main content
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

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

1

Create a custom SAML app in Google

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

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-----"]
}
FieldDescription
nameA human-readable label for the connection.
enabledSet to false while you finish IdP setup; flip to true at the end.
idp_metadata_xmlBase64-encoded (or raw) IdP metadata XML downloaded from Google. Provide exactly one IdP source.
idpExplicit 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).
3

Enter the SP details in Google

Back in the Google Admin Console, on the Service provider details screen:
  1. Set ACS URL to the sp.acs_url from the response
  2. Set Entity ID to the sp.entity_id from the response
  3. Set Name ID format to EMAIL
  4. Set Name ID to Basic Information > Primary email
  5. Click Continue
4

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 fieldApp attribute
First namefirst_name
Last namelast_name
Primary emailemail
Click Finish.
If you use different attribute names on the Google side, override them in the connection’s mapping block via a PUT request.
5

Turn on access and enable the connection

  1. In Google, open User access for the app and turn it ON for the relevant organizational units.
  2. 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.