Guide: Using SlashID as an OIDC Provider

Introduction

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.

info

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

IdP

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 'https://api.slashid.com/oauth2/clients' \
--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": ["https://api.example.com/oauth/callback"]
}'

info

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: https://api.slashid.com/.well-known/openid-configuration or, for the sandbox environment, https://api.sandbox.slashid.com/.well-known/openid-configuration
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 Factor	AMR values
webauthn	pop
email_link	email, token
sms_link	sms, token
otp_via_email	email, code
otp_via_sms	sms, code
oidc	oidc
saml	saml
api	N/A
direct_id	token
password	pwd

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.

info

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

SlashID supports the following ACR values:

ACR	Description	Example Authentication Factors
`0`	No user initiated-authentication	`[]`, `[direct_id]`, `[api]`
`urn:slashid:acr:1fa:any`	Any single authentication factor	`[password]`, `[webauthn]`, `[email_link]`, `[oidc]`
`urn:slashid:acr:1fa:pwd`	Single password authentication factor	`[password]`
`urn:slashid:acr:1fa:comms`	Single magic link or OTP authentication factor	`[email_link]`, `[otp_via_sms]`
`urn:slashid:acr:1fa:webauthn`	Single webauthn authentication factor	`[webauthn]`
`urn:slashid:acr:2fa:any`	Any two authentication factors	`[password, otp_via_email]`, `[webauthn, sms_link]`
`urn:slashid:acr:2fa:webauthn`	Any two authentication factors, one of which must be webauthn	`[webauthn, password]`, `[otp_via_email, webauthn]`

info

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.

Introduction​

1. Create an OAuth credential pair​

2. Configure OAuth credentials in your SDK/library​

Advanced options​

API Endpoints for OIDC​

ACR and ACM values​

ID Token​

Introduction

1. Create an OAuth credential pair

2. Configure OAuth credentials in your SDK/library

Advanced options

API Endpoints for OIDC

ACR and ACM values

ID Token