MitID only test and support the browsers that have at least 2% market share and thus it is a requirement, that app switch integrations utilize the default browsers of the respective OS in question.
It is a security requirement that the end-user is presented with the address bar from the browser to allow the end-user to verify the https://mitid.dk domain during the MitID flow.
Further it is a requirement that the browser utilized supports all the MitID authenticator options, including the MitID chip which is based on Web Authentication.
Embedded browsers are not supported and not allowed (* they are allowed in iframe flow variants) – thus integrations must adhere to the Android Custom Tabs or iOS SFSafariViewController browser integrations and it not allowed to use a standard embedded browser for the integration to MitID.
Note: This text will be displayed to the user in all MitID flows inside the MitID client, but only at the last authenticator shown.
Type: Base64 encoded string.
The reference text containing the transaction content (e.g., “Transfer <amount> to <ac-count>”).
It will be shown to the user in the MitID App.
It is limited to 130 characters.
uuid_hint
Type: String
If this parameter is set with the end-user MitID UUID, the MitID flow will be automatically started for the MitID identity with the specified MitID UUID.
cpr_hint
It is required to use encryption when sending cpr_hint either through server-server TLS or request payload-encryption
Type: String
If this parameter is set with the end-user CPR, the MitID flow will be automatically started for the MitID identity with the specified CPR.
require_psd2
Type: Boolean
If this parameter is set to true, the individual authentication flow will be PSD2 compliant by restricting what information can be revealed to the end-user during authentication.
loa_value
Specifies the requested Level of Assurance level for the MitID flow.
One of
low
substantial
high
if both loa_value and aal_value is undefined in the request, the default will be set to loa_value=substantial.
aal_value
Specifies the requested Authenticator Assurance Level for the MitID flow.
One of
low
substantial
high
if loa_value is set, aal_value will be ignored.
This enables to request a MitID flow where the aal level might be higher than the (expected) Level of Assurance (loa), i.e. ial=low, aal=substantial => loa=low.
enable_step_up
Requires prompt=login
Requires loa_value or aal_value higher than the existing session from which to step-up from.
Type: bool
Specifies that the MitID step-up functionality is requested.
To activate the MitID step-up flow the prompt=login must be specified to instruct the flow to reauthenticate. Then if the enable_step_up is set to true and if the requested loa og aal value is higher than the existing session for the end-user the MitID authentication will start in step-up mode.
action_text
Type: string, default: null
Allows to specify one of the accepted “action” header texts for the MitID client flow.
The transaction_token scope requests the transaction token from the Token endpoint including the following claims.
These claims are not shared in a SSO with other services.
transaction_id
mitid.transaction_text
mitid.transaction_text_type
mitid.reference_text
ssn
Social Security Number.
List of claims:
dk.cpr
Will trigger MitID CPR user-interaction.
ID Token identity claims
Claim value
Possible values
identity_type
private
idp
mitid
loa
Level of Assurance
One of
https://data.gov.dk/concept/core/nsis/Low
https://data.gov.dk/concept/core/nsis/Substantial
https://data.gov.dk/concept/core/nsis/High
ial
Identity Assurance Level
One of
https://data.gov.dk/concept/core/nsis/Low
https://data.gov.dk/concept/core/nsis/Substantial
https://data.gov.dk/concept/core/nsis/High
aal
Authenticator Assurance Level
One of
https://data.gov.dk/concept/core/nsis/Low
https://data.gov.dk/concept/core/nsis/Substantial
https://data.gov.dk/concept/core/nsis/High
amr
The list of authenticators used to achieve the resulting LoA.
Possible values are:
password
code_token
code_reader
code_app
code_app_enchanced
u2f_token
mitid.psd2
The mitid.psd2 claim is only issued as an ID Token identity claim if the authentication of an end-user is PSD2 compliant.
Userinfo endpoint mitid scope claim values
Claim
Description
mitid.uuid
The unique MitID identifier of the subject.
mitid.date_of_birth
The date of birth of the subject.
mitid.age
The age of the subject
mitid.has_cpr
</td>
Is there a CPR associated with the MitID
</tr>
mitid.identity_name
The registered identity name.
Exception: if the user has requested name and address protection and the serviceProvider is not public then this claim will contain "NAVNE & ADRESSEBESKYTTET".
mitid.transaction_id
MitID generated transaction ID.
</tbody></table> ### Transaction token MitID specific claims
Claim value
Possible values
mitid.uuid
Same value as for ID token.
mitid.reference_text
Passthrough of the MitID reference_text identity provider parameter.
mitid.transaction_text_sha256
Base64 encoded SHA256 digest of the MitID transactiontext identity provider parameter.
mitid.transaction_text_type
Passthrough of the MitID transactiontexttype identity provider parameter
mitid.psd2
The mitid.psd2 claim is always issued as a transaction token MitID specific claim.
transaction_actions
Type: string (single value) or JSON list
Only set, if one or more of the following transaction actions where performed:
mitid.login (Login completed)
mitid.reuse_jwt (Automatic reuse of existing session)
mitid.sso_login (SSO login completed)
mitid.controlled_transfer (Controlled Transfer completed)
mitid.transaction_signing (Transaction signing)
mitid.cpr_match (CPR match completed)
mitid.cpr_lookup (Automatic CPR lookup completed)
### MitID CPR flow CPR is available from MitID flows if you are a public service provider. In this scenario, NEB will set **dk.cpr** in the result, if requested via the **ssn** scope. If you are a private service provider, the user’s CPR will not be available from the MitID system. In this scenario, a CPR Match service is provided (see MitID CPR Match API), available for MitID Brokers making it possible to match an active MitID session and CPR and verify if the supplied CPR matches the authenticated MitID identity and thus making it possible to verify if a MitID identity has the given CPR.xxxxxx. NEB implements this as a natural part of the MitID flow and will ask the user for CPR when the service provider requests CPR with the **ssn** scope. **Note**_, that it is supported to request CPR via the CPR flow by reauthenticating a user with the additional_ **_ssn_** _scope. In this case, NEB_ _will reuse the active MitID session and ask the user for CPR (but will not ask for login), do the required CPR Match verification, and return the CPR to the service. This enables services to only ask for CPR using the CPR flow when needed for specific users._ **Note** that MitID only allows MitID Match for 15 minutes after the MitID session was issued. ### MitID CPR Match API See the swagger API reference for details. The Broker API supports a “MitID CPR Match API” that allows services to match a CPR with a MitID authentication from NEB. In this way, services can ask the user for CPR and then call the API with the access token retrieved from NEB for the user authentication as authorization header. This also allows services to verify that an already known CPR matches the MitID identity in question. **Note** that MitID only allows MitID Match for 15 minutes after the MitID session was issued. If “cprNumberMatch” returns false, it means that it is not possible to match the “cpr” input parameter with the CPR-number of the user. MitID restricts CPR-matching to a maximum of three tries per session, in which case the endpoint will return the following response: Cpr Match exceeded. Only 3 tries is allowed within a session. To reset the CPR matching exceeded limitation, the client must prompt the user for reauthentication using MitID. ### MitID SSO NEB implements and supports MitID SSO and allows integrating services to utilize MitID SSO for automatic sharing MitID sessions in a SSO defined and managed by participating MitID Brokers. Any client, service or service provider can be member of up to one MitID SSO Group and if so, will automatically map all MitID sessions to this MitID SSO and automatically reuse an existing session if already active within this MitID SSO. It is possible to setup MitID SSO groups with other MitID Brokers and other MitID Broker services and service providers. NEB will handle the required end-user consent, which is required when automatically reusing an active MitID session. Note, contact Signaturgruppen if you plan to use this feature. #### MitID SSO logout It is required by all clients who utilize a MitID SSO to inform their MitID broker of logout events from the end-user. Logout is handled either by sending the end-user to the End session endpoint with the original issued ID token or by calling the Logout endpoint with the original issued ID token. See general section about logout in this document for more details. MitID SSO requires that all logout events are handled using Back-channel endpoints and thus enabling the termination of MitID SSO sessions without the need of the end-user browser. MitID SSO groups are by this forced to be Back-channel SSO groups. The only way participating service providers can receive logout events is by registering a valid Back-channel endpoint for their integration at NEB. Participating service providers will be able to get the session status from the Userinfo endpoint. ### MitID Controlled Transfer With MitID Controlled Transfer, a requesting service provider can request and retrieve a “MitID Controlled Transfer Token Exchange Code” (MitID CT Exchange Code) from their MitID Broker. Then, another service provider can exchange this to a MitID authentication from their respective MitID Broker. Flow: - Service provider A requests a MitID CT Exchange Code from Broker A and specifies a Transfer Token Text - Service Provider A redirects end-user to Service Provider B with the MitID CT Exchange Code and Transfer Token Text - Service Provider B uses Broker B and the implementation provided by Broker B to exchange the MitID CT Exchange Code token and the Transfer Token Text to a MitID authentication enabling the end-user login at Service Provider B. The protocol for exchanging MitID CT Exchange Code between service providers are up to the two exchanging service providers to define. The protocol for retrieving or exchanging MitID CT Exchange Code between service providers and MitID brokers are up to each broker to define. The specification for retrieval and exchange towards the NEB interface is specified here. Note that it is up to each agreement with other service providers, how the MitID CT Exchange Code is exchanged – this is not specified nor handled by NEB. **NOTE**: The requesting service provider has a mandatory requirement of getting the correct consent from the end-user, before sending the end-user to another service provider with a MitID CT Exchange Code. The official description of the requirement is: When the user is performing a controlled transfer from service provider A to service provider B, it is the responsibility of service provider A to get a consent from the end user, regarding eID attributes which service provider A has requested on initial request, since these attributes will be available to service provider B. #### Requesting a Controlled Transfer Token Exchange Code A Controlled Transfer Token Exchange Code is retrieved by calling the MitID Controlled Transfer Token Exchange Code endpoint (see the swagger API reference for details). | **Parameters** | **Description** | | --- | --- | | targetBrokerId | MitID Broker ID of receiving MitID broker | | targetServiceProviderId | MitID Service Provider ID of receiving service provider | | transferTokenText | Type: String
The calling service provider must specify a Transfer Token Text and hand this out to the receiving service provider. The Transfer Token Text is restricted by MitID to a maximum of 130 characters. Any length above 130 will result in an unsuccessful request. | ### Exchanging a Controlled Transfer Token Exchange Code to a MitID login As a service provider integrating to NEB, it is possible to exchange a MitID CT Exchange Code received from another service provider for a MitID login. The MitID CT Exchange Code is used by NEB in exchange of a MitID authentication token from the MitID APIs and as such enables NEB to automatically login an end-user in exchange for the MitID CT Exchange Code. The MitID CT Exchange Code is passed as a parameter to the MitID identity provider in the NEB OIDC specification, alongside the received Transfer Token Text, and will be used to login the end-user based on the MitID session used to create the MitID CT Exchange Code in the first place. ### NemID PID claim for MitID flows It is possible to request the NemID PID claim (nemid.pid) for MitID flows. This is done by specifying the scope nemid.pid which will trigger the relevant end-user flow required to return the nemid.pid claim along with the MitID login.
NemID PID scope
Claims
nemid.pid
nemid.pid
nemid.pid_status
If set, the nemid.pid claim contains the NemID PID.
nemid.pid_status can have one of the following values
success
unable_to_lookup
To retrieve the PID from a MitID login Signaturgruppen Broker will have to lookup PID from a NemLog-In3 supplied supporting service using the end-user Danish CPR number. The end-user will be guided through the needed steps automatically when the nemid.pid scope is specified. It is recommended, that the nemid.pid scope is only specified when the returned MitID identity is unknown to the service in question, as the end-user will have to enter his Danish CPR number when this scope is specified. The nemid.pid scope can be used as a reauthentication scope (see section about reauthentication) and thus NEB will automatically reuse an available user session to ensure that the end-user does not need to authenticate with MitID additional times. Note, that the scopes “nemid.pid” and “ssn” can be used together or separately. If ssn is specified that dk.cpr claim will be issued to the service provider, but both nemid.pid and ssn scopes will trigger CPR matching for the end-user. It is thus possible to minimize the data handed back to the service provider by controlling it this way. If the NemID PID could not be retrieved the nemid.pid_status claim will indicate the result. ### NemID PID API for MitID flows _Endpoint: /mitid/nemidPidLookup (see the swagger API reference for details)_ Allows a service provider to lookup the NemID PID based on a successful MitID session for the end-user. The endpoint allows for an optional CPR parameter, which is used to complete the lookup. If the ssn flow was used for the authentication flow the CPR is known by NEB for the current session and thus CPR is not needed for the lookup. If the ssn flow was not used, the service provider must provide the correct CPR for the end-user as part of the lookup. ### SSN details claims for MitID flows It is possible to request detailed information about the person based of the Danish social security system for MitID flows. Service providers can request name and/or address details for the person. To request the details the scopes ssn.details_name and ssn.details_address will trigger the relevant end-user flow required to return the detailed information for the name and address respectively along with the MitID login.
SSN details scope
Claims
ssn.details_name ssn.details_address
Shared claims:
ssn.details.status
ssn.details.name_address_protected
ssn.details.person_status
The ssn.details.status-claim can have one of the following to values:
success
unable_to_lookup
If the value of the ssn.details.status-claim is unable_to_lookup, then no other claims are returned.
The ssn.details.name_address_protected-claim contains a boolean value. If the claim value is “true” then no other claims from ssn.details-scopes are returned.
The ssn.details.person_status reflects the status of person in CPR. The possible values are:
Please refer Statuskoder i CPR for details on the meaning behind the different status values. If the value is "emigrated" no ssn.details_address-claims are returned.
The shared claims are only returned once even if both ssn.details-scopes are requested.
ssn.details_name
List of claims:
ssn.details.given_name
ssn.details.middle_name
ssn.details.surname
ssn.details_address
List of claims:
ssn.details.care_of_name
ssn.details.city_name
ssn.details.floor
ssn.details.street_name
ssn.details.street_number
ssn.details.unit
ssn.details.zip_code
ssn.details.zip_name
Please note that the transaction token will contain a transaction_action-claim with the value “ssn.details_lookup”, when one or both of the ssn.details-scopes are requested as outlined in the section “Transaction token MitID specific claims”. To retrieve the detailed information for the person from a MitID login Signaturgruppen Broker will have to look up the information from the Danish national social security system using the Danish CPR number. The end-user will be guided through the needed steps automatically when one of or both the ssn.details-scopes are specified. It is recommended, that the ssn.details-scopes only are specified, when the returned MitID identity is unknown to the service in question, as the end-user will have to enter his Danish CPR number when these scopes are specified. Note, that the scopes “ssn.details_name”, “ssn.details_address” and “ssn” can be used together or separately. If ssn is specified that dk.cpr claim will be issued to the service provider, but all scopes will trigger CPR matching for the end-user. It is thus possible to minimize the data handed back to the service provider by controlling it this way. Further note that a normal minimal address consist of name in combination with street_name, zip_code and zip_name. ### MitID service provider parameters | **Identity Provider parameters (mitid)** | **Description** | | --- | --- | | transfer_token_exchange_code | Type: string
The issued MitID Controlled Transfer Token Exchange Code
A Controlled Transfer Token Text, which is up to the calling Service Provider to define and set.
This text must be handed out to the receiving service provider together with the MitID Controlled Transfer Token Exchange Code. | Note: See general section on identity provider parameters for reference on how to set the parameters.