Google Workspace

Configure a Google Workspace custom SAML app for your Auth application.

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

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-----"]
   }
   

   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).

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 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.

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.