Build authentication requests

Implement the code that constructs authorization requests. Your authentication requests must include all required parameters and generate unique security values.

Implementation steps:

1. Generate unique security parameters (code verifier, state, nonce) using cryptographically secure random generation.

2. Derive code challenge from code verifier using SHA-256.

3. Store security parameters securely for later validation.

4. Construct authorization URL with all parameters.

5. Redirect users to Sovos Account authorization endpoint.

For complete request examples, check Authentication request examples. For details on generating security parameters, review Security mechanisms.

Manage authentication state

Track authentication state between authorization request and callback. Your application must store security parameters temporarily and retrieve them when handling the callback.

For Single Page Applications

Store security parameters in memory when initiating authentication:

• Code verifier (for PKCE verification)

• State value (for CSRF protection)

• Nonce value (for token validation)

Use JavaScript variables or application state management. When handling the callback, retrieve stored values to validate the response. Clear stored values after successful token exchange.

For backend applications

Store security parameters in session storage linked to the user session. When the callback arrives, retrieve values from session storage. Clear session data after successful authentication completes.

For more details, read the Security mechanisms article.

Handle authentication callbacks

Implement the code that receives and validates callbacks from Sovos Account after verification completes.

When authentication succeeds, Sovos Account redirects users to your redirect URI with query parameters:

https://your-app.com/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE_VALUE
            

Callback handling steps:

1. Extract the authorization code and state parameter from the callback URL.

2. Retrieve your stored state value.

3. Validate that the returned state exactly matches the stored value.

4. If validation fails, reject the callback and log the security violation.

5. If validation succeeds, proceed to token exchange.

Exchange authorization code for tokens

After receiving and validating the authorization code, exchange it for tokens by making a POST request to Sovos Account's token endpoint.

Retrieve the token endpoint URL from the discovery document at https://accounts.trust.sovos.com/.well-known/openid-configuration.

Required parameters for token exchange:

grant_type

Set to authorization_code to indicate you're exchanging an authorization code.

code

The authorization code from the callback.

redirect_uri

Must exactly match the redirect URI from your authorization request.

client_id

Your application's client ID.

client_secret

Your application's client secret.

code_verifier

The code verifier you generated for PKCE. For more details, read theSecurity mechanisms article.

Example token exchange request:

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

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://your-app.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=CODE_VERIFIER
            

Successful response includes:

• ID token: Contains verified user claims based on requested scopes.

• Access token: Authorizes API requests to Sovos Account services.

• Refresh token: Allows obtaining new access tokens (only if you requested offline_access scope).

• Token type: Typically "Bearer".

• Expires in: Access token lifetime in seconds.

Validate and extract user claims

After receiving tokens, validate the ID token and extract user claims.

ID token validation steps:

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 claim matches your client ID.

4. Confirm the token hasn't expired by checking the exp claim.

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

After successful validation, decode the ID token to extract user claims. Available claims depend on the scopes you requested:

• sub: Unique user identifier (always present).

• name, given_name, family_name, gender, birthdate: Profile information (if you requested profile scope).

• email, email_verified: Email information (if you requested email scope).

• phone_number, phone_number_verified: Phone information (if you requested phone scope).

• credential: Identity document information (if available with profile scope).

For complete details on token handling, storage, and refresh, check token management.

Handle errors

Implement error handling for each stage of the authentication flow. Provide clear error messages to users and log errors for troubleshooting.

Authorization request errors

If authorization request parameters are invalid, Sovos Account redirects to your redirect URI with error parameters instead of an authorization code:

• error: Error code (invalid_scope, invalid_request, unauthorized_client).

• error_description: Human-readable error description.

• state: Your state parameter (validate this matches).

Display appropriate error messages to users and log errors for troubleshooting.

Verification failures

If biometric verification fails, Sovos Account returns an error describing why verification didn't succeed. Allow users to retry verification or provide guidance on resolving common issues like poor fingerprint quality or incorrect card positioning.

Token exchange errors

If token exchange fails, the response includes an HTTP error status and error details in the response body:

• invalid_grant: Authorization code expired, already used, or invalid.

• invalid_client: Client authentication failed (wrong client ID or secret).

• invalid_request: Missing required parameters or PKCE validation failed.

• unauthorized_client: Client not authorized for this grant type.

Log these errors and prompt users to re-authenticate. For complete error code reference, go to status codes.

Token validation errors

If token validation fails (signature mismatch, expired token, invalid nonce, wrong audience), reject the token and restart authentication. Never use tokens that fail validation.

State validation errors

If the state parameter is missing or doesn't match your stored value, reject the callback immediately. This indicates a potential CSRF attack. Log these security violations for investigation.

Project errors

AMR errors

• Message: "invalid amr"

ACR errors

• Message: "invalid ACR"

Store errors

• Message: "context flow not found"

Context flow errors

• Message: "amr not found in workflow"

• Message: "unable to validate amr"

• Message: "no verification attempts remaining"

Context flow operation errors

• Message: "subject already set"

• Message: "credential already set"

• Message: "email already set"

• Message: "standard claims already set"

• Message: "unable to find step"

• Message: "error generating OnlineId session"

Login handler errors

• Message: "invalid login hint"

Session errors

• Message: "incomplete session configuration: missing URI or API Key"

Main error codes

Code	Name	Value
0	UNKNOWN_ERROR	"Unknown error"
1	HARDWARE_UNAVAILABLE	"Connection to Trust Connects failed or device not available"
2	CAMERA_UNAVAILABLE	"Camera device not available"
3	CHALLENGE_NOT_FOUND	"Challenge not found"
4	SERVICE_ERROR	"Service error"
5	TIMEOUT_ERROR	"Timeout error"
6	MAX_ATTEMPTS_REACHED	"Max attempts reached"
7	USER_REJECTED	"User rejected"
8	VERIFICATION_FAILED	"Verification failed"
9	SESSION_NOT_FOUND	"Session not found"
10	AUTH_STATUS_FAILURE	"Authentication status failure"

Hardware errors

SUCCESS_INITIALIZATION

"The initialization have been correct"

INCORRECT_SUBJECT

"The subject provided doesn´t match with the subject read from the card"

LOW_QUALITY

"The fingerprint quality is too low, please try again"

INCORRECT_SLOT

"The finger provided doesn't match with the selected slot"

VERIFICATION_DONE

"The verification has been completed successfully"

UNKNOW_FLOW

"Unrecognized verification type"

TIMEOUT_FINGERPRINT

"Reading time has expired"

START_READING_CARD

"Card code read has started"

FOCUSING

"Focusing on card code"

CODE_READ

"Card code reading completed"

START_READING_CHIP

"Chip card read has started"

CARD_READ_SUCCESSFULLY

"The card have been read successfully"

READ_CARD_FAILURE

"An error has occurred while trying to read the card"

CARD_NOT_READ

"CARD NOT READ. REMOVE THE CARD AND PLACE IT ON THE READER AND TRY AGAIN"

FINGERPRINT_READ

"A Fingerprint sample was read successfully"

MOC_TRUE

"Match on card result was positive"

INVALID_TRANSITION

"The transition required is not possible in the current machine status"

CREDENTIAL_ERROR

"An error has been detected in the credential field"

MAX_ATTEMPTS

"The verification was negative, attempts depleted"

HARDWARE_UNAVAILABLE

"Hardware device not available or connection failed"

Error response format

Errors are returned in the following format:

{
  "code": null,
  "state": "aPT6tMubhosoJjkI",
  "error": "urn:audits:01KGSKPY5DS48EQ439QS2ADKT2;USER_REJECTED",
  "errorDescription": "Authentication status failure"
}

Note:

The code field is null in error responses. The system assigns code values only to successful validations.

URN Pattern: urn:audits:<ID>;<ERROR_CODE>

Configure environments

Set up different configurations for User Acceptance Testing (UAT) and production environments. Store environment-specific values in configuration files or environment variables rather than hardcoding them.

UAT environment

Use these endpoints and credentials for testing:

• Authorization endpoint: https://accounts-uat.trust.sovos.com/oauth2/auth.

• Discovery endpoint: https://accounts-uat.trust.sovos.com/.well-known/openid-configuration.

• UAT client ID and secret.

• UAT redirect URIs (can include localhost).

Production environment

Configure production endpoints and credentials:

• Authorization endpoint: https://accounts.trust.sovos.com/oauth2/auth.

• Discovery endpoint: https://accounts.trust.sovos.com/.well-known/openid-configuration.

• Production client ID and secret.

• Production redirect URIs (must use HTTPS).

Configuration management

Store these values in environment-specific configuration:

• Client ID and secret.

• Authorization and token endpoint URLs.

• Discovery endpoint URL.

• Redirect URIs.

• Allowed scopes and workflows.

• Token refresh settings.

Never commit production credentials to source control. Use environment variables, secure configuration management systems, or encrypted configuration files.

Test your integration

Verify your integration works correctly before deploying to production. Test with the UAT environment first. Test all workflows, scopes, and error scenarios your application will encounter.

Successful authentication flow

Test the complete happy path:

1. Initiate authentication request with valid parameters.

2. Complete biometric verification successfully.

3. Verify callback includes authorization code and correct state parameter.

4. Confirm token exchange succeeds and returns all expected tokens.

5. Validate ID token signature and claims.

6. Verify tokens contain expected user claims based on requested scopes.

Security parameter validation

Test that security mechanisms work correctly:

• Test that callbacks with invalid or missing state are rejected.

• Verify ID tokens with invalid or missing nonce are rejected.

• Confirm PKCE validation works (token exchange fails with wrong code verifier).

• Test that expired authorization codes are rejected.

• Verify reused authorization codes are rejected.

For more details, read theSecurity mechanisms article.

Scope variations

Test different scope combinations and confirm each scope combination returns the expected claims in the ID token.

Workflow variations

Test each verification workflow your application uses.

Token management

Test token handling throughout the lifecycle.

Error scenarios

Test error handling for common failure cases:

• Test with invalid client credentials (wrong client ID or secret).

• Test with unregistered redirect URI.

• Test with invalid or unsupported scopes.

• Test verification failure handling (requires manual verification failure).

• Test network timeout handling.

• Test token validation failure scenarios.

• Verify appropriate user-facing error messages display.

• Confirm errors are logged correctly for troubleshooting.

Deploy to production

After successful testing, deploy your integration to the production environment. Monitor initial production authentications to confirm everything works as expected.

Troubleshooting common issues

If you encounter problems during implementation or after deployment, check these common issues and solutions.

Authorization code expired

Authorization codes expire within minutes and can only be used once. Exchange them for tokens immediately after receiving the callback.

Solution: Reduce time between callback and token exchange. Never store authorization codes for later use. If you receive this error frequently, check for network delays or slow processing in your callback handler.

State parameter mismatch

The state value in the callback doesn't match the state you sent in the authorization request.

Solution: Verify you store state values correctly and retrieve them accurately when handling callbacks. For SPAs, ensure state survives the redirect (store in sessionStorage if needed). For backend apps, check session storage is working. Confirm you're comparing states correctly (exact string match, case-sensitive).

PKCE validation failed

Token exchange fails with invalid_grant error indicating PKCE validation failure.

Solution: Verify you're sending the exact code verifier you used to generate the code challenge. Check your SHA-256 hashing implementation. Confirm base64url encoding is correct (not base64). Ensure the same code verifier isn't being reused across requests.

Token validation fails

ID token signature verification fails or claim validation fails.

Solution: Confirm you're using current public keys from Sovos Account's JWKS endpoint. Verify issuer claim matches expected value (https://accounts.trust.sovos.com for production). Check audience claim matches your client ID exactly. Ensure token hasn't expired. Verify nonce matches your stored value.

Redirect URI mismatch

Authorization request or token exchange fails with redirect URI mismatch error.

Solution: The redirect URI must be registered exactly with your client application. Check for trailing slashes, http vs https, different ports, or subdomain differences. The redirect URI in token exchange must exactly match the one in authorization request.

Invalid client credentials

Token exchange fails with invalid_client or unauthorized_client error.

Solution: Verify client ID and client secret are correct. Check you're using the right credentials for the environment (UAT vs production). Ensure credentials aren't corrupted or have extra whitespace. Confirm the client is authorized for authorization code grant type.

Scope not available

Authorization request fails or expected claims aren't returned.

Solution: Verify the scopes you're requesting are supported. Check scope parameter syntax (space-separated or plus-separated). Confirm your client application is authorized to request those scopes. Remember that openid scope is required.

Verification hardware not detected

Biometric verification fails because hardware isn't detected.

Solution: Confirm Sovos Trust Connect is running. Check that required hardware devices are connected. Verify device drivers are installed correctly. Review hardware compatibility in Integration requirements.

For additional troubleshooting support, contact your assigned Project Manager or go to Sovos Support.

Next steps

After successful deployment, consider these additional areas to enhance your integration:

• Review Status codes for comprehensive error code reference.

• Implement Token refresh for long-lived sessions.

• Set up monitoring and alerting for authentication failures and security violations.

• Plan for credential rotation and security maintenance.

• Review security mechanisms security mechanisms.

• Implement logout functionality to clear tokens and end sessions.

• Consider implementing silent authentication for better user experience.

• Review and optimize token storage strategies.