OIDC Integration Guide

1. What Is OIDC

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables clients to verify the identity of users based on the authentication performed by OAuth 2.0 authorization servers, as well as to obtain profile information about the user using REST.

The following sequence diagram demonstrates the hight level OpenID Connect flow:

Open

How the token exchange is actually performed is determined by the grant type that the “Relaying Party” is requesting. At Audkenni we only support the “Authorization Code with PKCE” flow as can be seen in the sequence diagram below:

Open

More details about this flow can be read here.

2. Integration

For OIDC integration the OpenID Provider (Audkenni) and the Relying Party first need to exchange their endpoints and credentials which each other.

2.1. Information provided by the OpenID provider:

The endpoints of the OpenID Provider are static and can be found here (together with other information about the Audkenni provider). The most important endpoints are:

• authorize: https://idp.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/authorize

• token: https://idp.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/access_token

• userinfo https://idp.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni/userinfo

Next to that, the OpenID Provider will provide a client_id and possibly a client_secret to the Relying Party

2.2. Information provided by the Relying Party:

The Relying Party needs to provide the following information

• redirect_uri’s

• If the client is confidential or public.

  • The main difference relates to whether or not the application is able to hold credentials (such as a client ID and secret) securely. e.g a javascript only client is considered public as the end-user will be able to see all the information exchanged between the Relying Party and the OpenID provider including credentials.

3. Setup

In some cases, the Relying Party is also an OpenID provider that received a request from other Relying Parties and relies on Audkenni for the actual authentication. This scenario is seen in the picture below.

In this case, Audkenni mandates that the information about the original Relying Party (RelatedPartyParty) is provided in the authorization request as the first attribute of the RELATEDPARTY scope url parameter, e.g.:

An example full authorize request would look as follows:

3.1. Providing the login message

The message that the user receives during authentication (e.g. on his phone/app/nexus card) can also be provided in the authorize request as the second attribute of the RELATEDPARTY scope url parameter. The message has to be provided in base64 encoded format.

e.g

An example full authorize request would look like this

If no message is provided in the RELATEDPARTY scope then the user will receive the message “Login to Audkenni”.

3.2. Influencing the login flow

The login flow the user experiences can be influenced by adding the “acr_values“ parameter in the authorize request. At the moment the following values are supported

• default

  • In this case, the default login flow would be presented in which the user can choose the authentication method

• nexus

  • In this case, only the nexus personal card authentication option is shown

• sim

  • In this case, only the Sim card authentication option is shown 

An example authorizes request where the sim card option is enforced looks like this:

→ Response

The end result of the oauth2 flow is two JWT tokens: the access_token and the id_token. The user information can be found in the following attributes of the id_token:

• nationalRegistryId

  • The social security number

• certificate

  • The certificate generated by the authenticator as a result of the user authentication

• name

  • The display name of the user

As a reference, a complete payload of a (decoded) id_token looks as follows:

4. Reference integration

A postman collection that replicated the oauth2 flow can be found here.