OpenID Connect

​The E-Ident service uses the OpenID Connect (OIDC) as one of two possible identification protocols. This page outlines the identification process, the identification parameters and the ID Token.

OpenID Connect identification

Identification in E-Ident can be done using the OIDC protocol and the implementation supports the Authorization Code Flow with the optional PKCE and CIBA flows. The figure below illustrates the identification sequence when using OIDC.

 

  1. The end user accesses the E-Ident customer site with a request to log on.
  2. The end user browser is redirected to E-Ident to begin identification. Sample identification request: https://www.ident-preprod1.nets.eu/its/index.html?client_id=<client_id>&response_type=code&redirect_uri=<redirect_uri>&scope=openid+ssn&state=2017-06-12-15.12.43.345354&nonce=386145d332342 
    Read more about the mandatory and optional parameters.
  3. End user identification is initiated towards a selected eID. The end user supplies his/her credentials.
  4. E-Ident redirects the end user to the E-Ident customer's redirect_uri by appending the query string
    ?code=<authorization code>. Similarily, the  state parameter, as sent by the customer, is also appended to the redirect_uri.
  5. The E-Ident customer requests an ID Token based on the authorization code. Successive token requests with the same authorization code (code) will result in error and invalidation of previously accessed tokens.

PKCE flow

The Proof Key for Code Exchange (PKCE) flow allows Single Page Application (SPA) and native apps to retrieve the ID token directly in a secure way without revealing the password and not through a backend call. The flow is optional and works likes this:

  • Customers must generate a code_verifier value
  • Optionally the customers transforms the code_verifier value and sends it as a code_challenge to the E-Ident service along with the identification request. The customers may also optionally send the code_challenge_method (SHA-256 or plain) along with the identification request.
  • After authentication, the code_verifier is sent when retrieving the token. The E-Ident service will verify the code_verifier against the original challenge, using the specified method (SHA-256 or plain).

CIBA flow

Standard authentication using OIDC relies on the user agent (user's browser) first access the OIDC provider to initiate the session. The response from the provider is a web UI that guides the user through the authentication sequence.

The Client Initiated Backchannel Authentication (CIBA) flow enables authentication sessions to be initiated and processed in a different channel than the browser through the E-Ident web UI.

The following diagram illustrates a CIBA flow use case:

CIBA1.jpg 

In this use case:

  1. A user contacts an agent by phone or e-mail requesting for some service or assistance.
  2. The request is forwarded to the back end system that requires the user to be remotely authenticated.
  3. A CIBA request is sent to the E-Ident service to initiate authentication.
  4. The user then completes the sequence by providing their consent (by authenticating using their device).
Another alternative would be for the user to request for a service through an app published by their provider (the company providing a service such as a bank, school, institution, etc.).

CIBA2.jpg

After authentication in the user device, the service provider in this use case can retrieve the ID token from the E-Ident service.

Implementation

To implement the backchannel flow, customers will need to follow the following sequence:

  • call the CIBA endpoint to start a new authentication transaction. See CIBA specific identification parameters.
  • use the response to start user authentication (user consent)
  • wait for the user complete(alternatively, poll the server for updates)
  • retrieve the ID token

Requesting for a CIBA transaction

curl -kiSs \
https://www.ident-preprod1.nets.eu/oidc/ciba \
-H Authorization: Basic <<Base64Enocoded username:password>> \
-d scope=openid \
-d amr_values=passport_reader

Upon success, the server will respond with a unique ID that is bound to the new session

{"auth_req_id":"c69597e96f5a4dcc970ec38e5a85a4c3","interval":5,"expires_in":600}

The auth_req_id is a session ID that can be provided to the authentication app to facilitate consent confirmation (authentication).

Requesting for CIBA transaction with login hint and binding message

When starting a CIBA transaction with BankID on Mobile (NO) or Mobile BankID (SE), it's required to specify the end user's identity. This is done by passing the login_hint parameter with the correct data depending on the authentication method. The binding_message parameter is used to specify the text that will appear on the end user's device.

curl -kiSs \
https://www.ident-preprod1.nets.eu/oidc/ciba \
-H "Authorization: Basic <<Base64Encoded username:password>>" \
-d scope=openid \
-d login_hint=<<SSN>>\
-d amr_values=<<se_bankid/no_bidmob>> \
-d binding_message=<<Base64Encoded message>>

Retrieving the CIBA ID token

curl -kiSs \
https://www.ident-preprod1.nets.eu/oidc/token \
-H "Authorization: Basic <<Base64Enocoded username:password>>" \
-d grant_type=urn:openid:params:grant-type:ciba \
-d auth_req_id=c69597e96f5a4dcc970ec38e5a85a4c3

The following E-Ident providers currently support the CIBA flow:

  • BankID on mobile (NO)

  • BankID (SE)

  • Nets Passport Reader

Identification request parameters

The different identification request parameters are divided in these sections:

Mandatory

NameDescription​Value
​client_idThe customer identifier given upon registration. Often referred to as MID or merchant identifier. This is not the same as the MerchantID.  ​​MID
​nonce ​String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. ​Unique random value
Max lenght: 500 bytes (UTF-8)
​redirect_uri​A URL to the customer resource that will process OIDC claims after authentication. One or more redirect_uri must be registered on the customer configuration. The URL the end user is going to be returned to must be set in the redirect_uri parameter when the customer initiates an identification.
Note: Several redirect_uri URLs can be registered in the configuration. This means that you can use the same configuration for several test environments or production environments.​
​Customer redirect uri as registered in E-Ident.
​response_type

OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. When using the Authorization Code Flow, this value is code.

​code
​scope​Scopes are used to retrieve the claims that are grouped in the below table. The optional values are custome scopes in E-Ident. None, one or more can be requested at the same time.

​Mandatory scope: openid
Optional: cert, email, organisationphone, profile and ssn.

Space-separated list.

​state

​Opaque value used to maintain state between the request and the call back. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

The customer should check the value of this parameter against the value returned by E-Ident after identification. If it does not match, error should be thrown.

Unique random value​
Max length: 500 bytes (UTF-8)

Optional

​Name​Description​Value
​additional_info

​The additional info parameter can be used by any customer to enter their own information. The parameter value will be returned as it was entered in the corresponding claim in the ID Token or attribute in the SAML assertion.

In addition, the information is added to E-Ident statistics and may be returned to the customers as part of statistics. The last part must be agreed with Nets in each case.

​Format:

[A-Za-z0-9_\-åøæÅØÆ]{0,50} 

Max length: 50 characters

​amr_values

Requested Authentication Method Reference values. Space-separated string that specifies the "amr" values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The authentication methods used for the authentication performed are returned as the amr Claim Value. This parameter is equvalent to the forcepkivendor parameter of SAML identification.

​One or more of:

[no_bankid, no_bidmobno_buypass,   dk_nemid_js, dk_nemid-opensign, mitid, se_bankid, fi_tupas, fi_mobiilivarmenne, passport_reader, verimi, nets_sms]​

​code_challenge

​The code_challenge is created by

  • SHA256 hash of the code_verifier and
  • Base64 URL encode the resulting hash.

If it is not possible to do the above transformation, the code_challenge may be set to the code_verifier value.

​Mandatory in PKCE flow.
​code_challenge_method

​This parameter specifies the method used for the code_challenge parameter.

  • S256: Transformed code_challenge

  • Plain: code_challenge is the same as code_verifier

If the parameter is not sent in the request, Nets will assign plain as the default value.

​Valid values: [S256 | plain]

Optional parameter in PKCE flow.

​code_verifier​The code_verifier should be a high-entropy cryptographic random string. 

Format: [A-Za-zO-9-._~]

​Min length: 43 char

Max length: 128 char

Mandatory in PKCE flow.

​deflectWhere the redirect_uri should be opened. Options are to keep it in iframe (_self) or take over the page (_top).

 Valid values: [_top, _self]

 Default: _top

id_token_hint​ID Token parameter for prompt=none
​max_age​Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the end user was actively authenticated. If the elapsed time is greater than this value, then  the customer should attempt to actively re-authenticate the end user. When max_age is used, the ID Token returned should include an auth_time Claim Value.

​Integer value

Example:

600 for 10 minutes

​style​A customer with a specific typographic, layout, or colour scheme can provide a URL to a CSS style sheet. If provided, the given style sheet will be used when rendering web pages in a browser.
Note: style is ignored if the wi parameter is set to “n” or not set at all.
​Format: URL
Range: only URLs to trusted domains are allowed by E-Ident.
Trusted domains are a part of the customer configuration setup.
This parameter overrides the URL issued to E-Ident during configuration.
​ ui_locales

The language used to provide user with information during identification. If not provided, then E-Ident uses the language specified by the web browser.

If no supported languages are available in the browser, or the parameter, then Norwegian is used by default.

Supported language codes:

[nb-NO |  nn-NO | en-GB |  da-DK  sv-SE | fi-FI | sv-FI]

​wi

The wi parameter is used to indicate that the user interface shall be embedded UI.

Note: The wi parameter may also be set to n to indicate standalone UI. However, as this is default UI option it is not necessary to use the wi parameter.

​​​​​​Valid values: [ r ]

Optional eID specific parameters

​Name​Description​Constraints​eID
​aal_value
 

​Specifies the requested Authentication Assurance Level.

One of:

[ low | substantial | high ]

​MitID DK
​acr_values

​Used to set the minimum level of assurance for the identification.

​Valid values:

See the eID specific page.

Verimi

​autostart

​Used to inform the service if it shall try to start the eID client automatically. (If the end user is using the device where the eID client is located)

​Values:

 [true | false]

​BankID (SE)
​celnr8

​8-digit mobile/cell number for BankID on mobile (NO).

​Encoding: Base64​​BankID on mobile (NO)
​dob6

​6-digit date of birth for BankID on mobile (NO).

​Encoding: Base64​BankID on mobile (NO)
​forcebank​To direct the end user directly to the wanted bank, the customer can use this parameter. It can only be used in combination with amr_values=fi_tupas.

If the parameter is not used, a list of all the Tu-pas banks configured on the customer site will be displayed.

One of: nordea | opbank | danske | handelsbanken | aland | sbank | aktia | popbank | savingsbank| omasp

Finnish Bank ID (FI)
​loa_value
 

​​Specifies the requested Level of Assurance.

One of:

[ low | substantial | high ]

MitID DK​
​nemid_clientmode

​The NemID JS client can either be shown in a standard or in a limited mode. The standard mode includes administration possibilities for the end user like activation for new end user.

Some customers might notice that the content of their iFrame is moved slightly when pressing the question mark button in the NemID client. This could be prevented by using this parameter with “limited” as the value.

​Value:

[standard | limited]

               
 Default:

standard
​NemID JS (DK)
​presetid
​​​​​

​A pre-selected user ID to improve user experience and reduce number of steps for a user.

 

​​

​Possible value (depending on eID):

​[SSN | Phone number | E-mail address | name]

Encoding: Base64

​Applicable for these:

BankID (NO), BankID (SE), Mobiilivarmenne (FI), Nets One time code and Verimi

​reference_text

​Reference text displayed during MitID identification. The text is displayed both in the MitID client and in the MitID app.

​All characters allowed except:  %<

Max length: 130

​MitID (DK)
​transactiontext

​Transaction text displayed in the end user's app:

  • NemID code app
  • BankID security app/mobile app 
Characters
Max length: 100 ​
BankID (SE), NemID JS (DK)​

CIBA specific parameters

​Name​Description​Constraints
​​amr_values​​Requested Authentication Method Reference values. Can only contain a single value for CIBA transactions.​One of:

[no_bidmob, se_bankid,

passport_reader]​

​binding_message​​Text to be displayed on the end user's device (Base 64 encoded).
  • BankID on Mobile (NO): max 116 characters.
  • Passport reader: not supported
​​login_hint​String specifying the end user's identify.
  • ​​Mobile BankID (SE): SSN
  • BankID on Mobile (NO): <phone-number date-of-birth>
  • Passport reader: not supported

ID Token

The ID Token is a JSON Web Token (JWT) and is either signed or signed-then-encrypted. The default is signed. For more information on encryption, see ID Token Encryption section.

The ID Token signature should be validated using the public key that is mentioned in the kid element in JWT header. The corresponding key can be looked up from E-Ident’s JWKS endpoint.

The ID Token is valid for 15 minutes. Successive token requests with the same authorization code (code) will result in error and invalidation of previously accessed tokens.

The ID Token claims depends on the scope parameter value from the identification request. The openid value must always be used while cert, profile and ssn is optional. All ID Token claims are listed here, sorted by the scope value. See examples in  Step 3 on how to retrieve an ID Token.

openid

​ClaimDescriptionValue/constraint
​aal

​Authentication 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
Applicable eID:
MitID (DK)
​acr​​The level of assurance for the specific identification.​Possible values are listed on the eID pages.
​additional_info

The value of the additional info parameter if used.

​amr

Auth Method Ref​. JSON array of strings that are identifiers for authentication methods used in the authentication.

In E-Ident, this is the eID type used in the identification.

​One of:

[no_bankid | no_bidmob | no_buypass           dk_nemid_jsdk_nemid-opensign | mitid se_bankidfi_tupasfi_mobiilivarmenne | passport_reader | verimi]

​aud

Audience(s) that this ID Token is intended for.

​The unique customer "MID" value.
​auth_files_url​A URL to download authentication files. Read more about the authentication files.

Applicable eID:

Nets Passport Reader

​auth_time​Time when the end user identification occurred. The value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
​dk_dan_pid​In E-Ident, this is the personal identifier from a NemID identification.
​dk_dan_rid RID value from NemID MOCES identification. 
​expExpiration time on or after which the ID Token must not be accepted for processing.​The value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
​fi_trx_code​Unique but transient anonymous identifier for the end user. Remains the same in identity token and UserInfo responses during one authentication session, but is different in subsequent authentications of the same user.​

​Applicable eID:

Mobiilivarmenne (FI)

​​fi_tupas_bank​The user’s bank used in the identification process.

One of:

[nordea | opbank | danske | handelsbanken | aland | sbank | aktia | popbank | savingsbank | omasp]

​Applicable eID:

Finnish Bank ID (FI)

​fi_tupas_pid
 

​A fixed identifier for the user set in the E-Ident / FTN service.

​Applicable eID:

Finnish Bank ID (FI)

​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
Applicable eID:
MitID (DK)
​iatTime at which the JWT was issued. The value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
​iss

Issuer Identifier for the Issuer of the response.

​E-Ident issuer URI

​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
Applicable eID:
MitID (DK)
​mitid_amr

​The list of authenticators used to achieve the resulting level of assurance for a MitID identification.

​Possible values are:

  • mitid.password
  • mitid.code_token
  • mitid.code_reader
  • mitid.code_app
  • mitid.code_app_enchanced
  • mitid.u2f_token
Applicable eID:
MitID (DK)
​mitid.uuid​Unique identifier for MitID.

​Applicable eID:

MitID (DK)

​no_bid_pid​Norwegian BankID personal identifier.

​Applicable eIDs:

BankID (NO) and BankID on mobile (NO)

​nonce​String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.
​notafter​Certificate validity end time.​​Applicable eIDs:

BankID (NO), BankID on mobile (NO), BankID (SE) and NemID (DK)

​notbeforeCertificate validity begin time.​​Applicable eIDs:

BankID (NO), BankID on mobile (NO), BankID (SE) and NemID (DK)

​phone_number​​8-digit mobile/cell number (provided by merchant or user)​​Applicable eID:

BankID on mobile (NO)

​pid​Personal identifier. Content will vary from eID to eID.

​See possible values in "Information about end user" section for each eID.

​se_bid_securitylevel​Swedish BankID security level

​Applicable eID:

BankID (SE)

​sub

Subject Identifier.

​A string in the format "eID type:ID"

cert

​Claim​Description​Value/constraint
​c​The country associated with the end user's eID. ​Applicable eID:

All (if available)

​certificate​The end user's certificate.​​Applicable eID:

BankID (NO), BankID on mobile (NO), BankID (SE) and NemID (DK)

​certpolicyoid​The certificate policy of the end user's certificate.

​Applicable eID:

All (if available)

​cn​The common name from the end user's certificate.​Applicable eID:

All (if available)

​dn​The distinguished name from the end user's certificate. ​Applicable eID:

All (if available)

email

​​Claim​Description​Value/constraint
​emailThe end user's e-mail address.

Applicable eIDs:

Verimi

​email_verified​This claim tells if the e-mail address has been verified or not.

​One of:

true | false

Applicable eIDs:

Verimi 

organisatio​n

​​Claim​Description​Value/constraint
​authorized_to_represent

​The organisation number (Danish CVR number) the user has selected and is authorised to represent. 

The user can select a company when using the Private NemID - on behalf of companies​ or Private MitID - on behalf of companies ​functions.

Applicable eID:
NemID (DK) POCES users and MitID (DK)
​organisation_name

For Private NemID and Private MitID:​

The name of the organisation the user logs in on behalf of.​

For Finnish Bank ID:
The organisation name connected to the user's legal person ID.

​Applicable eID:
NemID (DK), MitID (DK) and Finnish Bank ID (FI)
​organisation_number

For NemID:

​The organisation number either from a NemID MOCES certificate or the organisation number received when using the Private NemID - on behalf of companies​ ​function. 

Note: When a NemID MOCES is used to login, the authorized_to_represent claim will be empty. This as no validation of user rights on behalf of company has been performed. The organisation number is fetched from the user's certificate. 

For MitID:

The organisation number received when using the Private MitID - on behalf of companies function.

For Finnish Bank ID:
​​The organisation number (VAT) connected to the user's legal person ID.

​Applicable eID:
NemID (DK) - MOCES and POCES users, MitID (DK) and Finnish Bank ID (FI)

phone

​​Claim​Description​Value/constraint
​phone_numberThe end user's phone number.

Applicable eIDs:

BankID on mobile (NO), Mobiilivarmenne (FI) and Verimi

​phone_number_verified​This claim tells if the phone number has been verified or not.

​One of:

true | false

Applicable eIDs:

Verimi

profile

​Parameter​Description​Value/constraint
​birthdate​Date of birth in the format DD.MM.YYYY

Applicable eID:

BankID (NO), BankID on mobile (NO), Finnish Bank ID (FI) and Mobiilivarmenne (FI)​

​family_name​The end user's surname​Applicable eID:

All (if available)

​given_name​The end user's given name. Applicable eID:

All (if available)

​name​​The end user's full name.​​Applicable eID:

All (if available)

ssn​​

​Parameter​Description​Value/constraint
​dk_ssn​Danish SSN

​Applicable eID:

NemID (DK) and MitID (DK)

​fi_ssn

​End user's ​Finnish personal identity code (henkilötunnus).

Applicable eIDs:

Finnish Bank ID (FI) and Mobiilivarmenne

​fi_satu

​Finnish unique identification number (sähköinen asiointitunnus).

​Application eID:

Finnish Bank ID (FI)

​no_ssn​Norwegian SSN

​Applicable eID:

BankID (NO) and BankID on mobile (NO)

​se_ssn​Swedish SSN

​Applicable eID:

BankID (SE)

​ssn​Social security number / National identifier

​Applicable eIDs:

BankID (NO), BankID on mobile (NO), Buypass (NO), NemID (DK), MitID (DK), BankID (SE), Finnish Bank IDs (FI) and Mobiilivarmenne.

ID Token sample

{
  "sub" : "dk_nemid_js:PID:xx-xx-xx-xx",
  "dk_ssn" : "xx",
  "amr" : "dk_nemid_js",
  "iss" : "https://ti-pp.bbs.no/oidc",
  "certificate" : "<base64value>",
  "dn" : "CN=Test Testesen + SERIALNUMBER=PID:xx-xx-xx-xx, O=<Value>, C=DK",
  "cn" : "Test Testesen",
  "nonce" : "1a2c2990a3639",
  "dk_dan_pid" : "PID:xx-xx-xx-xx",
  "aud" : "<mid>",
  "certpolicyoid" : "1.3.6.1.4.1.31313.2.4.6.1.4",
  "exp" : 1510653509,
  "iat" : 1510652609
}

ID Token encryption

Customers can request Nets to encrypt all ID Tokens. The ID Token will be encrypted using RSA-OAEP and AES, as described by RFC 7516. The encryption is done after signing, which means that the customer needs to decrypt the ID Token before being able to validate the signature.

The customer will need to provide Nets with one of the following options:

  • A URL to a JWKS endpoint where Nets can look up a public key for encryption purposes. It is optional to also provide a key id. Otherwise the first public key in the response from the endpoint will be used.
  • The RSA key members and the key type in JSON format.

Get in touch with support for more details.

OIDC discovery URL

OIDC discovery request has to be made to get the token_endpoint and jwks_uri. This can be done programmatically or manually to get the token_endpoint uri and jwks_uri.

The OIDC discovery URL:

  • Customer test: https://www.ident-preprod1.nets.eu/oidc/.well-known/openid-configuration
  • Production: https://www.ident.nets.eu/oidc/.well-known/openid-configuration

OIDC UserInfo endpoint

The UserInfo endpoint returns claims about the authenticated user, including some claims not available in the ID token. Accessing this endpoint requires an access token. This token is returned together with the ID token. The access token shouldn't be expired to get the authentication data. The endpoint response will be in JSON format.

For SAML protocol, the access token will be available in the SAML response.

Requesting authentication data from UserInfo edpoint

curl https://www.ident-preprod1.nets.eu/oidc/userinfo -H "Authorization: Bearer <<access token>>"

Sample UserInfo endpoint response

{
	"sub" : "se_bankid:xxxxxxxxxxxx",
	"user_signature" : "<<user_signature>>",
	"user_cert_ocsp" : "<<user_cert_ocsp>>",
	"notbefore" : "20210112230000",
	"amr" : ["se_bankid"],
	"notafter" : "20230113225959",
	"iss" : "https:\/\/www.ident-preprod1.nets.eu\/oidc",
	"given_name" : "Test",
	"nonce" : "nonce06\/09\/2021",
	"auth_device_ip" : "xxx.xxx.xxx.xx",
	"ssn":"xxxxxxxxxxxx",
	"access_token" : "QzLCDFodNn0y4XdGY2AVKRdDxY2JFiHLDZm0bz8aV-E",
	"aud" : "Test merchant",
	"se_ssn" : "xxxxxxxxxxxx",
	"name" : "Test Testesen",
	"exp" : 1630915131,
	"iat" : 1630914231,
	"family_name" : "Testesen",
	"jti" : "278b78056a8349f68be8679d7f908159"
}

Recommended reading

The OIDC standard is described here: http://openid.net/connect/

Referenced documentation: http://openid.net/specs/openid-connect-core-1_0.html

Reference implementations: