<!-- source: https://modelux.ai/docs/guides/sso-google -->

> Connect Google Workspace as your SAML identity provider for Modelux.

# SSO with Google Workspace

Step-by-step Google Workspace setup. Requires the **Super Admin** role
in Google Workspace and **admin** or **owner** in Modelux.

If you haven't read the [SAML SSO overview](/docs/guides/sso), start
there.

## 1. Collect Modelux SP details

In Modelux → **Settings → SSO**, note:

- **SP Entity ID**
- **Assertion Consumer Service URL**

## 2. Create a custom SAML app in Google

1. [admin.google.com](https://admin.google.com) → **Apps → Web and
   mobile apps → Add app → Add custom SAML app**.
2. App name: `Modelux`. Click **Continue**.
3. On the **Google Identity Provider details** page, you'll see three
   values:
   - SSO URL
   - Entity ID
   - Certificate (click **Download certificate** — this is a `.pem`
     file)
4. **Keep this browser tab open** — you'll paste these into Modelux in
   the next step. Click **Continue**.

## 3. Configure the SP side

On the **Service Provider details** page:

- **ACS URL:** Modelux's **Assertion Consumer Service URL**
- **Entity ID:** Modelux's **SP Entity ID**
- **Name ID format:** `EMAIL`
- **Name ID:** `Basic Information > Primary email`
- Click **Continue**.

## 4. Configure attribute mapping

| Google directory attribute | App attribute |
| --- | --- |
| `Primary email` | `email` |
| `First name` | `firstName` |
| `Last name` | `lastName` |
| `Full name` (if available) | `displayName` |

Click **Finish**.

## 5. Copy Google → Modelux

Back on the Google side, re-open the **Google Identity Provider details**
panel (you can find it on the app's overview → **SP detailed configure**
or by re-entering the wizard):

| Google field | Modelux field |
| --- | --- |
| *SSO URL* | IdP SSO URL |
| *Entity ID* | IdP Entity ID |
| *Certificate* (contents of the downloaded `.pem`) | IdP certificate |

Paste into Modelux's **Identity provider** form, set **Default role**
to `member`, click **Test connection**, then **Save**.

## 6. Turn the app on for users

In Google Admin, on the Modelux app page:

1. Under **User access**, click the tile and choose **ON for everyone**
   or **ON for certain organizational units / groups**.
2. Save. Propagation to end users takes a few minutes.

## 7. Verify domain + test

1. In Modelux **Settings → SSO**, add your email domain, publish the
   TXT record at `_modelux.<domain>`, and click **Verify**.
2. Open [app.modelux.ai/login](https://app.modelux.ai/login) in an
   incognito window → **Use SAML SSO** → enter your work email.

## 8. Turn on enforcement

Once the test user logs in successfully, toggle **Require SAML for all
members** in Modelux.

## SCIM provisioning

Google Workspace supports SCIM but auto-provisioning setup is less
common than Okta/Entra. Contact support@modelux.ai if you need help
wiring Google's SCIM client.

## Troubleshooting

- **"Clock skew"-style errors**: Google-signed assertions are valid for
  ~10 minutes. If your server clocks drift, verification fails. NTP
  usually handles this; check your server time matches real time within
  a few seconds.
- **Certificate mismatch**: Google rotates signing certs periodically.
  If users start failing to log in, re-download the certificate from
  Google and paste the new PEM into Modelux.
- **"No Primary email"**: some Google Workspace users (service
  accounts) don't have a primary email. Those can't use SSO — they
  weren't real users anyway.