Skip to main content

Guide: Using SlashID as an OIDC Provider


Learn how to use SlashID to authenticate users with the OpenID Connect (OIDC) authorization code flow. This diagram shows a simplified version of the OIDC flow you'll implement.


A client in this context is any application or website the user is authenticating with.


1. Create an OAuth credential pair

First, you need to create OAuth client credentials in SlashID via our API. Here's an example:

curl --location '' \
--header 'SlashID-OrgID: <ORG ID>' \
--header 'Content-Type: application/json' \
--header 'SlashID-API-Key: <API KEY>' \
--data '{
"scopes": ["openid", "offline_access"],
"client_name": "oidc-testing",
"grant_types": ["authorization_code", "refresh_token"],
"redirect_uris": [""]

By default, SlashID enforces PKCE for the authorization code flow.

After authentication, the user may only be redirected to one of the redirect URIs registered with the client.

2. Configure OAuth credentials in your SDK/library

Now that you have set up an OAuth credential pair in SlashID, you will need to configure these settings in your Client.

  • Client ID: Public identifier of your OAuth application
  • Client Secret: Confidential secret used to authenticate your OAuth application (Public applications, i.e. mobile apps, don't have this)
  • Authorization URL: Used by the Client to request authorization from your user
  • Token URL: Used by the Client to retrieve tokens
  • Discovery URL: For SlashID, this is at: or, for the sandbox environment,
  • Scopes: OAuth scopes used to grant access to the Client. SlashID supports openid and offline_access, as well as custom scopes. If the openid scope is included in the authorization request, SlashID will return an ID token containing the information about the user. See below for more information. If the offline_access scope is included in the authorization request, SlashID will return a refresh token. The scopes in the request must be included in those registered with the client.

Advanced options

API Endpoints for OIDC

SlashID works out of the box with any OIDC-compliant SDK/library so no further setup is needed. However, if you manually want to interact

  • /oauth2/authorize for loading the authentication page
    • Accepts GET with query parameters, which can be used to enforce multi-factor authentication (MFA)
    • Accepts POST with form parameters. The parameters can be used to enforce MFA and Step-up Auth.
  • /oauth2/tokens for getting/refreshing tokens
  • /oauth2/tokens/introspect for inspecting tokens

ACR and ACM values

Authentication Context Class Reference (ACR) and Authentication Methods Reference (AMR) are optional ID token claims in the OpenID Connect specification to provide information about the strength of the authentication mechanism.

The value of the AMR claim is an array of strings, where each string represents a specific authentication method used during the authentication event.

SlashID supports the following AMR values:

  • pop: the user demonstrated proof of possession of a key
  • code: the user provided a single-use code
  • pwd: the user authenticated with a password
  • token: the user provided a single-use token
  • oidc: the user authenticated with a third-party OpenID Connect provider
  • saml: the user authenticated with a third-party SAML provider
  • email: the user demonstrated control of an email address
  • sms: the user demonstrated control of a phone number via SMS
  • mfa: the user authenticated with multiple factors
  • mca: the user authenticated via multiple channels

The mapping between SlashID authentication factors and AMR values is as follows:

Authentication FactorAMR values
email_linkemail, token
sms_linksms, token
otp_via_emailemail, code
otp_via_smssms, code

With the additional rules that:

  • If multiple factors were completed, the mfa value will be included in the AMR claim
  • If multiple channels were used (e.g., email and SMS, or email and WebAuthn), the mca value will be included in the AMR claim

The authorization request may include an acr_values parameter comprising a list of desired ACRs in order of preference. This can be used to request specific levels of assurance in the subsequent authentication. The ID token will then include an acr claim with the specific ACR value achieved during the authentication.


MFA can be enforced by supplying one of the 2fa:* ACRs in the acr_values parameter

SlashID supports the following ACR values:

ACRDescriptionExample Authentication Factors
0No user initiated-authentication[], [direct_id], [api]
urn:slashid:acr:1fa:anyAny single authentication factor[password], [webauthn], [email_link], [oidc]
urn:slashid:acr:1fa:pwdSingle password authentication factor[password]
urn:slashid:acr:1fa:commsSingle magic link or OTP authentication factor[email_link], [otp_via_sms]
urn:slashid:acr:1fa:webauthnSingle webauthn authentication factor[webauthn]
urn:slashid:acr:2fa:anyAny two authentication factors[password, otp_via_email], [webauthn, sms_link]
urn:slashid:acr:2fa:webauthnAny two authentication factors, one of which must be webauthn[webauthn, password], [otp_via_email, webauthn]

If the authorization request does not include the acr_values parameter, urn:slashid:acr:1fa:any will be used by default

ID Token

When a user authenticates with OIDC, SlashID generates an ID token, an access token, and a refresh token. The ID token contains information about the user and includes the following claims

"aud": "Audience", // The audience the token is intended for
"sub": "Subject", // The subject of the token (typically a user id)
"iss": "Issuer", // The issuer of the token
"jti": "JTI", // JWT ID, a unique identifier for the token
"iat": "IssuedAt", // The time at which the token was issued, in Unix timestamp format
"exp": "ExpiresAt", // The expiration time of the token, in Unix timestamp format
"nonce": "Nonce", // A string value used to associate a Client session with an ID Token (optional)
"rat": "RequestedAt", // The time at which the authentication request occurred, in Unix timestamp format (optional)
"auth_time": "AuthTime", // The time when the authentication occurred, in Unix timestamp format (optional)
"at_hash": "AccessTokenHash", // Access token hash value (optional)
"acr": "AuthenticationContextClassReference", // Authentication Context Class Reference (optional)
"amr": "AuthenticationMethodsReferences", // Authentication Methods References (optional)
"c_hash": "CodeHash", // Code hash value, not always populated (optional)
"prev_token_id": "PrevTokenID", // Previous Token ID if applicable (optional)
"oid": "OID", // Organization ID
"region": "Region", // Geographic region
"first_token": "FirstToken", // Indicates if this is the first token issued
"authentications": "Authentications", // Details about the authentication events (optional)
"gdpr_consent_levels": "GDPRConsentLevels", // GDPR consent levels (optional)
"groups_claim_name": "groups", // The claim name for groups (optional)
"groups": "Groups", // Groups the subject belongs to, not serialized into JSON
"custom_claims": "CustomClaims" // Additional custom claims not included in the standard claims (optional)

Custom claims can be added to the token using our webhooks.