> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/getting-started-guide/federation/openiam-idp-google.md). # OpenIAM as IdP for Google Workspace Make OpenIAM the identity provider for Google Workspace using SAML 2.0. **Goal:** users in one test OU (or group) of a Google Workspace tenant sign in to Google by authenticating at OpenIAM, via a third-party SSO profile.\ **Time:** 60–90 minutes.\ **What this proves:** OpenIAM issues assertions Google accepts, scoped safely to a test population; the profile is cleanly removable.\ **Prerequisites:** [shared prerequisites](/getting-started-guide/federation.md); Google Workspace tenant with super-administrator access; a test OU (or group) containing only test users. ## Values worksheet | Name | Example | Yours | | ------------------------------------------------------------------------------------------- | -------------------------- | ----- | | Test OU or group | `OU=/POC-SSO` | | | OpenIAM host | `openiam.poc.example.com` | | | Provider ID (after step 2) | `3013` | | | OpenIAM issuer (Response Issuer; default `https:///idp/saml2/idp/login/`) | | | | Google SP Entity ID (from the profile, step 1) | | | | Google ACS URL (from the profile, step 1) | | | | Test user (same primary email both sides) | `fedtest2@poc.example.com` | | ## Safety checks {% hint style="warning" %} **Blast radius control is the OU/group assignment.** SSO profiles apply to organizational units or groups — never assign the profile to the root OU during a POC, and there is no per-user assignment. {% endhint %} Also know your escape hatches before you start: 1. **Super admins bypass third-party SSO at `admin.google.com`** — they always sign in with Google credentials there, and the newer SSO profiles don't apply to super admins at all. That's your lockout escape hatch; protect those accounts with Google 2-Step Verification (Google's own recommendation, since they bypass your IdP). 2. Keep an admin console session open in a second browser throughout. 3. Test users hold no admin roles. {% stepper %} {% step %} **Create the SSO profile in Google (inactive until assigned)** Google Admin console → **Security → Authentication → SSO with third-party IdP** → add a SAML SSO profile: | Google field | Value | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | IDP entity ID | your OpenIAM issuer (worksheet; you can create the OpenIAM provider first if you prefer real values — the two steps reference each other) | | Sign-in page URL | `https:///idp/saml2/idp/login` | | Sign-out page URL | `https:///idp/saml2/idp/logout` | | Change password URL | `https:///selfservice` | | Verification certificate | upload the provider's signing certificate (**Download Signing Public Key** on the OpenIAM provider page) | All URLs must be HTTPS. After saving, Google displays this profile's own **Entity ID** and **ACS URL** — copy both into the worksheet; the OpenIAM provider needs them. **Do not assign the profile to any OU yet.** {% endstep %} {% step %} **Create the SAML Identity Provider in OpenIAM** **Access Control → Authentication Providers** → create a new provider → type **SAML Identity Provider**: | Field | Value | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Provider Name | `Google POC` | | Linked to Managed System | default OpenIAM managed system | | Assertion Consumer URL | the Google **ACS URL** from step 1 | | Request Issuer | the Google **SP Entity ID** from step 1 (the issuer Google sends in its AuthnRequests — OpenIAM finds the provider by it) | | Response Issuer | leave default; make sure the value Google holds as *IDP entity ID* matches it exactly | | Audiences | the Google **SP Entity ID** | | Name ID Format | Email Address — Google matches the NameID against the user's **primary Workspace email**, and with this format OpenIAM sends the user's default email address | | Signature | generate or upload; enable assertion signing | Entitle the test users to the provider's resource via a role (see the [chooser](/getting-started-guide/federation.md) — entitlement plus a login on the linked managed system). **The user's default email in OpenIAM must equal their Google primary email** — that is the matching contract for this journey; check it now on each test user's profile. Verify `https:///idp/saml2/idp/metadata/` returns XML. {% endstep %} {% step %} **Assign the profile to the test OU (the activating step)** Google Admin console → SSO with third-party IdP → **Manage SSO profile assignments** → assign your profile to the **test OU or group only** (a group assignment overrides the OU assignment). From this moment, those users' sign-ins redirect to OpenIAM. {% endstep %} {% step %} **Validate** Private window → `accounts.google.com` → enter `fedtest2@poc.example.com` → Google redirects to OpenIAM → authenticate → land in Gmail/Drive. (This journey is SP-initiated: Google always starts the flow.) **Negative tests:** (a) a Google user *outside* the test OU must get the normal Google password prompt — proves the scope held; (b) a test-OU user whose OpenIAM email ≠ Google primary email must fail after OpenIAM login — authentication vs. matching, observed; (c) an un-entitled user must be refused by OpenIAM. {% endstep %} {% endstepper %} ## Evidence to capture The profile's assignment screen (test OU only); the redirect and signed-in screenshots; all three negative results; the unassignment screenshot from rollback. ## Rollback Remove the profile assignment from the test OU (or set it to *None*) — those users immediately return to Google-credential sign-in. Delete the SSO profile once done. Deactivate or delete the OpenIAM provider. A locked-out state is recovered through the super-admin bypass at `admin.google.com`. ## You know this worked when… {% hint style="success" %} A test-OU user signs in to Google via OpenIAM, an outside-OU user is untouched, both mismatch tests fail in the expected place, and unassignment restores Google sign-in. {% endhint %} ## If it failed | Symptom | Likely cause / where to look | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | No redirect at Google | Profile not assigned to the user's OU, assignment still propagating, or the user is a super admin (bypass by design) | | Google error after OpenIAM login | NameID ≠ primary Google email — compare the OpenIAM default email with the Workspace primary email exactly | | OpenIAM error page | Request Issuer/Audience don't match the profile's SP Entity ID, or the user isn't entitled to the provider resource | | Certificate error at Google | Wrong or regenerated signing key — re-upload the current **Signing Public Key** to the profile | More: [Federation troubleshooting and recovery](/getting-started-guide/federation/troubleshooting.md). Next: [Entra ID as IdP for OpenIAM](/getting-started-guide/federation/openiam-sp-entra.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/getting-started-guide/federation/openiam-idp-google.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.