Team & Settings

Single Sign-On (SSO)

With Single Sign-On, members of your organization sign in to Routebase through your company's identity provider (IdP) instead of individual passwords. Routebase supports SAML 2.0 — it works with Okta, Microsoft Entra ID, Google Workspace, OneLogin, Ping, and any other SAML-compatible IdP — plus SCIM 2.0 for automatic user provisioning. SAML connections and SCIM live on Settings → Single Sign-On (in the Security group of the settings sidebar), described as "Configure SAML connections, manage SSO enforcement, and provision users via SCIM." The verified domains that enforcement is based on sit on their own page, Settings → Domains, right above it.

SAML SSO and SCIM provisioning are available on the Enterprise plan — on lower plans the sidebar entry shows a lock icon and the page shows an upgrade card. Opening the page also requires the org:manage-security permission, which Admins and Owners have.

Setup at a glance

  1. Verify your email domain — prove you own acme.com via a DNS TXT record on Settings → Domains. That page needs no Enterprise plan; see Custom Domains.
  2. Create an SSO connection — walk through the connection wizard and exchange SAML metadata with your IdP.
  3. Test and activate — run a test sign-in, then flip the connection to Active.
  4. Optionally enforce SSO — require SSO for everyone whose email is on a verified domain.
  5. Optionally add SCIM — let your IdP create, update, and deactivate Routebase users automatically.

Step-by-step guides for your provider

Each guide covers the whole round trip — creating the SAML app in the IdP, running the Routebase wizard, pasting the Entity ID and ACS URL back, and the optional SCIM and group-mapping steps:

Using a different SAML 2.0 provider? Start from SSO Setup Overview and choose the Generic SAML vendor preset.

You can have one active connection at a time. While a connection is active, the Create connection button is hidden — disable the active one first if you need to set up a replacement.

Creating a connection

Click Create connection in the SSO Connections card. The Configure Single Sign-On wizard walks you through six steps:

Step What you do
Protocol Choose SAML 2.0. OIDC is shown but not yet available ("coming soon").
Vendor Pick Okta, Microsoft Entra ID, Google Workspace, or Generic SAML. Each preset pre-fills the attribute mapping for that vendor.
Metadata Name the connection and paste your IdP's metadata (URL or XML).
Mapping Map SAML assertion attributes to Routebase user fields.
Test Copy the Entity ID and ACS URL into your IdP, then run a test sign-in.
Activate Turn the connection on for your users.

Metadata

On the Metadata step, enter:

  • Connection name (required) — only visible to admins; use a name that identifies the IdP and environment, e.g. Acme Okta Production.
  • IdP metadata URL — preferred, because Routebase auto-refreshes it when your IdP rotates its signing certificates.
  • IdP metadata XML — paste the full XML (max 1 MB) if your IdP does not expose a public metadata URL (Google Workspace, for example, only offers a download).

The step includes vendor-specific guidance — where to create the SAML app in your IdP and where to find its metadata — with a collapsible Show step-by-step checklist.

The metadata exchange goes both ways: after this step, the wizard shows the Entity ID and ACS URL that you paste back into your IdP's SAML app configuration.

Attribute mapping

Map each Routebase user field to the claim name your IdP sends:

Field Required Notes
Email Yes Unique identifier. SSO login fails without it.
First name / Last name No Used for the profile display name.
Avatar URL No Optional profile picture URL from the IdP.
Groups claim No Comma-separated or JSON array. Used for Group → Role mapping.

Vendor presets fill these in for you. Two Microsoft Entra gotchas are flagged inline in the editor:

  • Map email to user.userprincipalname, not user.mail — users without a mailbox have no mail value and would fail to sign in.
  • For groups, configure the group claim to emit "Cloud-only group display names". By default, Entra sends group object IDs (GUIDs), which won't match name-based group mappings.

Test and activate

Moving past the Mapping step saves the connection in Draft status. The Test step then shows the connection's Entity ID, ACS URL, and Connection ID with copy buttons — make sure these are configured in your IdP — and an Open test login button that opens a test sign-in in a new tab. Complete the sign-in against your IdP to confirm the SAML handshake works end to end.

Finally, click Activate. Members of your organization can now sign in via your identity provider; existing users are prompted to link their accounts on their next login.

Managing connections

Each connection in the SSO Connections card shows its name, a status badge (Active, Draft, Disabled, or Error), its connection ID, when it was last used, and the last error message if something went wrong. Four actions are available per connection:

  • Manage — opens a details dialog with the read-only identity provider details (Entity ID, ACS URL, Connection ID, Metadata URL — all with copy buttons) and editable fields: name, metadata URL, metadata XML, signing certificate, attribute mapping, and the Just-in-time provisioning toggle ("Automatically create a Routebase user on first SSO login"). Metadata XML and the signing certificate are stored encrypted and never displayed — leave those fields blank to keep the current values.
  • Test — opens a test sign-in in a new tab, same as in the wizard.
  • Disable / Enable — temporarily turns the connection off without deleting it.
  • Delete — removes the connection after confirmation. Users will no longer be able to sign in with it; this cannot be undone.

Enforcing SSO

SSO enforcement is per verified domain: once a domain is verified, an SSO required switch appears next to it in the Verified domains card on Settings → Domains. Turning it on requires everyone whose email address is on that domain to sign in via SSO.

Existing members who currently use a password get a 14-day grace period. During it, a banner appears at the top of the app: "Single Sign-On will be required soon. Password login for your account will be disabled in N days." with a Link account button to connect their SSO identity. After the grace period — or when an enforced user tries to sign in with a password — they see a "Single Sign-On required" page with a Continue to sign in button that routes them through SSO.

If Just-in-time provisioning is enabled on the connection, users on a verified domain get a Routebase account automatically on their first SSO sign-in — no invitation needed. If it's disabled, only users who already have a membership (invited or SCIM-provisioned) can sign in.

Group role mappings

The Group Role Mappings card maps IdP groups (e.g. routebase-admins) to Routebase custom roles, so role assignment follows your directory. Click Add mapping and fill in:

Field Purpose
External group name Must match the group name your IdP sends in the groups claim (case-insensitive).
External group ID (optional) Stable IdP-side identifier that survives group renames.
Routebase role The custom role members of this group receive.
Team (optional) Also add matched users to a team.
Priority Higher number wins when a user is in multiple mapped groups.

Users who match no mapping fall back to the SSO connection's default role. Deleting a mapping doesn't change anyone immediately — existing members keep their current role until their next SSO login or SCIM update.

SCIM provisioning

SCIM 2.0 lets your IdP create, update, and deactivate Routebase users (and sync groups) automatically. Your organization's SCIM endpoint is:

https://api.routebase.dev/scim/v2/{your-org-slug}

Calls are authenticated with bearer tokens from the SCIM Provisioning Tokens card:

  1. Click New token, give it a name that identifies the IdP (e.g. Okta Production), and optionally set an expiry date — leave it blank for a non-expiring token you rotate manually.
  2. The full token is shown only once, in a copy dialog. Paste it straight into your IdP's SCIM configuration (it is sent as Authorization: Bearer ...). After you close the dialog, only the token prefix remains visible.
  3. Use Rotate to invalidate a token and get a fresh one (shown once, same as at creation), or Revoke to kill it permanently — provisioning calls signed with a revoked token fail immediately.

Each token row shows its prefix, when it was last used (or "Never used"), its expiry, and Revoked/Expired badges where applicable. Treat SCIM tokens like passwords: anyone holding one can provision and deprovision users in your organization.

SSO and SCIM are independent — you can run SSO with just-in-time provisioning and no SCIM, or both together.

Troubleshooting

  • Users can't sign in — check the connection's status badge (it must be Active) and the row's last error message, then run Test to reproduce the handshake yourself.
  • Sign-ins suddenly fail after working fine — your IdP may have rotated its signing certificate. Connections configured with a metadata URL refresh automatically; if you pasted metadata XML, open Manage and paste the updated XML.
  • Some Microsoft Entra users fail while others work — usually the email claim is mapped to user.mail and the failing users have no mailbox. Map it to user.userprincipalname instead.
  • Group mappings don't apply — verify your IdP sends group names (not object IDs) in the groups claim, and that the mapping's external group name matches exactly (matching is case-insensitive).
  • A user sees "Single Sign-On required" — their email domain has SSO enforcement turned on and they tried a password login. That's enforcement working as designed.
  • New users can't get in at all — if just-in-time provisioning is off, users need an existing membership (an invitation or a SCIM-provisioned account) before SSO sign-in succeeds.

The Audit Log records sign-in and membership events, which helps pin down when a failure started.

For a symptom-by-symptom walkthrough — including the SCIM error codes, a curl recipe to reproduce a provisioning failure, and why group mappings silently fall back to the default role — see SSO Troubleshooting.