Documentation

Google SAML Setup

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

Suggest Edits

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.

  1. Click on Add App, then Add custom SAML app.

  1. Name your SAML app Opal. You can use this brand asset as the app icon. When ready, click Continue.
  2. Copy the value of the SSO URL field.
  3. 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.
2262 2262
  1. Download the Google IDP public certificate by clicking the down arrow icon next to the certificate.

  1. In Opal, upload the certificate with the Upload Certificate button.
2262
  1. Click Save Changes to save this data to Opal.
  2. 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.

  1. Click Continue.
  2. 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

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

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.
804
  1. 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.

  1. This should prompt you to log in with Google.
  2. 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.

Updated 3 days ago