SSO Setup Overview

These guides walk you through connecting Routebase to your identity provider (IdP) with SAML 2.0, and — where your IdP supports it — automatic user provisioning with SCIM 2.0.

Start here for the concepts and the prerequisites that apply to every provider, then follow the guide for yours.

When something does not work, SSO Troubleshooting is organised by symptom.

How the connection works

Routebase brokers SAML rather than terminating it directly. Your IdP connects to a Routebase-managed connection, which in turn issues the token Routebase's API trusts:

[Your IdP] --SAML--> [Routebase-managed SAML connection] --OIDC--> [Routebase]

Two things follow from this, and they explain most of what the guides ask you to do:

• You get one ACS URL and one Entity ID per organization. Both are generated by Routebase and shown in the connection wizard. You paste them into your IdP; you never invent them yourself.
• You can swap identity providers without changing anything on the Routebase side beyond the connection's metadata.

User provisioning is separate and does not go through the broker. SCIM clients talk to Routebase directly:

[Your IdP SCIM client] --Bearer token--> https://api.routebase.dev/scim/v2/<your-org-slug>/Users

You can run SSO without SCIM — users are created on first sign-in by just-in-time provisioning — or SCIM without SSO, which is rare but useful for headless directory sync.

Before you start

1. An Enterprise plan. SAML SSO and SCIM provisioning are Enterprise features. On lower plans the Single Sign-On entry in the settings sidebar carries a lock icon and the page shows an upgrade card.
2. The Owner or Admin role in your Routebase organization — specifically the org:manage-security permission.
3. A verified email domain. Go to Settings → Domains and prove ownership of the domain your users sign in with via a DNS TXT record. Verify it before you create the SSO connection: the connection captures your verified domains when it is saved, so that sign-ins from those domains get routed to your IdP. If you verify a domain later, open the connection and save it again to pick it up.
4. Admin access in your IdP — the exact role differs per provider and is named at the top of each guide.

The order that works

sequenceDiagram
    participant I as Your IdP
    participant R as Routebase

    Note over I,R: each side needs a value only the other can produce —<br/>which is why you visit your IdP twice

    I->>I: 1 · create the SAML app,<br/>ACS URL and Entity ID as placeholders
    I->>R: its metadata URL or XML
    R->>R: 2 · create the connection → Draft
    R->>I: the real Entity ID and ACS URL
    I->>I: 3 · replace the placeholders
    R->>R: 4 · test sign-in, then Activate

Every guide follows the same sequence, and the order matters. Routebase needs your IdP's metadata before it can create the connection, and your IdP needs Routebase's ACS URL and Entity ID, which only exist once the connection has been created. You therefore visit your IdP twice:

1. In your IdP: create the SAML application. Fill the ACS URL and Entity ID fields with any syntactically valid placeholder — you replace them in step 3. Copy the IdP's metadata URL (or download its metadata XML).
2. In Routebase: run Settings → Single Sign-On → Create connection through the Protocol, Vendor, Metadata and Mapping steps. Saving the Mapping step creates the connection in Draft status, and the Test step then shows your Entity ID, ACS URL and Connection ID.
3. Back in your IdP: replace the placeholders from step 1 with the real Entity ID and ACS URL.
4. In Routebase: run the test sign-in, then Activate.

What is optional

Everything past activation is opt-in and can be added later:

• SSO enforcement — require SSO for everyone on a verified domain. Existing password users get a 14-day grace period with an in-app banner before their password login stops working.
• SCIM provisioning — let your IdP create, update and deactivate Routebase users.
• Group role mappings — assign Routebase roles from IdP group membership.

For the full description of the settings page itself — every card, every field, every status badge — see Single Sign-On (SSO).

Screenshots

These guides are deliberately text-only. The bulk of each one happens inside a third-party admin console — Okta, the Azure portal, the Google Admin console — whose screens we do not control and which change on their own schedule. A screenshot of someone else's console ages badly and is worse than an accurate field name. The Routebase-side steps are covered visually on Single Sign-On (SSO).