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. 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 nonce and state parameters, as sent by the customer, are 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.


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
​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: profile, ssncert and organistation.

Space-separated list.

​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.
​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)
​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)

Optional

​Name​Description​Value
​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

​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_bidmobdk_nemid_js, dk_nemid-opensign, se_bankid, fi_tupas, fi_mobiilivarmenne]​

id_token_hint​ID Token parameter for prompt=none
​ 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 |  en_GB |  da_DK  sv_SE | fi_FI | sv_FI]

​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

​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”.​
​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.
​wi​Web interface hint.​​​​​​Valid values: [ n | r ]

 
n: Standalone GUI (default)
r: Embedded GUI

Optional eID specific parameters

​Name​Description​Constraints​eID
​presetid
​​​​​

​A pre-selected user ID. Customer can use this to limit identification to the given ID.

​​​​

​Possible value:

​[SSN]

Encoding: Base64

​BankID (NO)
BankID (SE)
​dob6

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

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

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

​Encoding: Base64​​BankID on mobile (NO)
​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)
​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)
​transactiontext​Transaction text displayed in the end user's NemID code app. Characters
Max length: 100 ​
NemID JS (DK)​
​forcebank​To direct the end user directly to the wanted Tupas 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)


 

ID Token

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.

openid

​ParameterDescriptionValue/constraint
​acr​Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the identification performed satisfied.
​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 |            dk_nemid_js | dk_nemid-opensign | se_bankidfi_tupas fi_mobiilivarmenne]

​aud

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

​The unique customer "MID" value.
​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​The identifier that the bank attaches to the certificate to identify it in the bank's system.​Applicable eID:

Finnish Bank ID (FI)

​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

​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)

​se_bid_securitylevel​Swedish BankID security level

​Applicable eID:

BankID (SE)

​sub

Subject Identifier.

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

cert

​Parameter​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)

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)

​fi_ssn​Finnish SSN

​Applicable eID:

Finnish Bank ID (FI) and Mobiilivarmenne

​no_ssn​Norwegian SSN

​Applicable eID:

BankID (NO) and BankID on mobile (NO)

​se_ssn​Swedish SSN

​Applicable eID:

BankID (SE)

organisatio​n

​​Parameter​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​ ​function.


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

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


​Applicable eID:
NemID (DK)
​organisation_number
​​

​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. 


​Applicable eID:
NemID (DK) - MOCES and POCES users

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
}

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

 

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: