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

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

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

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

  3. Display Name: Routebase. Save.

  4. Open the Configuration tab:

    OneLogin field Value
    Audience (EntityID) urn:placeholder (replaced in step 3)
    Recipient https://example.com/placeholder (replaced in step 3)
    ACS (Consumer) URL https://example.com/placeholder (replaced in step 3)
    ACS (Consumer) URL Validator .* for now (replaced in step 3)
    Login URL leave blank
    SAML signature element Response
    Encrypt assertion unchecked

  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 configure in Routebase in step 2:

    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 — this is OneLogin's metadata URL. A metadata URL is preferable to a downloaded XML file: 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.

2. Create the connection in Routebase

  1. Go to Settings → Single Sign-On and click Create connection.
  2. Protocol: SAML 2.0.
  3. Vendor: Generic SAML.
  4. Metadata:
    • Connection name: something that identifies the environment, e.g. Acme OneLogin Production. Only admins ever see it.
    • IdP metadata URL: paste the OneLogin Issuer URL from step 1.
  5. Mapping: because Generic SAML has no preset, type the four claim names exactly as you set them in OneLogin — 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 OneLogin

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

Routebase field OneLogin field
Entity ID Audience (EntityID)
ACS URL Recipient
ACS URL ACS (Consumer) URL

For the ACS (Consumer) URL Validator, OneLogin expects a regular expression that the ACS URL must match. Build it from the ACS URL you just pasted by escaping the regex metacharacters in it — in practice the dots, the slashes and the ? — and anchoring it with ^ and $. Do not leave it at .* in production: the validator exists precisely to stop the assertion being posted somewhere else.

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 a OneLogin user who has the app assigned.
  3. When the round-trip succeeds, click Activate.

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

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

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 — it is shown once.
  2. In OneLogin, open the Routebase app → Configuration tab and fill in:
    • SCIM Base URL: https://api.routebase.dev/scim/v2/<your-org-slug> — your organization slug is the one that appears in your Routebase URLs.
    • SCIM JSON Template: leave at the default.
    • SCIM Bearer Token: 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 — 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 roles, have the user sign out fully and back in.

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