> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prelude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://workspace.google.com/) account with super admin access
* A verified [custom domain](/session/documentation/domain-names) 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

<Steps>
  <Step title="Create a custom SAML app in Google">
    1. Open the [Google Admin Console](https://admin.google.com/)
    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**.
  </Step>

  <Step title="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`:

    ```bash theme={null}
    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:

    ```json theme={null}
    "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](/session/documentation/integration-guide/saml/introduction#connection-behavior). |

    The response contains an `sp` block with the values you need next (`sp.entity_id` and `sp.acs_url`).
  </Step>

  <Step title="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**
  </Step>

  <Step title="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**.

    <Note>
      If you use different attribute names on the Google side, override them in
      the connection's `mapping` block via a `PUT` request.
    </Note>
  </Step>

  <Step title="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:

    ```bash theme={null}
    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 }'
    ```
  </Step>
</Steps>

## Delete the connection

```bash theme={null}
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](/session/documentation/frontend-sdks/web/saml) guide, or require this domain to use SSO with [Enforce SSO login](/session/documentation/integration-guide/saml/enforce).