> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Google SAML Setup

> Learn how to configure Opal to authenticate users via Google SAML SSO.

Use this guide to configure Opal to allow or require users to log in with Google SAML SSO.

## Setup

1. When logged into Google Workspace as an administrator, select **Apps > Web and mobile apps** on the left sidebar.

<img src="https://mintcdn.com/opalsecurity/4Xj9diJ3E3kX-9Xd/images/docs/db29d41-setup_1.png?fit=max&auto=format&n=4Xj9diJ3E3kX-9Xd&q=85&s=f93dbccbb328a88504db800af02160dd" alt="" width="513" height="516" data-path="images/docs/db29d41-setup_1.png" />

2. Click on **Add App**, then **Add custom SAML app**.

<img src="https://mintcdn.com/opalsecurity/lt0M-hBs5yNe5ff5/images/docs/a63d993-setup_2.png?fit=max&auto=format&n=lt0M-hBs5yNe5ff5&q=85&s=25429c0b23b82c233ae475f54c29d720" alt="" width="1508" height="542" data-path="images/docs/a63d993-setup_2.png" />

3. Name your SAML app **Opal**. You can use [this brand asset](https://drive.google.com/uc?export=download\&id=17DAV1wD6Ldc4hPmrX1smq4i4s6w-1brL) as the app icon. When ready, click **Continue**.
4. Copy the value of the **SSO URL **field.
5. In the **Settings > Authentication** section of the Opal dashboard, click **Setup** and paste the **SSO URL** into the **Identity Provider SAML 2.0 SSO URL (HTTPS)** field.

<img src="https://mintcdn.com/opalsecurity/fu-nWazMe1LxLhxi/images/docs/20beaf800ff544c673c944779f499199d10da7e645a313c37fe5f4ceb37611b7-saml-sso-settings.png?fit=max&auto=format&n=fu-nWazMe1LxLhxi&q=85&s=38ff76310508ce2564b8d62ca7fec0ba" alt="2262" width="2722" height="1259" data-path="images/docs/20beaf800ff544c673c944779f499199d10da7e645a313c37fe5f4ceb37611b7-saml-sso-settings.png" />

<img src="https://mintcdn.com/opalsecurity/TlQj9FwRe9HHNEYB/images/docs/0b4aab981ffd6eebddbfc58d896ec7a3fbf1b7323c1c83c384058db0dfbe2428-opal-saml-sso.png?fit=max&auto=format&n=TlQj9FwRe9HHNEYB&q=85&s=b14ac19238074e4c1fc4871bbae2ba74" alt="2262" width="2972" height="1703" data-path="images/docs/0b4aab981ffd6eebddbfc58d896ec7a3fbf1b7323c1c83c384058db0dfbe2428-opal-saml-sso.png" />

6. Download the Google IDP public certificate by clicking the down arrow icon next to the certificate.

<img src="https://mintcdn.com/opalsecurity/fu-nWazMe1LxLhxi/images/docs/2b96db4-setup_4.png?fit=max&auto=format&n=fu-nWazMe1LxLhxi&q=85&s=ef6d70c913a6c0054038f7d5feb8fa08" alt="" width="1548" height="920" data-path="images/docs/2b96db4-setup_4.png" />

7. In Opal, upload the certificate with the **Upload Certificate** button.

<img src="https://mintcdn.com/opalsecurity/lt0M-hBs5yNe5ff5/images/docs/ad8fb82cddff2bd09218020bd8ee1fb47222766296d18ab12fbbff706d4f86f1-opal-saml-sso-upload-cert.png?fit=max&auto=format&n=lt0M-hBs5yNe5ff5&q=85&s=723d234dade70475f385ebce3e344c3e" alt="2262" width="2972" height="1703" data-path="images/docs/ad8fb82cddff2bd09218020bd8ee1fb47222766296d18ab12fbbff706d4f86f1-opal-saml-sso-upload-cert.png" />

8. Click **Save Changes** to save this data to Opal.
9. Open the **Setup** modal again and copy the **ACS URL **and **Entity ID** values. Go back to the Google SAML app creation page and paste these fields to the corresponding **ACS URL **and **Entity ID** fields.

<img src="https://mintcdn.com/opalsecurity/E-CmJXh0QNjZUl4g/images/docs/53119bd-setup_6.1.png?fit=max&auto=format&n=E-CmJXh0QNjZUl4g&q=85&s=670e89c27868e17c6695cf1188d12532" alt="" width="2526" height="756" data-path="images/docs/53119bd-setup_6.1.png" />

10. Click **Continue**.
11. In the **Attribute Statements** page, map the following **Google Directory** attributes to **App attributes**:

* **First name**: **given\_name**
* **Last name**: **family\_name**
* **Primary email**: **email**

<img src="https://mintcdn.com/opalsecurity/lt0M-hBs5yNe5ff5/images/docs/a205155-setup_7.png?fit=max&auto=format&n=lt0M-hBs5yNe5ff5&q=85&s=881e0040d6f82452cbf1ad1bd72e3271" alt="" width="2180" height="1232" data-path="images/docs/a205155-setup_7.png" />

12. Click **Finish** to complete the creation of the Google SAML app.
13. Turn on the SAML app by selecting **OFF for everyone** in the SAML app page, then **ON for everyone**, then **Save.**

<img src="https://mintcdn.com/opalsecurity/KunPWigry5GIeB5g/images/docs/5049985-setup_8.png?fit=max&auto=format&n=KunPWigry5GIeB5g&q=85&s=4ca5681dac32d28c3d343153c9d1f7f4" alt="" width="2302" height="1018" data-path="images/docs/5049985-setup_8.png" />

## Test login via SAML

1. Go to Opal, then log out of your Opal account.
2. Click on **Continue with SAML** on the Opal login screen.
3. Manually type your email address in the **Email field**. This email must have the same domain name as the user who created the SAML app in the Opal UI. For example, if `stephen@opaltest.com` created the SAML integration, the SAML integration will be tied only to users with the `opaltest.com` domain.
4. Click **Continue with SAML**. This should prompt you to log in with Google.
5. You may arrive at the following linking screen. If so, click **Continue** and log in with the account corresponding to your email address.

<img src="https://mintcdn.com/opalsecurity/TlQj9FwRe9HHNEYB/images/docs/0ac87fa-setup_10.png?fit=max&auto=format&n=TlQj9FwRe9HHNEYB&q=85&s=f97b0738eaf7974fd01b55d7c91f642c" alt="804" width="804" height="926" data-path="images/docs/0ac87fa-setup_10.png" />

7. At this point, you should be able to log into Opal.

## Test IDP-initiated flow from Gmail

1. Log in to Gmail.
2. On the upper right corner, click on the **Google Apps** dots icon, then **Opal**.

<img src="https://mintcdn.com/opalsecurity/CCjTTkaW-43B4efd/images/docs/f24d9a0-setup_11.png?fit=max&auto=format&n=CCjTTkaW-43B4efd&q=85&s=313a5987723844370a37b2dff6e9cbf3" alt="" width="924" height="600" data-path="images/docs/f24d9a0-setup_11.png" />

3. This should prompt you to log in with Google.
4. At this point, you should be able to log into Opal.

## Common issues

Adding a SAML connection in Google and enabling it for your users can take up to **24 hours** to propagate. As a result, there are occasionally caching issues after you add a new SAML connection.

Manifestations of this problem include the following errors:

* **403 app\_not\_configured**
* **403 not\_a\_saml\_app**
* **500**

In some cases, these caching issues can be circumvented by **clearing browser state** for Opal and Google, or attempting to log in using an incognito browser tab or a different browser. The most consistent fix is to wait up to 24 hours for the app to propagate.