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

OneLogin SSO Setup

You need: the OneLogin Account Owner or Administrator role, 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.

Routebase has no OneLogin-specific vendor preset, so you pick Generic SAML in the wizard and enter the four claim names yourself. Everything else works exactly as with the presets.

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

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

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

2. Create the SAML application in OneLogin

  1. In OneLogin admin, go to Applications → Applications → Add App.

  2. Search for SAML Custom Connector (Advanced) and select it.

  3. Set the Display Name to Routebase, then save.

  4. Open the Configuration tab:

    OneLogin field Value
    Audience (EntityID) the Entity ID from section 1
    Recipient the ACS URL from section 1
    ACS (Consumer) URL the ACS URL from section 1
    ACS (Consumer) URL Validator a regular expression the ACS URL must match, as described below
    Login URL leave blank
    SAML signature element Response
    Encrypt assertion unchecked

    For the ACS (Consumer) URL Validator, build the expression from the ACS URL by escaping the regex metacharacters in it, which in practice are the dots, the slashes and the ?. Anchor the result with ^ and $. Do not use .* in production, because the validator exists precisely to stop the assertion being posted somewhere else.

  5. Open the Parameters tab and add these fields with Include in SAML assertion ticked. The names are case-sensitive and must match what you type in Routebase in section 3:

    Field name in the assertion Value
    email Email
    firstName First Name
    lastName Last Name
    NameID value (already present) Email

  6. Optionally add a groups parameter sourced from User Roles if you plan to map roles from OneLogin.

  7. Open the SSO tab and copy the Issuer URL, which is OneLogin's metadata URL. A metadata URL is preferable to a downloaded XML file, because Routebase re-reads it, so certificate rotations in OneLogin do not break your sign-ins.

  8. Assign at least one test user to the app under Users → Applications.

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 OneLogin Production. Only admins ever see it.
  2. Paste the OneLogin Issuer URL from section 2 into IdP metadata URL.
  3. Under Mapping, type the four claim names exactly as you set them in OneLogin, because Generic SAML has no preset. Those names 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 OneLogin, 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 a OneLogin user who has the app assigned.
  3. When the round-trip succeeds, click Activate.

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

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

OneLogin's outbound SCIM 2.0 with bearer authentication matches Routebase directly.

  1. In Routebase, go to Settings → Single Sign-On → SCIM Provisioning Tokens → New token. Name it OneLogin Production and copy the token immediately, because it is shown once.
  2. In OneLogin, open the Routebase app and go to the Configuration tab, then fill in three fields.
    • Set SCIM 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.
    • Leave SCIM JSON Template at the default.
    • Set SCIM Bearer Token to the token from step 1.
  3. On the Provisioning tab, tick Enable provisioning and enable Create user, Update user and Delete user.
  4. Set When users are deleted in OneLogin to Delete, and When user accounts are suspended in OneLogin to Suspend. Both deactivate the Routebase membership and revoke the user's sessions.
  5. Save, then assign users.

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

7. Optional: map OneLogin roles to Routebase roles

If you push OneLogin roles through the groups claim or through SCIM groups, open Settings → Single Sign-On → Group Role Mappings.

  • The external group name must match the name OneLogin 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 roles, have the user sign out fully and back in.

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