For AI agents: the complete documentation index is at https://docs.routebase.dev/llms.txt. Every page is also available as Markdown by appending index.md to its URL or by sending Accept: text/markdown.
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. Start the connection in Routebase and copy the two values

Google needs Routebase's Entity ID and ACS URL, and Routebase needs Google's metadata. Both values on the Routebase side are known before the connection exists, so you start here and never have to enter placeholders in Google.

  1. Go to Settings → Single Sign-On and click Create connection.
  2. Choose SAML 2.0 as the Protocol.
  3. Choose Google Workspace as the Vendor. This preselects the attribute mapping for the names you configure in section 2.
  4. On the Metadata step, the wizard shows the Entity ID and ACS URL with copy buttons. Copy both, because you enter them in the next section. Leave the wizard open, since you come back to it in section 3.

If the wizard says the values are shown after this step instead, your organization already has a connection with the same name, such as an abandoned draft. Delete it under Settings → Single Sign-On and start again, or continue with placeholders in Google and replace them once the Test step shows the final values.

2. Create the custom SAML app in Google Admin

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

  2. Under 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 section 3. Click Continue.

  4. Fill in the Service provider details fields.

    • Set ACS URL to the ACS URL from section 1.
    • Set Entity ID to the Entity ID from section 1.
    • Set Name ID format to EMAIL.
    • Set Name ID to Basic Information > Primary email.

  5. Add these three Attribute mapping entries. The app attribute names are case-sensitive and must match what you confirm in Routebase in section 3:

    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, either for everyone or for the specific organizational units and groups that should reach Routebase.

3. Finish the connection in Routebase

Back in the wizard, still on the Metadata step:

  1. Give the Connection name something that identifies the environment, such as Acme Google Workspace. Only admins ever see it.

  2. Open the file you downloaded in section 2 and paste its full contents into IdP metadata XML, not into the URL field. The limit is 1 MB, which is 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.

  3. Under Mapping, confirm the claim names email, firstName and lastName. Email is required and the rest are optional.

  4. Click Next. Routebase creates the connection in Draft status and the Test step appears. It repeats the Entity ID and ACS URL you already entered in Google, and it adds a Connection ID, which 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, which 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, because 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, and the higher number wins. Give every mapping a distinct priority, because 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