Signing Integration Guide with CIBA

1. What is CIBA

CIBA is an acronym for Client Initiated Backchannel Authentication and its based on OpenID Connect.  CIBA allows a client application, known as a consumption device, to obtain authentication and consent from a user without requiring the user to interact with the client directly. Instead, the client application can initiate a backchannel request to the user's authentication device, such as a smartphone with an authenticator app installed, to authenticate the user and consent to the operation. 

The Backchannel Request grant is used when performing CIBA. The following diagram demonstrates the Backchannel Request grant flow: 

More information can be found in the following blog post

2. Integration

For CIBA integration the OpenID Provider (Audkenni) and the Client (Relying Party in OpenID connect flow) first need to exchange their endpoints, signing data 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:

Next to that, the OpenID Provider will provide a client_id and a client_secret to the Client (Relying Party)

 

2.2. Information provided by the Client:

The Relying Party only needs to provide the information how he is going to sign the request JWT in order for to validate it. e.g. In case the clients signs the JWT with a private key the OpenID provider will need the public key. If the client uses a JSON web key then the OpenID provider would need the Public key of that web key


3. Setup

In some cases, the Client is also an OpenID provider that received a request from other Clients and relies on Audkenni for the actual signing. 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 signing request as the first attribute of the RELATEDPARTY scope url parameter, e.g.:

scope=openid profile signature RELATEDPARTY:exampleclient

An example full signing request would look as follows:

{ "claims": { "login_hint": "8422263", "scope": "openid profile signature RELATEDPARTY:clientname", "acr_values": "sim-sign", "iss": "clientid", "aud": "https://idp.audkenni.is/oauth2/realms/root/realms/audkenni", "exp": 238932499002, "binding_message": "binding display message", "binding_content": "binding content" "nexus_url": "https://ms.audkenni.is/plugout-server-4.25.4/api/v1/1d29c733-cb05-4b82-a4f1-40acccf72284" }, "key":"{{private_key}}", "alg":"RS256" }

Next to the scope the following parameters can be modified:

Parameter

Description

Parameter

Description

login_hint

In case the sim solution is used to sign the message this MUST contain the mobile number of the user

scope

In case of a proxy scenario this should contain the name of the initial requesting party

acr_values

This determines the method that is going to be used to sign the message. Valid values are sim_sign and nexus_sign

binding_message

This is the message that the user will see when receiving the sign request

binding_content

This is the actual content that will be signed

nexus_url

This parameter is required when nexus_sign is used as acr_values. It contains the url of the nexus personal connection that is setup with the enduser. A example html page that will generate that script can be downloaded

 

→ Response

The end result of the CIBA flow are two JWT tokens: the access_token and the id_token. The signing 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 sign request

  • name

    • The display name of the user

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

{ "at_hash": "B9S_gwle5CHxi5wX6BaY8g", "sub": "2963785c-b8cc-490e-8d7e-054f7538383b", "signature": "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", "auditTrackingId": "5d5aec42-65c2-484a-898f-0517415e32d5-337150", "iss": "https://idp-dev.audkenni.is:443/sso/oauth2/realms/root/realms/audkenni", "tokenName": "id_token", "aud": "exampleclient", "c_hash": "fkBNmAssGpWBsw_g-cncIw", "acr": "0", "nationalRegisterId": "0101303369", "org.forgerock.openidconnect.ops": "hN7HsJ_MOT5BJJazBsyRRaIQ4GQ", "s_hash": "bKE9UspwyIPg8LsQHkJaiQ", "azp": "exampleclient", "auth_time": 1575010950, "name": "Gervimaður Asía", "realm": "/audkenni", "exp": 1575014561, "tokenType": "JWTToken", "iat": 1575010961 }

4. Reference integration

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