API reference

OpenID Connect (OIDC)

Road supports OpenID Connect single sign-on, for both customer-facing identity and social login. OIDC is built on OAuth 2.0: an external identity provider (IdP) authenticates the user and issues a token that Road trusts. A business can connect its own customer IdP (WSO2, Auth0, Azure AD B2C), or let users sign in with Google, Apple, Facebook and other OIDC providers.

How OIDC works

  1. The user picks one of the configured OIDC providers.
  2. Road redirects them to that provider.
  3. They authenticate with the IdP (password, biometric, or multi-factor, whatever the IdP requires).
  4. The IdP issues an ID Token describing the authenticated user.
  5. Road verifies the token and reads the user's details, such as email and a unique identifier.
  6. If the user already exists in Road they are signed in; otherwise a new user is created.

OIDC on Road

Road's OIDC covers two cases:

  • Customer identity. A business authenticates its customers against an external OIDC IdP, with each Account mapping its own IdP login to a Road user.
  • Social login. Users sign in with an existing Google, Apple, Facebook or other OIDC account, so there is no separate Road password to manage, which suits consumer-facing products.

Before you start

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

OIDC is configured on the Provider's Social login page.

Configuring a provider

You can enable several OIDC providers at once; each one shows as a Log in with … button on the sign-in screen, so users choose how to authenticate. To add a provider:

  1. Supply its OIDC issuer discovery URL (the provider's .well-known/openid-configuration). Road reads the endpoints it needs from there.
  2. Create an application on the provider's side for Road, and enter the Client ID and Client Secret it issues on the Road configuration page.

Road reads user details from the provider's UserInfo endpoint, so the application must grant three scopes:

  • openid, for the user's unique identifier.
  • profile, for basic details such as name.
  • email, for the email address Road matches on.

Without those scopes Road cannot retrieve enough to match or create a user.