SSO Setup

Google Workspace SSO Setup

You need: the Super Admin role in Google Workspace, and the Owner or Admin role in a Routebase organization on the Enterprise plan.

Time: about 20 minutes.

Read SSO Setup Overview first for the prerequisites that apply to every provider — in particular, verify your email domain under Settings → Domains before you begin. That is normally your Workspace domain.

Google Workspace does not ship a SCIM client for third-party applications, so provisioning works differently here than with Okta or Entra ID. Section 6 covers the options.

1. Create the custom SAML app in Google Admin

Routebase needs Google's metadata before it can create a connection, so Google comes first. The ACS URL and Entity ID you enter here are placeholders — you replace them in step 3.

  1. In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.

  2. App details: name it Routebase. A logo is optional. Click Continue.

  3. On the Google Identity Provider details screen, download the metadata file. Google does not host a public metadata URL, so this XML file is what you paste into Routebase in step 2. Click Continue.

  4. Service provider details:

    • ACS URL: https://example.com/placeholder (replaced in step 3)
    • Entity ID: urn:placeholder (replaced in step 3)
    • Name ID format: EMAIL
    • Name ID: Basic Information > Primary email

  5. Attribute mapping — add these three. The app attribute names are case-sensitive and must match what you configure in Routebase in step 2:

    Google Directory attribute App attribute
    Primary email email
    First name firstName
    Last name lastName

  6. Click Finish.

  7. On the app overview, open User access and turn the service ON — for everyone, or for the specific organizational units and groups that should reach Routebase.

2. Create the connection in Routebase

  1. Go to Settings → Single Sign-On and click Create connection.

  2. Protocol: SAML 2.0.

  3. Vendor: Google Workspace. This preselects the attribute mapping for the names you configured in step 1.

  4. Metadata:

    • Connection name: something that identifies the environment, e.g. Acme Google Workspace. Only admins ever see it.
    • IdP metadata XML: open the file you downloaded in step 1 and paste its full contents here, not into the URL field. The limit is 1 MB, far above any real metadata document.

    Because Google gives you a static XML document rather than a URL, Routebase cannot re-read it. If Google rotates the app's signing certificate, download the metadata again and paste the new XML into the connection under Manage. Sign-ins fail until you do.

  5. Mapping: confirm the claim names (email, firstName, lastName). Email is required; the rest are optional.

  6. Click Next. Routebase creates the connection in Draft status and the Test step appears.

3. Paste the Routebase values back into Google

The Test step shows three values with copy buttons. Two of them go back into Google:

Routebase field Google field
ACS URL Service provider details → ACS URL
Entity ID Service provider details → Entity ID

In the Google Admin console, open the app → Service provider details → Edit, replace the two placeholders from step 1, and save.

The third value, Connection ID, is only useful when contacting support.

4. Test and activate

  1. Back in the Routebase wizard, click Open test login. A sign-in opens in a new tab.
  2. Sign in as a Workspace user who has the app enabled.
  3. When the round-trip succeeds, click Activate.

If the test fails, work through SSO Troubleshooting — it is organised by what the user actually sees.

5. Optional: require SSO for your domain

Go to Settings → Domains, find your verified domain, and turn on SSO required. Everyone whose email address is on that domain must then sign in through Google.

Existing password users are not locked out immediately: they get a 14-day grace period with an in-app banner and a Link account button. See Single Sign-On (SSO) for what the banner says and when it appears.

6. Keeping users in sync

Google Workspace has no built-in SCIM client for third-party apps, so there are three ways to keep Routebase aligned with your directory.

Just-in-time provisioning — the default

Do nothing. The first time a Workspace user signs in through SSO, Routebase creates their membership and applies any group role mappings. No tokens, no configuration.

What it does not do: suspending a user in Google does not deactivate them in Routebase. Their next SSO sign-in is blocked at Google's end, but an existing Routebase session stays valid until it expires. If you need a suspension in Google to deactivate the Routebase membership immediately, use one of the two options below.

A directory-sync job you run yourself

Poll the Google Directory API and push the changes to Routebase's SCIM 2.0 endpoint at https://api.routebase.dev/scim/v2/<your-org-slug>, authenticating with a token from Settings → Single Sign-On → SCIM Provisioning Tokens. Routebase implements the standard /Users and /Groups resources; the request and error formats are described in SSO Troubleshooting, which also has a curl recipe you can develop against.

An identity governance platform

Any IGA product that reads Google Directory and writes to a SCIM 2.0 endpoint with bearer authentication works. Point it at the same base URL and token as above.

7. Optional: map Workspace groups to Routebase roles

To send group membership in the SAML assertion:

  1. In the Google Admin console, edit the SAML app.
  2. Under Attribute mapping → Group membership, add the groups you want to expose. Filter to a prefix such as routebase- so you are not leaking your whole group structure into an assertion.
  3. Set the app attribute name to groups.

Then open Settings → Single Sign-On → Group Role Mappings in Routebase.

  • The external group name must match the name Google sends. Matching is case-insensitive.
  • Priority decides the winner when a user is in several mapped groups — higher wins. Give every mapping a distinct priority; ties are resolved arbitrarily.
  • Users matching no mapping fall back to the connection's default role.
  • Role changes take effect on the next sign-in, and re-evaluation is throttled to roughly five minutes per user. After changing groups, have the user sign out fully and back in.

Other providers: Okta · Microsoft Entra ID · OneLogin · Ping Identity · Troubleshooting