Integrations · SAML 2.0

Google Workspace SSO

Configure Clavex as an external SAML 2.0 Identity Provider for Google Workspace. Once active, all Workspace accounts (Gmail, Drive, Meet, Calendar…) are gated by Clavex login — including MFA, passkeys, and eID methods.

Protocol: SAML 2.0, SP-initiated (Google initiates the flow) and IdP-initiated (Clavex-side deep link). Google does not support OIDC as an external IdP — SAML is the only option for Workspace SSO.

Prerequisites

Google Workspace Super Admin access
A verified domain in Google Workspace (e.g. acme.eu)
Clavex running with a public HTTPS endpoint (e.g. https://id.acme.eu)
An organization slug in Clavex — we use acme throughout this guide

Step 1 — Retrieve Clavex SAML Metadata

Clavex exposes its IdP metadata at a well-known URL. Download it — you will upload it to Google Admin in Step 3.

bash

# Replace "acme" with your organization slug and your Clavex domain $ curl https://id.acme.eu/acme/saml/idp/metadata \ -o clavex-idp-metadata.xml
# Verify the metadata contains your entity ID and SSO URL $ grep -E 'entityID|Location' clavex-idp-metadata.xml entityID="https://id.acme.eu/acme/saml" Location="https://id.acme.eu/acme/saml/sso"

Key values from the metadata — you may need to enter these manually in the Google Admin UI:

Field	Value
Entity ID (Issuer)	`https://id.acme.eu/acme/saml`
SSO URL	`https://id.acme.eu/acme/saml/sso`
SLO URL	`https://id.acme.eu/acme/saml/slo`
Certificate	Download from `/acme/saml/idp/metadata`

Step 2 — Create a SAML App in Google Admin

Open admin.google.com → Apps → Web and mobile apps
Click Add app → Add custom SAML app
Set the app name to Clavex SSO and upload your logo (optional)
On the Google Identity Provider details screen, note down:
- SSO URL — you don't need this (Clavex is the IdP, not Google)
- Skip this screen; click Continue

On the Service provider details screen, enter:

Field	Value to enter
ACS URL	`https://id.acme.eu/acme/saml/acs`
Entity ID	`google.com/a/acme.eu`
Start URL	leave empty
Name ID format	`EMAIL`
Name ID	`Basic Information > Primary email`

Wait — isn't Google the SP here? Yes. In this setup Google is the SAML Service Provider and Clavex is the IdP. The ACS URL above is Clavex's Assertion Consumer Service, but we need Google's ACS URL to register the app on the Clavex side. See Step 3 below.

Step 3 — Register Google as SP in Clavex Admin

In the Clavex Admin Console, navigate to your organization → Identity Providers → SAML Service Providers → Add SP and fill in:

Admin API (curl)

# Register Google Workspace as a SAML SP in Clavex $ curl -X POST https://id.acme.eu/api/v1/organizations/acme/saml/sp \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "entity_id": "google.com/a/acme.eu", "acs_url": "https://google.com/a/acme.eu/acs", "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "sign_assertions": true, "encrypt_assertions": false }'

Step 4 — Upload Clavex Metadata to Google Admin

Back in Google Admin → your custom SAML app → Identity provider details
Click Upload metadata and upload the clavex-idp-metadata.xml file from Step 1
Click Continue, then Finish
Turn the app ON for all users (or a specific OU for testing)

Step 5 — Test the Login

bash

# IdP-initiated login deep link (open in browser) https://id.acme.eu/acme/saml/initiate?entity_id=google.com/a/acme.eu
# SP-initiated: go to accounts.google.com — Google detects your domain # and redirects to Clavex automatically for users with @acme.eu addresses

Attribute Mapping

Google Workspace requires at minimum the NameID (email). Optional attributes:

Google attribute	SAML attribute name	Clavex claim
First name	`firstName`	`given_name`
Last name	`lastName`	`family_name`
Department	`department`	`department`
Title	`title`	`job_title`

Troubleshooting

Symptom	Likely cause	Fix
`app_not_configured_for_user` from Google	App not assigned to the user's OU	Google Admin → App → User access → turn ON for the OU
`SAML response does not match`	Entity ID mismatch	Ensure SP Entity ID in Clavex matches exactly `google.com/a/acme.eu`
Redirect loop at login	Clavex ACS URL wrong in Google	Verify ACS URL is `https://id.acme.eu/acme/saml/acs`
Clock skew error	Server time drift > 2 min	Run `chronyc tracking` and sync NTP on Clavex host
Certificate validation failure	Expired or rotated IdP cert	Re-upload Clavex metadata after rotating signing certificate