OpenID Connect

• ​​OpenID Connect identification
• PKCE flow
• CIBA flow
• Identification request parameters
  
• Signed request
  
• ID To​k​​en
• OIDC Discovery URL
• OIDC Userinfo endpoint
• Recommended reading

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:

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

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=id_verifier

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 Nets ID verifier, the following optional parameters ntdr-doc-types and ntdr-app-doclist can be sent through binding_message. ntdr-doc-types parameter accepts the following values: I, P, D and V.  These alphabets mean ID cards, Passport booklets, Driver's license and Viza/crew credentials respectively. ntdr-app-doclist parameter accepts boolean value indicating whether the document type selection page will be shown to the user.

For Nets ID Verifier, binding_message will accept value in JSON format.

A valid JSON format for binding_message is:

{

"ntdr-doc-types": "<I, V, D, P>" (multiple values, with comma separation, are allowed),

 "ntdr-app-doclist": "<true/false>"

}​​​

BankID on Mobile (NO)

When starting a CIBA transaction with BankID on Mobile (NO), 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.

​ BankID (SE)

For BankID (SE), it's optional to specify login_hint. If login_hint is provided, then that will be used to exclude other user's SSN than the provided SSN.

The binding message will accept values in text or JSON format which will appear on the end user's device.  BankID SE supports two ways of CIBA authentication depending on the amr_values parameter.

se_bankid​​

The “amr_values" can be passed as “se_bankid" which will return auth_req_id and autostart_token. Use this token to launch the app. Please refer https://www.bankid.com/en/utvecklare/guider/teknisk-integrationsguide/programstart for technical details.​

se_bankid:mob​ile

​​The “amr_values" can also be passed as “se_bankid:mobile" which will return one additional token called qr_data, use this qr_data to create animated QR code which can be scanned by BankID app. Once the first QR code is created then the polling should be done every second for token endpoint. The qr_data will be returned in every polling which can be used to update the animated QR code every second.

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

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

{
    "auth_req_id": "5be667afc6624d938a370d70b79d1c44",
    "interval": 2,
    "qr_data": "bankid.553399f8-8e65-45b5-9b83-d17d2631d88a.0.f6a74ceaafbf31d5274b8b65ffe116c30eace8457870e7aa15beaa7842594efa",
    "expires_in": 600,
    "autostart_token": "753b0e6b-3342-4fc1-90de-657dc8e39d89"
}

​​
Start polling for below endpoint-

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=5be667afc6624d938a370d70b79d1c44

​​
Upon success, the server will respond with a qr_data -

{
    "error": "authorization_pending",
    "error_description": "Consent confirmation is still pending",
    "qr_data": "bankid.80cc06dc-2686-4d4f-ad0b-73df09d76d80.11.64e6835d7bba6e9389449a4e7fca5e2aa9d56e01bb5c0ac5f014d16317a7d3b1"
}

​​​

A QR code generation library can be used to produce the QR code in the preferred size.

A valid JSON format for binding_message is-

{

   “transactiontext": “base64encoded (content from merchant)",

   “transactiontext_type": “<text/markdown>"

}

TrustID

When starting a CIBA transaction with TrustID, it's optional 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 accepts JSON format which have data for message which will appear on end user's device, request type, user status etc.

A valid JSON format for binding_message is-

{

  "requestType": "<provisioning/authentication>",

  "appId": "<appId value>",

  "bindingMessage": "<content from merchant>",

  "quarantineTime":<quarantine time>,

  "userStatus":"<active/locked/quarantined>"

}

For more information go to TrustID.​​

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 (NO)

• BankID (SE)

• Nets ID Verifier​
  

• TrustID
  

Identification request parameters

The different identification request parameters are divided in these sections:

• Mandatory​
• Option​al
• Optional eID specific
• CIBA specific

Mandatory

Mapping of eID to amr_values parameter:

List of supported documents

List of Supported Documents.pdf

Optional eID specific parameters

CIBA specific parameters

Signed request

E-Ident supports Signed Request Object (Signed JWT) in OIDC requests. Both request and request_uri parameters are supported as specified by the OIDC standard. E-Ident will do a RSA signature verification to make sure that the Request Object is signed by the expected E-Ident customer by using a public key associated with the client_id.

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

If using the request_uri option, the request uri will have to be registered by Nets.

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

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
• cert
• email
  
• nemid.pid
  
• organisation
  
• phone
• profile
• ssn 
  
• addr​ess​​​

openid

​ cert

email

nemid.pid

organisatio​n

phone

profile

ssn​​​

address

ID Token sample

{
  "sub" : "mitid:PID:xx-xx-xx-xx",
  "dk_ssn" : "xx",
  "amr" : "mitid",
  "mitid.uuid" : "xx-xx-xx-xx",
  "iss" : "https://www-ident-test.nets.no/oidc",
  "dn" : "CN=Frida Jørgensen",
  "pid" : "PID:xx-xx-xx-xx",
  "nonce" : "nonce07/06/2023",
  "aal" : "https://data.gov.dk/concept/core/nsis/High",
  "ssn" : "xx",
  "aud" : "MER2",
  "ial" : "https://data.gov.dk/concept/core/nsis/High",
  "mitid_amr" : [ "code_app" ],
  "exp" : 1686117229,
  "identity_type" : "private",
  "iat" : 1686116329,
  "jti" : "xx-xx-xx-xx-xx",
  "loa" : "https://data.gov.dk/concept/core/nsis/High"
}

ID Token encryption

Customers can request Nets to encrypt all ID Tokens. The ID Token will be encrypted using RSA-OAEP-256 and AES, as described by RFC 7516. JWE Compact serialization is used and 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.

Note: The use of encrypted ID Token is required for Finnish Trust Network customers offering identification with Finnish Bank IDs and Mobiilivarmenne.

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

The OIDC userinfo endpoint URL:

• Customer test: https://www.ident-preprod1.nets.eu/oidc/userinfo
• Production: https://www.e-ident.nets.eu/oidc/userinfo

Requesting authentication data from UserInfo endpoint

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"
}

Userinfo endpoint claims

The userinfo endpoint may return these claims in addition to the claims in the ID Token.

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

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

Reference implementations:

• https://github.com/mitreid-connect/simple-web-app
• https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server/tree/master/openid-connect-client