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

Okta SSO Setup

You need: Okta admin access, and the Owner or Admin role in a Routebase organization on the Enterprise plan.

Time: about 20 minutes for SSO, plus 10 for SCIM provisioning.

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.

1. Start the connection in Routebase and copy the two values

Okta needs Routebase's Entity ID and ACS URL, and Routebase needs Okta'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 Okta.

  1. Go to Settings → Single Sign-On and click Create connection.
  2. Choose SAML 2.0 as the Protocol.
  3. Choose Okta 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 Okta and replace them once the Test step shows the final values.

2. Create the SAML application in Okta

  1. In Okta admin, go to Applications → Applications → Create App Integration.

  2. Choose SAML 2.0, then Next.

  3. Under General Settings, set the App name to Routebase. A logo is optional.

  4. Fill in the SAML Settings fields.

    • Set Single sign on URL to the ACS URL from section 1.
    • Set Audience URI (SP Entity ID) to the Entity ID from section 1.
    • Set Name ID format to EmailAddress.
    • Set Application username to Email.

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

    Name Name format Value
    email URI Reference user.email
    firstName URI Reference user.firstName
    lastName URI Reference user.lastName

  6. Add a Group Attribute Statement, which you only need if you plan to map Okta groups to Routebase roles:

    Name Name format Filter
    groups URI Reference Matches regex routebase-.*

  7. Finish the wizard, then Assign people / groups to the application. At least one test user must be assigned.

  8. Open the application's Sign On tab and copy the Metadata URL. A metadata URL is preferable to a downloaded XML file, because Routebase re-reads it, so certificate rotations in Okta do not break your sign-ins.

3. Finish the connection in Routebase

Back in the wizard, still on the Metadata step:

  1. Give the Connection name something that identifies the IdP and the environment, such as Acme Okta Production. Only admins ever see it.
  2. Paste the Okta metadata URL from section 2 into IdP metadata URL.
  3. Under Mapping, confirm the claim names match your Attribute Statements, which are email, firstName, lastName, and groups if you added it. 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 Okta, 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 an Okta user assigned to the application.
  3. When the round-trip succeeds, click Activate.

Your organization can now sign in through Okta. Existing users are prompted to link their accounts on their next sign-in.

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 Okta.

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. Optional: SCIM provisioning

SCIM is independent of SSO. Set it up only after SSO works.

  1. In Routebase, go to Settings → Single Sign-On and scroll to SCIM Provisioning Tokens. Click New token, name it Okta Production, and optionally set an expiry. Copy the token immediately, because it is shown once and only its prefix remains visible afterwards.
  2. In Okta, open the Routebase app → Provisioning → Configure API Integration → Enable API integration.
  3. Fill in two fields.
    • Set Base URL to https://api.routebase.dev/scim/v2/<your-org-slug>, where your organization slug is the one that appears in your Routebase URLs.
    • Set API Token to the token from step 1.
  4. Click Test API Credentials. Okta should report success.
  5. Under Provisioning → To App, enable Create Users, Update User Attributes and Deactivate Users.
  6. Map at least userName, email, givenName and familyName. Pushing groups is optional.

Assigning a user to the Okta app now provisions them into Routebase. Removing the assignment deactivates their membership and revokes their sessions.

To rotate a token without downtime, create the new one first, put it into Okta, confirm a sync, and only then revoke the old one. Both are valid until you revoke.

7. Optional: map Okta groups to Routebase roles

If you push groups through the SAML groups claim or through SCIM, open Settings → Single Sign-On → Group Role Mappings and add a mapping per group.

  • The external group name must match the name Okta 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. A silent token refresh does not re-read groups.

Other providers: Microsoft Entra ID · Google Workspace · OneLogin · Ping Identity · Troubleshooting