SSO Setup Overview

These guides walk you through connecting Routebase to your identity provider (IdP) with SAML 2.0. Where your IdP supports it, they also cover 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 before the connection exists. You paste them into your IdP, and 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, because users are created on first sign-in by just-in-time provisioning. You can also run 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, which carries 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, because 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 R as Routebase
    participant I as Your IdP

    R->>R: 1 · start the wizard — the Metadata step<br/>shows the Entity ID and ACS URL
    R->>I: Entity ID and ACS URL
    I->>I: 2 · create the SAML app with those values
    I->>R: its metadata URL or XML
    R->>R: 3 · finish the wizard → Draft
    R->>R: 4 · test sign-in, then Activate

Every guide follows the same sequence. Routebase's Entity ID and ACS URL are known before the connection exists, so you configure your IdP once, with the real values, and never enter placeholders:

1. In Routebase: run Settings → Single Sign-On → Create connection through the Protocol and Vendor steps. The Metadata step shows your Entity ID and ACS URL with copy buttons. Leave the wizard open.
2. In your IdP: create the SAML application and fill its Entity ID and ACS URL fields with those two values. Copy the IdP's metadata URL (or download its metadata XML).
3. Back in Routebase: paste the metadata into the Metadata step, confirm the Mapping step, and click Next. Routebase creates the connection in Draft status. The Test step repeats the Entity ID and ACS URL and adds a Connection ID for support.
4. In Routebase: run the test sign-in, then Activate.

If the Metadata step 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 first, or fill the IdP with placeholders and replace them once the Test step shows the final values.

What is optional

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

• SSO enforcement makes SSO mandatory 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 lets 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, covering every card, every field and every status badge, see Single Sign-On (SSO).

The provider guides are text-only because each provider console changes on its own schedule, and the Routebase-side steps are shown with screenshots on Single Sign-On (SSO).