How to integrate with eID Hub - MitID

Overview

For a general overview of the integration process see How to integrate with eID Hub. It describes the steps that have to be done to integrate with any eID. This guide goes more into details specifically for the integration with MitID.

• Authentication / Signing flow
• UI customization
• Level of Assurance in MitID
• Authentication response validation
• Flow and CPR

Authentication / Signing flow

MitID security requirements demand the authentication to be done on a mitid.dk subdomain, which in our case is scrive.mitid.dk. Therefore the Service Providers are required to redirect their users to eID Hub frontend to perform the authentication (or signing).

This is how the flow between the end user, you (Scrive’s customer, or Service Provider, SP) and eID Hub’s backend and frontend looks like:

Three actions are required from SP to perform:

1. Call /transaction/new endpoint with parameters. MitID-specific parameters are the interface language, LoA level, display text and CPR. All parameters are optional for authentication, some are mandatory for signing. See API documentation for details.

2. Redirect the end-user to accessUrl returned by the above call.

3. Collect and verify the transaction details from /transaction/{t_id} after the user is redirected back to you, to redirectUrl, specified in step 1.

UI customization

eID Hub frontend, accessible at accessUrl, looks like the following image. The background color, logo and page title are customizable. SP name is set once you become Scrive’s customer and we register you with MitID as an SP.

Please contact our support if you want a customization.

Level of Assurance in MitID

MitID authentication is based on being able to specify the required assurance level before the actual authentication.

In eID Hub one can specify the required LoA level. This leads to end users who don’t have the required level not being able to authenticate (they’ll be shown an explanation that a higher assurance level is required).

IAL (identity assurance level) is initially assigned as part of the registration process with MitID and later only modifiable through additional registration processes.

AAL (authentication assurance level) is calculated on the basis of the authenticators that are used, e.g. only using password would result in a Low AAL, and using 2FA with MitID mobile application would result in Substantial or High.

LoA (level of assurance) is calculated as the minimum of IAL and AAL.

Authentication response validation

When the end user has authenticated, we retrieve the user data from MitID and perform mandatory steps to assure high security level. We validate the MitID response and signature, repack and sign the data ourselves, as required by the MitID Broker protocol. You must verify the signature we put in the response. Signed data is represented by the JWS format. We host the keys for the signature verification on a separate endpoint (see API documentation). You need to fetch these keys and verify the signature.

Flow and CPR

Private companies in Denmark cannot get access to their users' CPR numbers (social security number in Denmark) directly. The user data that is available after a MitID authentication includes userId, name and date of birth. Therefore to establish a connection between userId and CPR it is usual to ask the end-user to share their CPR explicitly and perform a so-called CPR-match, where given a known CPR MitID can tell, whether it is indeed the CPR of the authenticated user.

A. The most common flow is the following:

1. The company creates a new transaction for MitID with the fields cpr = null, requestCPR = false and redirects the user to the authentication URL
2. The company retrieves the available user data, including userId, and performs an internal check, whether this userId is already tied to a user account at the company.
3. 1. If this userId is unknown, the company then asks the user to enter their CPR in a input field on the company's webpage and then calls the CPR-match endpoint to validate the obtained CPR. A new user account is then created and CPR is stored alongside with the userId for future references.
   2. If this userId is already known, the user can be logged in into their account. The company should already have the CPR stored, thus no need to ask for it again.

B. Another possible flow is when the company already knows the user's CPR and wants to authenticate this particular user:

1. The company creates a new transaction for MitID with the fields cpr = knownCPR, requestCPR = false and redirects the user to the authentication URL. These settings imply that if the authenticated user has a different CPR, the authentication will be rejected.
2. The company retrieves user data.

C. Another possible flow that could be used if the company always needs to know the user's CPR (for example if there are no user accounts at all):

1. The company creates a new transaction for MitID with the fields cpr = null, requestCPR = true and redirects the user to the authentication URL. These settings imply that immediately after a normal authentication, the user is asked to enter their CPR in an input field, which is then validated internally.
2. The company retrieves user data, which will include the validated CPR.

Relation with NemID

The only way to establish a relation between a user's NemID and MitID accounts is by CPR. NemID internal identificator PID is not available in MitID, instead of it a new userId identificator is used. Thus to allow existing users continue using their accounts linked to NemID is to implement the flow A, and link a new MitID authentication to an existing account by CPR after the step 3.1.