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

Ping Identity SSO Setup

You need: the PingOne Identity Data Admin role (or PingFederate administrator access), 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.

This guide follows PingOne (cloud). PingFederate uses different screens but the same field names, and the Routebase side is identical.

Routebase has no Ping-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

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

  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 PingOne and replace them once the Test step shows the final values.

2. Create the SAML application in PingOne

  1. In the PingOne admin console, go to Connections → Applications → + Application.

  2. Choose Web App → SAML → Configure.

  3. Set the Application name to Routebase, then save and continue.

  4. On the Configuration step, choose Manually Enter and fill in five fields.

    • Set ACS URLs to the ACS URL from section 1.
    • Set Entity ID to the Entity ID from section 1.
    • Leave Sign-on URL blank.
    • Leave SLO endpoint blank.
    • Set Subject NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

  5. Add the Attribute Mappings. The outgoing claim names are case-sensitive and must match what you type in Routebase in section 3:

    PingOne attribute Outgoing claim name
    Email Address email
    Given Name firstName
    Family Name lastName

  6. Optionally add a groups claim sourced from Group Names if you plan to map groups to Routebase roles. Filter to a prefix such as routebase- so you are not leaking your whole group structure into an assertion.

  7. Save the application.

  8. On the application detail page, copy the Metadata URL. A metadata URL is preferable to a download, because Routebase re-reads it, so certificate rotations in Ping do not break your sign-ins. If your PingFederate instance exposes no public metadata URL, download the metadata XML instead. You then paste it into the IdP metadata XML field in section 3, and you have to re-paste it yourself after every certificate rotation.

  9. On the Access tab, assign the population or groups that should reach Routebase.

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 PingOne Production. Only admins ever see it.
  2. Paste the PingOne metadata URL from section 2 into IdP metadata URL. If you had to download the metadata instead, paste the XML into IdP metadata XML.
  3. Under Mapping, type the four claim names exactly as you set them in PingOne, 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 PingOne, 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 Ping user in the application's assigned population.
  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 Ping.

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

PingOne'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 PingOne Production and copy the token immediately, because it is shown once.
  2. In PingOne, open the Routebase application → Provisioning → Add Provisioning and choose SCIM Outbound.
  3. Fill in three fields.
    • Set SCIM 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 Authentication Method to OAuth 2 Bearer Token.
    • Set OAuth Access Token to the token from step 1.
  4. Click Test. PingOne should report success.
  5. Map at least these user attributes:
    • userName ← Email
    • emails[0].value ← Email
    • name.givenName ← Given Name
    • name.familyName ← Family Name
  6. Enable the Create, Update and Delete operations, and set the provisioning schedule. The default of five minutes is fine.

Users who leave the assigned population are deactivated in Routebase and their sessions are revoked.

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

7. Optional: map Ping groups to Routebase roles

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

  • The external group name must match the name Ping 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.

Other providers: Okta · Microsoft Entra ID · Google Workspace · OneLogin · Troubleshooting