link

# Authentication

This page shows the different MitID authentication flows that Signicat supports.

Since the process in all the flows are quite similar, we only provide a step-by-step list with image sliders for the "normal" authentication. The difference lies in the step for the chosen authenticator. The following screen examples show the advanced graphical profile in desktop version.

# Normal authentication

The normal MitID authentication flow consists of two main steps (we assume the user has already selected a login link from the service provider site):

  1. The user enters the username in the MitID Login box.
  2. The user authenticates using authenticators applicable for the requested LoA or AAL.

If you have set up CPR matching, the user is asked to provide their CPR match after step 2. For more details, see CPR matching.

After a successful login, the Approved screen is displayed and the user is redirected to the service provider site as logged in.

This image slider shows an example of a normal authentication with the MitID app authenticator. This example shows the advanced graphical profile in mobile version.

Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide

The flow is quite similar when using the other authenticators. The difference lies in the step for the chosen authenticator:

  • MitID app: After having entered the username (no password is needed), the user is asked to approve in the MitID app. The user either approves with a 6-digit PIN or with biometrics (fingerprint or face ID.)
  • MitID code display and MitID audio code reader: After having entered the username and password, the user is asked to confirm with a one-time password (OTP) received on their token.
  • MitID chip: After having entered the username and password, the user is asked to confirm with their chip.

The chosen authenticator combination also decides the LoA/AAL (see Possible authenticator combinations).

# CPR matching (add-on)

Signicat offers a CPR match flow that can be conducted after a MitID authentication. This is useful, since private service providers are not permitted to do a direct CPR lookup for a user in MitID, but they can match a given CPR number.

This is an example of Signicat's user interface for CPR matching, displayed after the MitID authentication flow (e.g. see Normal authentication):

click-to-zoom

This example is in mobile version and with an advanced graphical profile.

MitID enforces a maximum limit of three attempts to match the CPR number within a given authentication.

Signicat supports three possible sources that can provide the CPR number for matching: CPR from user, cache and prefilled subject (see below).

# CPR from user

The end-user provides their CPR number themselves by entering it as an input in Signicat’s CPR user interface (see screen example above). This can be considered the default source for the CPR number: If no other source was provided or the prefilled/cached CPR number does not give a positive match, the user will be prompted to provide it themselves. If the user enters an incorrect CPR number, they are met with a warning as well as information detailing how many remaining attempts they have.

# CPR from cache

If the end-user has provided their CPR number and checked the “Remember my CPR number” checkbox in the CPR user interface (see screen example above) and gets a positive match, Signicat will store the number for that user for a period of 90 days (by default). The next time the user conducts a CPR match flow (within the expiration time period and on the same service) the cached CPR will be used for matching, meaning the user will not have to provide it again themselves.

# CPR from prefilled subject

In the CPR match flow, you can use the subject prefilled parameter to inform Signicat of the CPR number that you want to match against the user being authenticated. The effect of this is that when the user has authenticated, the prefilled subject value will be matched using MitID's CPR matching service. If the match is successful, the transaction will complete without further user action. If the match is unsuccessful, the user will be prompted with the Signicat's CPR user interface (see screen example above) to provide their CPR number manually instead.

Important

The prefilled CPR number is not guaranteed to match the one returned in the result from Signicat. The prefilled CPR number will not be processed by Signicat unless it is passed in an encrypted request (see for example Encrypting authorisation requests). This ensures that the CPR number does not become unencrypted in any URLs that may end up in the end-user's browser history.

See below for OIDC and SAML2 code examples with the subject prefilled parameter.

# OIDC


"login_hint": ["subject-2805542112"]

# SAML2


<Extensions>

  <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="subject">2805542112</signicat:Prefilled>

</Extensions> 

# Step-up (add-on)

The Step-up flow can be used to reauthenticate a user at a higher LoA or AAL than they were already authenticated at. From the user’s perspective, the difference is that for the Step-up authentication, they do not have to fill in their username and only need to use authenticators that satisfy the new requested LoA/AAL (see Possible authenticator combinations).

If you have the Step-up feature and your method is configured to be used as the basis for a further Step-up authentication, the result will include an auth_token_id claim for OIDC or an auth-token-id attribute for SAML2 (see code examples below). To trigger a step-up based on this authentication, you must prefill the received value in your request. Additionally, you must ensure that the Step-up authentication targets a higher LOA or AAL than the original authentication. This can be done either by prefilling the LOA/AAL or by using a preconfigured method with a higher preconfigured LOA/AAL.

In the following examples, we assume that we have received an Auth Token ID for an authentication at LoA Substantial and we wish to conduct a Step-up at LoA High.

# OIDC


"login_hint": ["authTokenId-mitid:27fbcb32-07d3-4d4b-8db4-e98179f3dfae", "assuranceLevel-HIGH", "assuranceMethod-LOA"]

# SAML2


<Extensions>

  <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="authTokenId">mitid:27fbcb32-07d3-4d4b-8db4-e98179f3dfae</signicat:Prefilled>

  <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="assuranceLevel">HIGH</signicat:Prefilled>

  <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="assuranceMethod">LOA</signicat:Prefilled>

</Extensions> 

# PSD2 (add-on)

Signicat supports using the PSD2 mode in MitID. This ensures that MitID can be used in compliance with the PSD2 RTS (opens new window). Enabling PSD2 mode, restricts the information revealed to the user during a failed multi-factor authentication. For example, a user wants to authenticate using their password, followed by an OTP from their MitID code display. If the user enters the incorrect password and PSD2 mode is enabled, they will not be immediately informed that they entered the incorrect password, as they normally would be. Instead, they will proceed to the MitID code display prompt. Only after completing with the final authenticator, they will be informed that one or more of their authenticators failed, but not which one. The user will then be given the option to restart the authentication process:

click-to-zoom

The PSD2 feature is available through purchase of the PSD2 Compliance add-on.

# Using personal MitID on behalf of a company (add-on)

Signicat offers an add-on to let your users log on or sign on behalf of the companies they hold signatory rights in. First, the user is authenticated with MitID, which is used to validate their CPR number. Once the CPR number is validated, Signicat does a lookup towards the Danish Erhvervsstyrelsen to check which companies and organisations the user has signatory rights in. The user is then presented with a view that lets them select which of these entities they wish to represent.

As a service provider, you can control certain aspects of the flow:

  • Whether or not the end-user is allowed to represent themselves.
  • By prefilling a CVR number, the user is required to have signatory rights and is only permitted to log in or sign on behalf of that company (see Prefilling a CVR number).

In the example below, a user has authenticated with MitID and their CPR number has been validated. The user can choose to represent themselves (Helle Jensen) or one of the companies they have signature rights in, e.g. Jensen Services (CVR: 23456789).

click-to-zoom

If the user then selects to represent Jensen Services, the following attributes will be added to the response:

OIDC claim SAML2 attribute Example value
signicat.organization.number onbehalfof.orgnr 23456789
signicat.organization.name onbehalfof.name Jensen Services

# Prefilling a CVR number

As a service provider, if you know in advance which company you want the user to represent, you can accomplish this by prefilling the CVR number of that company. The effect of this is that Signicat will verify that the prefilled CVR number matches one of the companies that the user holds signatory rights in and the user will only be allowed to represent that company during their login.

If the prefilled CVR number has no matches, the service provider will receive the following error code (there will be no error displayed in the UI): urn:signicat:error:USER_LACKS_SIGNATORY_RIGHTS_FOR_SPECIFIED_CVR_ERROR

If the user cancels, you will get the standard error code for user cancels: urn:signicat:error:usercancel

You can prefill the CVR number as follows:

# OIDC

"login_hint": ["cvr-23456789"]

# SAML2

<Extensions> 
  <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="cvr">23456789</signicat:Prefilled> 
</Extensions>

# Session Transfer (add-on)

The MitID Session Transfer feature enables a service provider to securely transfer an authentication to a different service provider, without the user having to re-authenticate.

There are four main parties in a Session Transfer transaction:

  • Initiating service provider ("SP-A").
  • Initiating broker ("Broker-A").
  • Receiving service provider ("SP-B").
  • Receiving broker ("Broker-B").

Using the same broker

The two service providers may be using the same MitID broker, in which case Broker-A and Broker-B represent the same broker during different stages of the flow.

The flow is conducted as follows:

  1. The end-user authenticates with MitID at SP-A.
  2. SP-A initiates a MitID authentication with Broker-A, and the user authenticates successfully.
  3. SP-A must get consent from the user to share the attributes received from the initial authentication with SP-B before proceeding with the controlled transfer.
  4. SP-A requests a Transfer Token Exchange Code from Broker-A, specifying the receiving broker, receiving service provider, and optionally a Transfer Token Text.
  5. SP-A redirects the user to SP-B, and must also provide SP-B with the Transfer Token Exchange Code and Transfer Token Text, if it was specified.
  6. SP-B provides Broker-B with the Transfer Token Exchange Code. The Transfer Token Text must also be provided if it was specified by SP-A.
  7. Broker-B uses the Transfer Token Exchange Code to retrieve the eID attributes from MitID, without the user having to re-authenticate. If SP-A provided a Transfer Token Text in step 4, Broker-B will verify that it matches the one provided by SP-B in step 6.

Warning: Security measure regarding session lifetime

Since MitID has a long lifetime for the Transfer Token Exchange Code, it is important that SP-B completes the Session Transfer immediately upon receiving the Transfer Token Exchange Code (and Transfer Token Text) from SP-A. This is important to mitigate the risk of the Transfer Token Exchange Code being intercepted and used by an attacker to fraudulently authenticate as the end-user.

# OpenAPI documentation

For more details on how to set up the methods, see the OpenAPI documentation for the MitID Session Transfer API:

# Initiating service provider

When using Signicat’s MitID Session Transfer as the initiating service provider, there will be an additional claim/attribute in the response you receive in the initial authentication.

OIDC claim SAML2 attribute Example value Description
signicat.cta_id signicat.cta-id mitid:cta:3d939e76-2bcc-402b-9e81-0770c2f8efd6 Short for “Controlled Transfer of Authentication ID”. Used as a reference to the initial authentication.

The following diagram illustrates the two first steps (see above), where the end-user authenticates with the initiating service provider:

click-to-zoom

The CTA ID can then be used in a request to Signicat's MitID API. You will need an access token with the client.mitid.cta scope to retrieve the Transfer Token Exchange Code.

The Transfer Token Exchange Code and Transfer Token Text (if provided) must then be passed on to the target (receiving) service provider. The mechanism for how this is done is outside the scope of this documentation, and must be agreed upon between the service providers.

The following diagram illustrates the next steps where the controlled transfer from the initiating service provider to the receiving service provider is performed (see step 3-5 above):

click-to-zoom

# Receiving service provider

When using Signicat’s MitID Session Transfer as the receiving service provider (SP-B), you can complete the transfer by using the prefilled parameters transferTokenExchangeCode and transferTokenText in your request. Providing transferTokenText is only required if it was specified by the initiating service provider in their request to Signicat's MitID Session Transfer API (see step 4 above).

# OIDC

"login_hint" : ["transferTokenExchangeCode-7ed3cec8-33cb-4852-bc79-ef3293e1dc52", "transferTokenText-Example transfer token text"]

# SAML2

<Extensions> 
 <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="transferTokenExchangeCode">7ed3cec8-33cb-4852-bc79-ef3293e1dc52</signicat:Prefilled>
   <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="transferTokenText">Example transfer token text</signicat:Prefilled> 
</Extensions>

The following diagram illustrates the final steps where the controlled transfer is handled in the receiving service provider (see step 6-7 above):

click-to-zoom

If the authentication is successful, the transaction will complete immediately and you will receive the ID attributes of the end-user.

# App switching: From native mobile app to MitID app

MitID supports the concept of app switching. This means, when the end-user attempts to log into your native app, they are automatically sent to the MitID app for authentication. After they have completed the MitID authentication, they are automatically sent back to your native app. This feature saves the end-user from manually switching between your native app and the MitID app.

Note

The app switching feature in MitID is only supported when the initiating app is a native app. In other words, the app switching feature is not supported when the initiating app is a regular web browser. Additional requirements also apply, as outlined below.

For the end-user, the MitID flow with app switching is similar to the one described in Normal authentication. The only difference is that the app switching flow displays an OPEN MITID APP button in step 2, whereas this button is not displayed in the normal flow.

MitID app-switching

When you require your end-users to authenticate from your native app, the MitID Logon page (powered by Signicat) should be loaded in a web view in your app (Custom Tab/View Controller).

The following sequence diagram illustrates the backend communication with the app switching feature:

click-to-zoom

For more details on how to set this up, see the following sub-sections.

# Configuration of app switching

Please supply Signicat a Universal Link to your iOS app, and/or the App Link to your Android app. Signicat will help you set this up in a method for in-app usage. You must call this method for all in-app purposes.

This can be set up in two different ways:

  • Set up one method with redirect URLs for both Android and iOS configured. Then you can control which URL will be used, for example by sending login_hint=platform-ANDROID|IOS for OIDC (or the similar way of sending prefilled parameters for SAML2).
  • Set up two different methods for Android and iOS, with the appropriate mobilePlatform configured.

# MitID app detection

Given the requirement that app switching can only be used when the initiating app is your native app, the options for presenting the MitID Logon page to the end-user is an SFSafariViewController on iOS or a Chrome Custom Tab on Android.

Important

Regardless of which mobile platform is used, your native app must check that the MitID app is installed on the end-user’s device before presenting the MitID Logon page. If the MitID app is not installed, the app switching will not work.

The approach for detecting the presence of the MitID app will depend on the technology used in your native app. The following are examples on how to do this in iOS and Android.

# Android

Code example for checking if the MitID app is installed:

public boolean deviceHasMitIDApp() { 
  try { 
    getPackageManager().getPackageInfo("dk.mitid.codeapp.android", 0); 
    return true; 
  } catch (PackageManager.NameNotFoundException e) { 
    return false; 
  } 
}

Starting with Android 11, the following must also be included in AndroidManifest.xml:

<manifest ...>
  <queries> 
    <package android:name="dk.mitid.app.android" /> 
  </queries> 
  <application ... /> 
</manifest>

# iOS

Code example for checking if the production MitID app is installed:

func canOpenMitIDApp() -> Bool {
  guard let url = URL(string: "https://appswitch.mitid.nets.eu/.well-known/apple-app-site-association”) else {
    return false
  }
  return UIApplication.shared.canOpenUrl(url)
}

In addition, the string mitid-app must be added to the plist with a key of LSApplicationQueriesSchemes.

In pre-production, where the test version of the MitID app is used, you need to use the following URL in the check: https://appswitch-test.mitid.nets.eu/.well-known/apple-app-site-association.

# Returning from MitID app to your native app

In order for the MitID app to return to your app, your app needs to support App Links for Android and Universal Links for iOS.

# Android

Add an intent filter to your main activity in Manifest.xml. Example:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="link.to.your.domain.with.an.app.links.file" />
</intent-filter>

In addition, you need to host an assetlinks.json file on your domain matching the host in the manifest file.

Read more about Android App Links in the developer documentation for Android (opens new window).

# iOS

Your iOS app needs to be set up with a Universal Link. This is done by hosting an apple-app-site-association file on your domain and register a matching domain in the app. Read about Universal Links in the developer documentation for iOS (opens new window).

# 3D Secure (add-on)

MitID with 3D Secure (3DS) support allows you to use MitID in an iframe, and in a cookieless context. The feature is for use in 3DS transactions only.

Here is an example on how it could look in an iframe:

3DS in an iframe click-to-zoom

The following restrictions apply when using MitID with 3DS support:

  • The end-user is limited to the MitID App authenticator. If the end-user does not have a registered MitID App authenticator on their phone or tablet, they can not use MitID with 3DS support.

  • There are some additional requirements for MitID 3DS compared to normal authentication. For further information, contact Signicat at support@signicat.com.

  • Due to the above limitation, all MitID 3DS authentications will achieve AAL High or AAL Substantial, depending on whether or not the end-user has enrolled their app with App Enhanced Security.

Last updated: 06/12/2022 13:06 UTC