Skip to main content

Quick start guide

Learn how to set up safe authentications using the Authentication Risk Indicator.

This quick start guide shows you how to:

  1. Prepare for testing authentications with Authentication Risk Indicator.
  2. Craft your authentication request.
  3. Perform end-user authentication.
  4. Review the risk assessment in the response.

Prerequisites​

The Authentication Risk Indicator is an add-on to the Signicat eID Hub. To start using this feature, you first need to have completed the following preparations:

  1. Follow the Quick start guide for the eID and Wallet Hub. In particular, make sure you:
    1. Get started with the Signicat Dashboard.
    2. Add an eID.
    3. Set up an authentication protocol.
  2. Activate the Authentication Risk Indicator with an onboarding manager or Signicat Sales.

End-user authentication flow​

Below, you can find a sequence diagram that outlines how a typical authentication flow with the Risk Indicator works.

Sequence diagram showing Authentication with the Risk Indicator

1. Authentication request​

To obtain a risk evaluation of an end-user authentication with the Authentication Risk Indicator, you need to specify a parameter in the authentication request.

How you specify the risk parameter varies per authentication protocol. Below, select the tab of the authentication protocol you use to connect your application.

Request example​

To start an end-user authentication with OIDC, you direct the end-user to the authorisation endpoint (https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize) with the appropriate set of parameters.

To request the Authentication Risk Indicator for an authentication session, you need to provide the risk scope in the authentication request.

scope=openid risk

The example below shows what an authentication request could look like.

Example: Authentication request with risk scope
https://<YOUR_SIGNICAT_DOMAIN>/auth/open/connect/authorize?
  &client_id=<OIDC_CLIENT_ID>
  &response_type=<GRANT_TYPE_CODE>
  &redirect_uri=https://myservice.example/redirect
  &scope=openid%20risk
  &code_challenge=ABC123
  &code_challenge_method=S256
  &state=12345
  &nonce=678910

2. User authenticates at the eID​

When the end-user navigates to the authentication URL, Signicat redirects the session to the eID method of choice. Here, the eID presents:

  • Login screen
  • Optional multi-factor challenge
  • Optional consent screen (including the custom risk scope)

If the user consents and authentication succeeds, the eID redirects the user back to your redirect_uri. You can then proceed to retrieve the authentication response and evaluate its content to assess the risk rating calculated.

3. Receive the authentication response​

Response example​

After an authentication session has been completed, your receive a response with authorisation code. You need to exchange this code in the request to the /token endpoint to obtain:

  • Access Token: Authorises access to APIs or UserInfo
  • ID Token: Proves the user has authenticated
  • Refresh Token

The token response contains an ID token. This token contains the core user identity claims for the scopes you requested in the authentication request, including those specific to the Authentication Risk Indicator.

After you read and validate the ID Token, you can retrieve the risk rating calculated by the risk engine, as part of the risk scope:

Example: Authentication response with risk rating
"risk": {
  "selfEvaluation": {
     "riskValue": "medium"
  }
}

Third-party eID processing and evaluation

Optionally, if the eID method used for authentication supports risk rating analysis, you will also receive a thirdPartyEvaluation object that contains:

  • riskValue: Rating calculated by the third-party eID service.
  • source: Name of the eID.
Example: Authentication response with third-party risk rating
"risk": {
  "thirdPartyEvaluation": {
    "riskValue": "high",
    "source": "sbid"
  }
}

4. Use the risk rating in your policy​

Depending on the returned rating, on your application side you might want to implement an access restriction policy, such as:

  • Allow login normally
  • Require additional verification (MFA)
  • Require stepped-up authentication
  • Flag suspicious activity
  • Restrict access

Once your application validates the ID Token and verifies any identity-fraud checks, you may redirect your end-users to start an authenticated session in your digital service.

On this page