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

# Google Workspace

> Connect OpenCX to Google Workspace with a custom SAML app from the Google Admin console. Covers the SAML app wizard, attribute mapping, organizational-unit access, and testing.

Connect OpenCX to **Google Workspace** with a custom SAML app from the Google Admin console. Google Workspace does not offer SCIM to third parties, so provisioning is [just-in-time](/security/sso/scim#just-in-time-jit): members are created on first login.

## Before you start

<Steps>
  <Step title="Confirm your admin role">
    You need a **Super Admin** account in the Google Admin console.
  </Step>

  <Step title="Have your OpenCX SP details ready">
    | OpenCX value                                                      | Google field |
    | ----------------------------------------------------------------- | ------------ |
    | **ACS URL**: `https://auth.open.cx/sso/saml/{connection-id}/acs`  | ACS URL      |
    | **SP Entity ID**: `https://auth.open.cx/sso/saml/{connection-id}` | Entity ID    |
  </Step>
</Steps>

## 1. Create the custom SAML app

<Steps>
  <Step title="Open the SAML apps list">
    In the [Google Admin console](https://admin.google.com) go to **Apps → Web and mobile apps → Add app → Add custom SAML app**.
  </Step>

  <Step title="Name the app">
    Set the name to `OpenCX`, optionally add the logo, and click **Continue**.
  </Step>

  <Step title="Copy Google's IdP details">
    On the **Google Identity Provider details** step, download the **Metadata** (or copy the **SSO URL**, **Entity ID**, and **Certificate**). You'll hand this to OpenCX. Click **Continue**.
  </Step>

  <Step title="Enter the OpenCX service provider details">
    * **ACS URL** → your OpenCX **ACS URL**
    * **Entity ID** → your OpenCX **SP Entity ID**
    * **Name ID format** → **EMAIL**
    * **Name ID** → **Basic Information > Primary email**

    Click **Continue**.
  </Step>
</Steps>

## 2. Map attributes

On the **Attribute mapping** step, add:

| Google directory attribute | App attribute |
| -------------------------- | ------------- |
| **First name**             | `firstName`   |
| **Last name**              | `lastName`    |
| **Primary email**          | `email`       |

<Note>
  Google Workspace can send **group membership** as a claim: add a group mapping, pick the groups OpenCX should know about, and map them to an app attribute named `groups`. Use this for [role mapping](/security/sso/scim#role-mapping). If you skip it, everyone lands as the default role.
</Note>

Click **Finish**.

## 3. Hand your metadata to OpenCX

Give the metadata you downloaded in step 1 (or the SSO URL, Entity ID, and certificate) to your OpenCX contact. We register your Google issuer, SSO endpoint, and signing certificate on your connection.

## 4. Turn on access

<Steps>
  <Step title="Set the service to ON">
    Open the app → **User access**. Google apps default to **OFF**. Turn it **ON for everyone**, or **ON** only for the organizational units / groups that should reach OpenCX.
  </Step>

  <Step title="Wait for propagation">
    Google access changes can take a few minutes (occasionally up to 24 hours) to propagate. Give it time before testing.
  </Step>
</Steps>

## 5. Test the login

<Steps>
  <Step title="IdP-initiated">
    From a pilot user's Google account, open the **apps grid (waffle) → OpenCX**, or `https://myapps.google.com`, and click the OpenCX tile.
  </Step>

  <Step title="SP-initiated">
    In a private window, go to [platform.open.cx](https://platform.open.cx), enter the pilot's work email, and confirm the redirect to Google and back to the OpenCX Inbox.
  </Step>

  <Step title="Confirm the role">
    Verify the expected OpenCX role landed. If not, check the group mapping and your [role mapping](/security/sso/scim#role-mapping).
  </Step>
</Steps>

## 6. Enforce

When the pilot is clean, ask OpenCX to enforce SSO for your domain. Read the [pre-cutover checklist](/security/sso/troubleshooting#before-you-enforce) first and secure your [break-glass account](/security/sso/overview#enforcement-break-glass).

## Troubleshooting

| Symptom                       | Likely cause                                                               |
| ----------------------------- | -------------------------------------------------------------------------- |
| `app_not_configured_for_user` | The service is **OFF** for that user's org unit, or hasn't propagated yet. |
| Names blank                   | `firstName` / `lastName` attribute mappings missing.                       |
| Everyone is the default role  | No `groups` mapping, or group names aren't in your OpenCX role mapping.    |

More in [Troubleshooting SSO](/security/sso/troubleshooting).