API reference

SAML

Road supports SAMLv2 single sign-on so a company can connect its own identity provider (IdP) and let its people into Road with their corporate credentials. Access is managed in the company's directory, not in Road.

How SAML works

SAML brokers authentication between a Service Provider (SP), here Road, and an Identity Provider (IdP), the system that verifies the user. When a user tries to sign in, Road redirects them to the IdP; once the IdP has verified them it returns a signed SAML assertion confirming who they are, and Road grants access on the strength of it, with no separate Road password.

SAML on Road

SAML configuration is applied at the Account level: every user who authenticates through the configured IdP becomes a member of that Account. That makes it the right fit for a corporate customer that wants to manage employee access to Road, onboarding and offboarding, through its own directory.

Before you start

  • The person configuring it has the Account Administrator role.
  • SAML is enabled at the Provider (tenant) level by a Road administrator.

The SAML settings then live on the Organisation Profile Settings page, at https://dashboard.road.io/settings/account/organization/sso/saml.

Configuring the connection

The setup is SAMLv2 compliant and has been tested against Okta, Google Workspace and Microsoft Entra ID (formerly Azure AD). Any SAMLv2 IdP should work, provided it can sign the full response.

  1. Create the Road application in your IdP. Road's settings screen shows the EntityID and Assertion Consumer Service (ACS) URL to enter in the IdP. In return the IdP gives you a Sign-in URL and Signing Certificate, which you enter on the Road screen.
  2. Set the allowed email domains. Only users from the domains you list may sign in over SAML.
  3. Sign the whole response. Road requires the entire SAML response to be signed, not just the assertion; if only the assertion is signed, the sign-in is rejected.
  4. Optionally, disable password login. Turn off email and password sign-in so everyone must come through the corporate IdP.

Matching users

Road uses the SAML Subject.NameID as the user's unique identifier, and stores it on the User's externalId. Configure the IdP to send a stable, persistent value here, such as an internal user ID, rather than an email address, which can change.

Provisioning

Road does not support SCIM. Users are onboarded in one of two ways:

  • Pre-provision over the API. Create users ahead of time with their externalId set to the Subject.NameID the IdP will send. See Providers, accounts and users.
  • Provision on first login. With autoprovisioning enabled (it is off by default), Road creates the user the first time they sign in successfully.

When you autoprovision, you can also assign roles from SAML attributes. Road maps an IdP attribute to a role by matching on equals, exists or contains, so, for example, a Billing group and a Technical Administrator group can land on different Road roles, and new users get the right role without manual setup.