SSO Setup

Microsoft Entra ID SSO Setup

You need: the Application Administrator or Cloud Application Administrator role in Microsoft Entra ID (formerly Azure AD), and the Owner or Admin role in a Routebase organization on the Enterprise plan.

Time: about 25 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 Enterprise Application in Entra ID

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

  1. In the Azure portal, go to Entra ID → Enterprise applications → New application → Create your own application.

  2. Name: Routebase. Choose Integrate any other application you don't find in the gallery.

  3. Open the application and go to Single sign-on → SAML.

  4. Basic SAML Configuration → Edit:

    • Identifier (Entity ID): urn:placeholder (replaced in step 3)
    • Reply URL (ACS URL): https://example.com/placeholder (replaced in step 3)
    • Sign on URL: leave blank

  5. Attributes & Claims → Edit:

    • Unique User Identifier (Name ID): user.userprincipalname, format Email address.
    • Additional claims:
      • emailaddress → user.userprincipalname
      • givenname → user.givenname
      • surname → user.surname

    Map email to user.userprincipalname, not user.mail. Users without a mailbox have no mail value, and an assertion with no email is rejected — those users would fail to sign in while everyone else works. This is the single most common Entra misconfiguration.

  6. Group claims — only needed if you plan to map Entra groups to Routebase roles. Entra sends no group claim by default, and its default source emits object IDs rather than names:

    • Click Add a group claim.
    • Which groups: Security groups emits all of the user's security groups. Choose Groups assigned to the application only if you also assign those groups under Routebase → Users and groups — otherwise it emits nothing.
    • Source attribute: select Cloud-only group display names, and tick the "Emit group names for cloud-only groups" checkbox. The dropdown alone is not enough — without the checkbox Entra still sends group object IDs (GUIDs), which never match name-based mappings.
    • Leave the claim name at its default http://schemas.microsoft.com/ws/2008/06/identity/claims/groups; the Microsoft Entra ID preset in Routebase already points its groups field at it.
    • Save. Claim changes only reach a fresh sign-in — a silent token refresh does not pick them up.

  7. Under SAML Certificates → SAML Signing Certificate, copy the App Federation Metadata Url. A metadata URL is preferable to a downloaded XML file: Routebase re-reads it, so certificate rotations in Entra do not break your sign-ins.

  8. Under Users and groups → Add user/group, assign at least one test user.

2. Create the connection in Routebase

  1. Go to Settings → Single Sign-On and click Create connection.
  2. Protocol: SAML 2.0.
  3. Vendor: Microsoft Entra ID. This preselects the attribute mapping for Entra's claim URIs.
  4. Metadata:
    • Connection name: something that identifies the IdP and the environment, e.g. Acme Entra ID Production. Only admins ever see it.
    • IdP metadata URL: paste the App Federation Metadata Url from step 1.
  5. Mapping: confirm the claim names match what you configured in Attributes & Claims. 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 Entra ID

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

Routebase field Entra field
Entity ID Basic SAML Configuration → Identifier (Entity ID)
ACS URL Basic SAML Configuration → Reply URL (Assertion Consumer Service URL)

In the Azure portal, open the application → Single sign-on → SAML → Basic SAML Configuration → 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 Entra user assigned to the application.
  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 Entra ID.

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

Entra ID provisions against Routebase's SCIM 2.0 endpoint natively.

  1. In Routebase, go to Settings → Single Sign-On → SCIM Provisioning Tokens → New token. Name it Entra ID Production and copy the token immediately — it is shown once.
  2. In Entra, open the Routebase application → Provisioning → Get started.
  3. Provisioning Mode: Automatic.
  4. Tenant URL: https://api.routebase.dev/scim/v2/<your-org-slug> — your organization slug is the one that appears in your Routebase URLs.
  5. Secret Token: the token from step 1.
  6. Click Test Connection. Entra should report success.
  7. Under Mappings → Provision Microsoft Entra ID Users, push at least:
    • userName → userPrincipalName
    • emails[type eq "work"].value → mail or userPrincipalName
    • name.givenName → givenName
    • name.familyName → surname
    • active → Switch([IsSoftDeleted], , "False", "True", "True", "False")
  8. Under Settings, set Scope to Sync only assigned users and groups for the safest rollout.
  9. Set Provisioning Status to On and save.

Entra's initial sync runs within roughly 40 minutes; Provision on demand forces a single user through immediately.

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

7. Optional: map Entra groups to Routebase roles

Once the group claim emits display names (step 6 of section 1) or you push SCIM groups, open Settings → Single Sign-On → Group Role Mappings.

  • The external group name must match the group name Entra sends, e.g. routebase-developer — not its object ID. 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. If someone lands on the default unexpectedly, the group claim is almost always still emitting GUIDs or not being sent at all — recheck the checkbox in step 6.
  • 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.

Other providers: Okta · Google Workspace · OneLogin · Ping Identity · Troubleshooting