> 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-sp-google.md).

# Google as IdP for OpenIAM

Let users sign in to OpenIAM with their Google Workspace credentials.

**Goal:** users sign in to OpenIAM's portals with their Google credentials, via a custom SAML app in Google Workspace.\
**Time:** 45–75 minutes.\
**What this proves:** OpenIAM consumes Google assertions and matches them to existing users; both start directions work; cleanly removable.\
**Prerequisites:** [shared prerequisites](/getting-started-guide/federation.md); Google Workspace **super administrator** (required to create custom SAML apps); a test OU or access group. Low blast radius — adds a sign-in path; password login untouched.

One disambiguation up front: this is **SAML federation with a custom SAML app** — not "Sign in with Google" OAuth social login, which is a different OpenIAM feature configured under OAuth/OIDC.

## Values worksheet

| Name                                             | Example                                     | Yours |
| ------------------------------------------------ | ------------------------------------------- | ----- |
| Entity ID you choose for OpenIAM-as-SP           | `openiam-poc-sp-g`                          |       |
| OpenIAM ACS URL                                  | `https://<openiam-host>/idp/saml2/sp/login` |       |
| Provider ID (after step 2)                       | `3015`                                      |       |
| Google SSO URL / Entity ID / certificate         | from step 1                                 |       |
| Test user (primary Google email = OpenIAM email) | `fedtest4@poc.example.com`                  |       |

## Safety checks

{% hint style="warning" %}
Scope access with the app's OU/group controls — turn the app **ON only for the test OU or an access group**, never *On for everyone*, during the POC. Keep an OpenIAM password-login admin session open in a second browser. Google-side changes can take up to 24 hours to propagate but are typically fast.
{% endhint %}

{% stepper %}
{% step %}
**Create the custom SAML app in Google**

Google Admin console → **Apps → Web and mobile apps → Add App → Add custom SAML app**:

1. Name it (`OpenIAM POC`).
2. On the **Google Identity Provider details** page, download the **IdP metadata** (preferred — OpenIAM can import it), or copy the **SSO URL**, **Entity ID**, and **Certificate**.
3. Service provider details:

   | Google field         | Value                                                                                                                       |
   | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
   | ACS URL              | `https://<openiam-host>/idp/saml2/sp/login`                                                                                 |
   | Entity ID            | `openiam-poc-sp-g`                                                                                                          |
   | Start URL (optional) | leave empty (it sets the SAML RelayState — after login OpenIAM redirects to RelayState, defaulting to the portal)           |
   | Signed response      | leave **unchecked** — Google then signs the *assertion* only, which pairs with *Want Assertions Signed* on the OpenIAM side |
4. Name ID: keep the default — **primary email**.
5. Finish, then under **User access** turn the app **ON for the test OU** (or an access group; group access can span OUs).
   {% endstep %}

{% step %}
**Create the SAML Service Provider in OpenIAM**

**Access Control → Authentication Providers** → create a new provider → type **SAML Service Provider**. Fastest: **Import from Identity Provider Metadata** with the file from step 1. Target state:

| Field                                   | Value                                                                                          |
| --------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Provider Name                           | `Google login POC`                                                                             |
| Linked to Managed System                | default OpenIAM managed system                                                                 |
| SAML Issuer Name                        | `openiam-poc-sp-g` (must equal the Entity ID you gave Google)                                  |
| Sign-in page URL                        | the Google **SSO URL**                                                                         |
| SSO Binding                             | POST (default)                                                                                 |
| Name ID Format                          | Email Address                                                                                  |
| Want Assertions Signed                  | on                                                                                             |
| Signature section                       | Google's certificate as *Public Key for Validating Signatures* (filled by the metadata import) |
| Authentication policy / password policy | your defaults                                                                                  |
| Just-in-time provisioning groovy script | empty for the POC (unknown users rejected — proven in step 4)                                  |

Entitle the test users to the provider's resource via a role ([chooser](/getting-started-guide/federation.md)).

**The match:** Google sends the user's primary email as NameID; OpenIAM looks it up against user emails (must match exactly one), then resolves that user's login on the linked managed system. Contract: *Google primary email = OpenIAM user email.* Verify for `fedtest4` now.
{% endstep %}

{% step %}
**Validate**

* **SP-initiated:** private window → `https://<openiam-host>/idp/saml2/sp/login?issuer=openiam-poc-sp-g` → Google login → SelfService.
* **IdP-initiated:** as the test user, launch the app from the Google **app launcher** (it appears once access is ON); admins can also use the app's **Test SAML login** button. OpenIAM accepts unsolicited assertions (audience-based provider resolution; not compatible with encrypted assertions).

**Negative tests:** (a) a Google user in an OU where the app is **OFF** → blocked by Google (app not available/authorized); (b) an app-enabled Google user with **no matching OpenIAM user** → clean OpenIAM rejection; (c) matched but **un-entitled** → OpenIAM authorization error.
{% endstep %}
{% endstepper %}

## Evidence to capture

Both successful flows, the three negative errors, the app's User access screen (test OU only), the provider page.

## Rollback

Turn the app **OFF for everyone** (or delete it) in Google; deactivate or delete the OpenIAM provider. Password login was never affected.

## You know this worked when…

{% hint style="success" %}
`fedtest4` reaches SelfService via Google both ways, and the three negative tests fail at Google, at matching, and at entitlement respectively.
{% endhint %}

## If it failed

| Symptom                                         | Likely cause / where to look                                                                                            |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Google says the app isn't available to the user | App OFF for their OU/group, or propagation (up to 24 h)                                                                 |
| Google login OK, OpenIAM error                  | NameID (primary email) doesn't match exactly one OpenIAM user email; no login on linked managed system; or not entitled |
| Signature validation failure                    | Certificate mismatch — re-import the Google IdP metadata (Google rotates certs; note the expiry Google shows)           |
| Redirected to an unexpected page after login    | A Start URL was set in the Google app — it becomes the RelayState                                                       |
| Works from app launcher, not via the SP URL     | `issuer=` parameter doesn't equal the SAML Issuer Name exactly                                                          |

More: [Federation troubleshooting and recovery](/getting-started-guide/federation/troubleshooting.md). Next: [Brand the portals](/getting-started-guide/brand-the-portals.md), or [Where to go next](/getting-started-guide/where-to-go-next.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-sp-google.md?ask=<question>&goal=<user_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.