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. Create the SAML application in Okta

Routebase needs Okta's metadata before it can create a connection, so Okta comes first. The ACS URL and Entity ID you enter here are placeholders — you replace them in step 3.

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

  2. Choose SAML 2.0, then Next.

  3. General Settings → App name: Routebase. A logo is optional.

  4. SAML Settings:

    • Single sign on URL: https://example.com/placeholder (replaced in step 3)
    • Audience URI (SP Entity ID): urn:placeholder (replaced in step 3)
    • Name ID format: EmailAddress
    • Application username: Email

  5. Attribute Statements — add these three. The names are case-sensitive and must match what you configure in Routebase in step 2:

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

  6. Group Attribute Statements — only needed 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: Routebase re-reads it, so certificate rotations in Okta do not break your sign-ins.

2. Create the connection in Routebase

  1. Go to Settings → Single Sign-On and click Create connection.
  2. Protocol: SAML 2.0.
  3. Vendor: Okta. This preselects the attribute mapping for the names you configured in step 1.
  4. Metadata:
    • Connection name: something that identifies the IdP and the environment, e.g. Acme Okta Production. Only admins ever see it.
    • IdP metadata URL: paste the Okta metadata URL from step 1.
  5. Mapping: confirm the claim names match your Attribute Statements (email, firstName, lastName, and groups if you added it). Email is required; the rest are optional.
  6. Click Next. Routebase creates the connection in Draft status and the Test step appears.

3. Paste the Routebase values back into Okta

The Test step shows three values with copy buttons. Two of them go back into Okta:

Routebase field Okta field
ACS URL SAML Settings → Single sign on URL
Entity ID SAML Settings → Audience URI (SP Entity ID)

In Okta, open the application → General → SAML Settings → Edit, replace the two placeholders from step 1, and save.

The third value, Connection ID, 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 — it 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: 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 — 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:
    • Base URL: https://api.routebase.dev/scim/v2/<your-org-slug> — your organization slug is the one that appears in your Routebase URLs.
    • API Token: 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 — higher wins. Give every mapping a distinct priority; 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