Defined scopes

Sovos Account supports the following scopes:

openid

Indicates an OpenID Connect authentication request. This scope is required for all authentication requests.

profile

Provides access to basic profile information including name, birth date, gender, and credential details.

email

Provides access to email address and verification status.

phone

Provides access to phone number and verification status.

offline_access

Requests a refresh token that maintains authentication without requiring people to verify identity again.

Profile scope

The profile scope provides these claims:

• name: Person's full name.

• given_name: Person's first name.

• family_name: Person's last name.

• gender: Person's gender.

• birthdate: Person's date of birth.

When you request the profile scope during identity document verification, you also receive a credential claim with these fields:

• country: Country associated with the credential.

• issuer: Organization or authority that issued the credential.

• type: Type of credential (for example, national ID, passport, driver's license).

• subject: Unique identifier for the credential holder.

Email scope

The email scope provides these claims:

• email: Email address.

• email_verified: Email verification status.

Phone scope

The phone scope provides these claims:

• phone_number: Phone number.

• phone_number_verified: Phone number verification status.

Scopes in your request

Choose which information your application needs. Then, include the scope parameter in your authentication request with your selected scopes:

Basic authentication

Request only the openid scope for minimal information. This provides basic authentication without additional profile data:

scope=openid

Authentication with profile information

Request the openid and profile scopes to access name, birth date, gender, and credential information from identity documents:

scope=openid profile

Authentication with profile and email

Request the openid, profile, and email scopes to access profile information plus email address and verification status:

scope=openid profile email

Full information with offline access

Request all available scopes to access user information including profile data, email address, phone number, and refresh tokens:

scope=openid profile email phone offline_access

Available verification methods

Sovos Account supports these verification methods:

FPT (Fingerprint validation)

Validates the fingerprints against a centralized database. This method compares the captured fingerprint with stored fingerprint records to confirm identity.

SC (Smart Card validation)

Uses Match-on-Card (MOC) technology to compare biometric data stored directly on a smart card with a live fingerprint. The comparison happens on the card itself, ensuring the physical card matches the digital data.

FACE (Facial recognition)

Verifies identity by analyzing facial features using facial recognition technology. This method captures and compares facial features to confirm identity.

Single and multiple methods

You can use individual verification methods, or you can combine the methods to provide stronger security. Combining methods creates a verification workflow and people must complete two or more verification steps.

Available verification workflows

Sovos Account supports these verification workflows:

urn:acr:fpt

Validates identity using fingerprint comparison against a centralized database.

urn:acr:moc-fpt

Combines Match-on-Card (MOC) verification with fingerprint database validation.

urn:acr:online-id

Verifies identity using facial recognition against a document photo, using theSovos Online ID verification flow.

Required parameters

The client must specify the following parameters in the authorization request:

• response_type: Type of response expected (typically code).

• scope: Requested user information scopes.

• audience: Intended resource server for the token (optional but recommended for security).

Token types

Sovos Account returns different token types, each serving a specific purpose in your authentication flow.

ID token

A JSON Web Token (JWT) containing verified identity information. The ID token includes claims based on the scopes you requested during authentication. Your application decodes this token to extract user information like name, email, and credential data.

Important:

The ID token is designed for your application's use only. Never send ID tokens to other services or APIs.

Access token

A token that authorizes your application to make authenticated API requests to Sovos Account services. Include the access token in the Authorization header when calling protected endpoints.

Important:

Access tokens have limited lifetimes and expire after a defined period. Your application must handle expired access tokens by requesting new ones.

Refresh token

A long-lived token that allows your application to obtain new access tokens without requiring the user to authenticate again. Sovos Account only provides refresh tokens when you request the offline_access scope.

Important:

Refresh tokens remain valid for extended periods but can be revoked if necessary.

Token lifecycle

Tokens have limited validity periods that your application must respect:

• Each token includes an expiration time. Access tokens typically expire within hours, while refresh tokens remain valid for days or weeks. Your application should check token expiration before using tokens and handle expired tokens.

• Tokens become invalid when they expire, when users revoke access, or when Sovos Account detects security issues. Your application must handle invalid tokens by requesting new tokens or prompting users to re-authenticate.

• ID tokens use JWT format with three parts: header, payload, and signature. The payload contains the user claims. Access and refresh tokens use opaque formats that your application shouldn't attempt to decode or inspect.

Token refresh

When access tokens expire, use refresh tokens to obtain new ones without requiring user interaction. Refresh access tokens before they expire rather than waiting for API requests to fail. Consider refreshing tokens when they have 5-10 minutes of validity remaining.

To refresh tokens, make a POST request to Sovos Account's token endpoint with these parameters:

• grant_type=refresh_token: Indicates you're using a refresh token to obtain new tokens.

• refresh_token: Your refresh token.

• client_id: Your application's client ID.

• client_secret: Your application's client secret.

bash
POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET 

Sovos Account validates the refresh token and returns new tokens including a new access token and ID token. If you receive a new refresh token, discard the old one and use the new token for future refresh requests.

If a refresh token expires or becomes invalid, your application must initiate a new authentication flow to obtain new tokens, requiring user interaction.

Token storage

Store tokens securely to protect user information and prevent unauthorized access.

• For Single Page Applications: Store tokens in memory (JavaScript variables) rather than browser storage mechanisms like localStorage or sessionStorage. Memory storage prevents tokens from persisting across browser sessions and protects against cross-site scripting attacks.

  Note:

  When tokens are stored in memory, users must re-authenticate when they close the browser tab or refresh the page. Use refresh tokens to minimize re-authentication frequency while maintaining security.

• For backend applications: Store tokens in secure server-side session storage or encrypted databases. Never expose tokens to client-side code, logs, or error messages.

What not to do:

• Never include tokens in URLs or query parameters.

• Never log tokens in application logs or error tracking systems.

• Never store tokens in browser localStorage or sessionStorage for production applications.

• Never transmit tokens over unencrypted connections.

• Never share tokens between different applications or services.

Token validation

Validate tokens before using them to ensure they're authentic and haven't been tampered with.

1. Verify the token signature using Sovos Account's public keys.

2. Check that the issuer claim matches the Sovos Account issuer URL.

3. Verify that the audience (audience) claim matches your client ID.

4. Confirm the token has not expired by checking the exp claim.

5. Validate that the nonce claim matches the nonce you sent in the authorization request.

Most OpenID Connect libraries handle ID token validation automatically. If you validate tokens manually, ensure you perform all validation steps correctly.

• Access token validation: Access tokens use opaque formats that you cannot validate locally. Sovos Account validates access tokens when you make API requests. If an access token is invalid or expired, the API returns an error response.

• Obtaining public keys: Retrieve Sovos Account's public keys from the JWKS (JSON Web Key Set) endpoint listed in the discovery document at https://accounts.trust.sovos.com/.well-known/openid-configuration.

PKCE (Proof Key for Code Exchange)

PKCE protects the authorization code flow from interception attacks. This is critical for Single Page Applications that cannot securely store client secrets because they run in browsers where code is visible to users.

How PKCE works

Your application generates a random string called the code verifier. You create a code challenge by hashing the code verifier using SHA-256. When you send the authorization request, you include the code challenge. Sovos Account stores this challenge.

After verification completes and you receive the authorization code, you exchange it for tokens by sending both the authorization code and the original code verifier. Sovos Account hashes the code verifier and compares it to the stored code challenge. If they match, Sovos Account issues tokens.

This prevents attackers who intercept the authorization code from using it. Without the original code verifier, the intercepted code is useless.

Code verifier requirements

Generate a cryptographically random string between 43 and 128 characters long. Use only unreserved characters: uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), hyphen (-), period (.), underscore (_), and tilde (~).

Use your programming language's cryptographically secure random number generator. Never use predictable values or standard random functions that aren't cryptographically secure.

Code challenge derivation

Create the code challenge by applying SHA-256 hashing to the code verifier, then base64url-encoding the result. The code_challenge_method parameter must be set to S256 to indicate SHA-256 hashing.

Include both code_challenge and code_challenge_method=S256 parameters in your authorization request.

State parameter

The state parameter prevents cross-site request forgery (CSRF) attacks by ensuring that authorization callbacks come from requests your application initiated.

How state validation works

Your application generates a unique random value and includes it as the state parameter in the authorization request. You store this value temporarily.

After authentication completes, Sovos Account redirects people back to your application with the same state value included in the callback URL. Your application validates that the returned state matches the stored value.

If an attacker tries to trick users into authorizing malicious requests, the state values won't match and your application rejects the callback. This prevents attackers from injecting authorization codes from different sessions.

State value requirements

Generate a cryptographically random string at least 16 characters long. Longer values provide more security. Use characters that are URL-safe.

The state value should be unpredictable. Never use sequential numbers, user IDs, or other predictable patterns.

Nonce parameter

The nonce parameter prevents replay attacks by ensuring that ID tokens are issued in response to specific authentication requests your application made.

How nonce validation works

Your application generates a unique random value and includes it as the nonce parameter in the authorization request. You store this value temporarily.

Sovos Account includes the nonce value in the ID token it issues. When your application receives the ID token, you decode it and extract the nonce claim. You validate that this nonce matches the value you sent in the original request.

This ensures the ID token was issued specifically for your request and prevents attackers from reusing tokens from other authentication sessions.

Nonce value requirements

Generate a cryptographically random string at least 16 characters long. Use URL-safe characters.

Like state values, nonces must be unpredictable. Never use sequential values or patterns that attackers could guess.

Generating secure random values

All security parameters require cryptographically secure random values. Standard random number generators aren't secure enough for authentication.

Cryptographically secure generation

Use your programming language's cryptographically secure random number generator:

• JavaScript: crypto.getRandomValues() or crypto.randomBytes().

• Python: secrets module.

• Java: SecureRandom class.

• C#: RNGCryptoServiceProvider or RandomNumberGenerator.

Never use Math.random(), random.random(), or similar non-cryptographic random functions.

Minimum lengths

• Code verifier: 43-128 characters.

• State: 16+ characters (longer is better).

• Nonce: 16+ characters (longer is better).

Character sets

Use URL-safe characters to avoid encoding issues:

• Uppercase letters: A-Z

• Lowercase letters: a-z

• Digits: 0-9

• Special characters: hyphen (-), period (.), underscore (_), and tilde (~).

For code verifiers, you must use only these unreserved characters. For state and nonce, base64url encoding provides URL-safe output.

Security parameter lifecycle

Manage security parameters throughout the authentication flow to maintain security.

Generation timing

Generate all security parameters immediately before initiating the authorization request. Never generate them in advance and store them for future use.

Storage during authentication

Store security parameters temporarily while waiting for the authentication callback:

• Single Page Applications: Store in memory (JavaScript variables).

• Backend applications: Store in session storage or temporary database records.

Never store security parameters in cookies, localStorage, or other persistent storage.

Validation

Validate security parameters immediately when you receive the callback or tokens. Reject any requests where validation fails.

Disposal

Discard security parameters immediately after successful validation. Never reuse values across authentication requests.

Logging restrictions

Never log security parameters in application logs, error messages, or debugging output. This includes:

• Code verifiers and code challenges
• State values
• Nonce values

If you must log authentication flows for debugging, mask or omit these values.

Common security mistakes

Avoid these common errors that compromise authentication security:

Reusing security parameters

Generating security parameters once and reusing them across multiple authentication requests. This defeats the purpose of these security mechanisms. Generate new values for every request.

Using weak random values

Using predictable patterns, sequential numbers, or non-cryptographic random functions. Attackers can predict or brute-force weak values. Always use cryptographically secure random generation.

Skipping validation

Failing to validate returned state or nonce values, or accepting callbacks without these parameters. This leaves your application vulnerable to CSRF and replay attacks. Always validate all security parameters.

Insecure storage

Storing code verifiers, state, or nonce values in localStorage, cookies, or URLs. These storage mechanisms expose values to attackers. Use memory or secure session storage.

Logging sensitive values

Including security parameters in log files or error messages. Logs are often stored long-term and may be accessible to unauthorized users. Never log security parameters.

Insufficient code verifier length

Using code verifiers shorter than 43 characters. Short verifiers are easier to brute-force. Use the minimum length of 43 characters or longer.