> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-docs/user-guide/trust-platform/sso-configurations/google.md).

# Google Workspace (SAML)

This guide explains how to configure SSO integration between Trust and Google Workspace. After configuring Google, return to the [Trust SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md) to complete the setup.

{% hint style="info" %}
**Before you begin:** Access Trust and copy the **Identifier** and **Reply URL** fields as described in [Step 2 of the SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-2-select-protocol-and-obtain-data).
{% endhint %}

## Prerequisites

* Administrator access to Google Workspace
* Administrator access to Trust
* Verified corporate email domain in Google Workspace

***

## SAML Configuration

### Create SAML Application in Google Workspace

1. Access the [Google Admin Console](https://admin.google.com)
2. Navigate to **Apps** → **Web and mobile apps**

<div data-with-frame="true"><img src="/files/Aq6LBOnZn8HDVIhSokQX" alt="Google - Add Web app"></div>

3. Click **Add app** → **Add custom SAML app**

<div data-with-frame="true"><img src="/files/FwFuRyOSjuBSLGWLVbhW" alt="Google - Add custom SAML app"></div>

4. Configure the **App name** (e.g., "Trust - Caf")
5. Optionally add an app icon and description
6. Click **Continue**

<div data-with-frame="true"><img src="/files/T2PL1kwzqFwOjCYM6Ej7" alt="Google - App Details"></div>

### Download Google IdP Information

1. On the **Google Identity Provider details** page
2. Click **Download Metadata** to save the metadata XML file

<div data-with-frame="true"><img src="/files/Xpzpxkqz199lf9zbs2Ox" alt="Google - IdP Details"></div>

{% hint style="info" %}
Note: Keep this metadata file safe. You'll need to either host it publicly or use Google's metadata endpoint URL in Trust.
{% endhint %}

3\. Click **Continue**

***

### Configure Service Provider Details

Configure the following fields:

| Google Field        | Value                                      |
| ------------------- | ------------------------------------------ |
| **ACS URL**         | Paste the **Reply URL** copied from Trust  |
| **Entity ID**       | Paste the **Identifier** copied from Trust |
| **Start URL**       | Leave blank (optional)                     |
| **Signed response** | Leave unchecked                            |
| **Name ID format**  | EMAIL                                      |
| **Name ID**         | Basic Information > Primary email          |

<div data-with-frame="true"><img src="/files/z9wVAjrmDlSUfT8OcYwF" alt="Google - Service Provider Details"></div>

Click **Continue**

***

### Configure Attribute Mapping

Map Google user attributes to SAML attributes that Trust expects:

Click **Add mapping** for each attribute:

| Google Directory attributes | App attributes |
| --------------------------- | -------------- |
| First name                  | `given_name`   |
| Last name                   | `family_name`  |
| Primary email               | `email`        |

<div data-with-frame="true"><img src="/files/e2GUmDcvYY4YVbQW17pW" alt="Google - Attribute Mapping"></div>

{% hint style="info" %}
**Note:** The \`name\` attribute can use **Primary email** as a fallback, or you can create a custom mapping that combines first and last name if needed.
{% endhint %}

## Configure Group Claim (Optional)

If you want to use custom group mapping:

1. In Group membership
2. Add Google groups
3. In **App attributes**, enter `groups`

<div data-with-frame="true"><img src="/files/pn19PV1AEpw03pxa56dN" alt="Google - Add Group Claim"></div>

{% hint style="warning" %}
**Important:** Google can send either group email addresses (e.g., \`<admins@company.com>\`) or group names (e.g., \`Admins\`) in the groups claim, depending on your SAML app configuration. You will need to map the corresponding values in Trust.

Only groups that the user is a direct member of will be included. Nested group memberships may not be sent depending on your Google Workspace configuration.
{% endhint %}

4\. Click **Finish**

***

### Enable the Application for Users

1. In the app details page, click **User access**

<div data-with-frame="true"><img src="/files/X9isWUJt867EGlH965eq" alt="Google - User Access"></div>

2. Select **ON for everyone** or choose specific organizational units
3. Click **Save**

***

### Host Metadata URL

1. Download the metadata XML file from the Google Identity Provider details page
2. Host it on a publicly accessible URL (e.g., your web server or cloud storage)
3. Use that URL as the Metadata URL in Trust

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>Important:</strong> The metadata URL must be publicly accessible for Trust to retrieve the configuration.</p></div>

***

## Configure in Trust

After configuring Google Workspace, return to the [Trust SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-2-select-protocol-and-obtain-data) and configure:

| Trust Field      | Value                               |
| ---------------- | ----------------------------------- |
| **Protocol**     | SAML                                |
| **Metadata URL** | Paste your hosted metadata file URL |

**Attribute Statements:**

| Trust Attribute       | Claim Value                                 |
| --------------------- | ------------------------------------------- |
| **E-mail**            | `email`                                     |
| **Name**              | `email` (or custom attribute if configured) |
| **Given Name**        | `given_name`                                |
| **Family Name**       | `family_name`                               |
| **Groups** (optional) | `groups`                                    |

***

## Next Steps

After configuring Google and Trust, complete the setup:

1. [Configure Properties and Scopes](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-2-select-protocol-and-obtain-data)
2. [Configure Permission Groups](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-3-configure-permission-groups)
3. [Configure Attribute Statements](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-4-configure-attribute-statements)
4. [Configure Domains](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-5-configure-domains)
5. [Save and Test](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-6-save-and-test)

***

## Troubleshooting

| Problem                     | Probable Cause                        | Solution                                                                     |
| --------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| ACS URL error               | URI does not match                    | Verify that the ACS URL in Google matches the Reply URL from Trust           |
| User not authorized         | App not enabled for user              | Enable the app for all users or specific organizational units in User Access |
| Invalid SAML response       | Attribute mapping incorrect           | Verify attribute mappings in Google Admin Console                            |
| Certificate error           | Certificate expired or invalid        | Download new metadata from Google and re-host it                             |
| Metadata URL not accessible | Metadata file not publicly accessible | Ensure the metadata file is hosted on a publicly accessible URL              |
| Domain restriction          | User domain not verified              | Verify the corporate domain in Google Workspace                              |
| Name ID error               | Name ID format incorrect              | Ensure Name ID format is set to EMAIL and mapped to Primary email            |

***

## References

* [Google Workspace - SAML SSO](https://support.google.com/a/answer/6087519)
* [Google Workspace - Custom SAML Applications](https://support.google.com/a/answer/6087519)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-docs/user-guide/trust-platform/sso-configurations/google.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.