OpenID Connect Client-Initiated Backchannel Authentication (CIBA)¶
BankID with Biometrics supports CIBA for certain use cases. Get in touch to discuss your use case and enable CIBA for your client.
All permissions needs to be registered upfront
When authenticating with CIBA the permission needs to be registered upfront. This is explained in the steps below.
Steps¶
- Register a client with BankID OIDC
- Get an access token from BankID OIDC
- Get the BankID with Biometrics OIDC configuration
- Check if user is able to authenticate with CIBA
- Register the permission upfront
- Initiate backchannel request
- Poll for the result
- Get the signed permission (optional)
1. Register a client with BankID OIDC¶
If you don't have a client registered with BankID OIDC
yet, you'll need to register one. Follow the instructions
here to register your
application and obtain the necessary client credentials (client_id
and client_secret
).
Ensure that your client has the permissions/client
and permissions/ciba
scope available.
2. Get an access token from BankID OIDC¶
To obtain an access token from OIDC, follow these steps:
-
Call the token endpoint with your client credentials. You can find more detailed information about access tokens in the BankID OIDC documentation.
-
In the scope field, include the following permissions:
openid
,permissions/client
, andpermissions/ciba
. These permissions specify the scope of access granted to the token.
Here’s an example of a valid request:
POST /auth/realms/current/protocol/openid-connect/token HTTP/1.1
Host: auth.current.bankid.no
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <Base64-encoded client id:client secret>
grant_type=client_credentials&scope=openid%20permissions%2Fclient%20permissions%2Fciba
Make sure to replace the
3. Get the BankID with Biometrics OIDC configuration¶
To ensure seamless integration and avoid hardcoding specific endpoints in you application, follow these steps to dynamically fetch the OpenID Connect configuration:
- Determine the appropriate configuration URL based on the environment:
Environment | Url |
---|---|
Production | https://app.bankid.no/.well-known/openid-configuration |
Current (public test environment) | https://current.aletheia-test.idtech.no/.well-known/openid-configuration |
- Send an HTTP GET request to the respective configuration URL using your preferred programming language or API tool.
- Capture the response which will contain a JSON document with the configuration. By dynamically fetching the OIDC configuration, your application remains flexible, allowing for future changes or updates to the endpoints without requiring modifications to your code.
- To enhance the reliability and performance of your integration, we strongly advise implementing response caching for the OIDC configuration.
4. Check if user is able to authenticate with CIBA¶
To be able to authenticate with CIBA, the user must be enrolled in BankID with Biometrics. To check if the user is enrolled, you need to make a request to the user-exists API.
5. Register the permission upfront¶
To register a permission, follow these steps:
-
Construct a permission statement. See the permissions API for detailed information of how to construct the different permissions. Encode the permission statement using URL safe Base64 encoding. Below is an example of a permission statement for a payment:
const permissionStatement = { "nonce": "dW5pcXVlIHZhbHVl", // Must be unique "id": "YmFza2V0IGlk", // Your reference "payments": [ { "paymentId": "cGF5bWVudCBpZA", // Your reference "amount": "123.45", "currency": "NOK", "creditorName": "Scrooge McDuck" } ] } // Example implementation of a b64 URL Safe Encoder function b64URLSafeEncode(stringData) { return btoa(stringData) .replace(/\+/g, "-") .replace(/\//g, "_") .replace(/=/g, ""); } b64URLSafeEncode( JSON.stringify( permissionStatement ) ); // -> "eyJub25jZSI6ImRXNXBjWFZsSUhaaGJIVmwiLCJpZCI6IlltRnphMlYwSUdsayIsInBheW1lbnRzIjpbeyJwYXltZW50SWQiOiJjR0Y1YldWdWRDQnBaQSIsImFtb3VudCI6IjEyMy40NSIsImN1cnJlbmN5IjoiTk9LIiwiY3JlZGl0b3JOYW1lIjoiU2Nyb29nZSBNY0R1Y2sifV19"
Note:
- The `nonce` must be a unique value for each permission you register.
- Use `id` (basket ID) and `paymentId` as references to the payment(s) in your systems. These will not be shown to the end user.
- The `amount` is a decimal amount represented as a string and must use the dot as the decimal separator.
-
Send a POST request to the permissions endpoint, providing the access token received in the first step as a bearer token. Include the permission, which is the URL safe Base64 encoding of the permission statement object.
POST /permissions/v1/ HTTP/1.1 Host: api.current.aletheia-test.idtech.no Content-Type: application/json Authorization: Bearer <access token from step 1> { "type": "payment.v1", "loa": "sub", "iat": 1617091752, "exp": 1617092652, "permission": < URL safe b64 encoded permission statement from step 2a > "intents": [ "ciba" ], "loginHint": [ { "scheme": "nnin", "value": "string" } ] }
Note:
- `iat` and `exp` are timestamps in seconds since the UNIX epoch. `iat` can be at most 1 minute
into the past. `exp` sets the maximum time by which the permission must be granted and should
normally be set just a few minutes into the future.
- When using `intents : ["ciba"]` it is mandatory to include `loginHint` in the request.
-
On a successful request, you will receive a response body containing a permission ID, a permission token and a binding message:
{ "id": "1.BY.MEKrA-00GVtmvWOCDYQko_fSg93LO5n2rBnlj-X4MQg.BiDEl_CgfakqahcXjLrFet_GGpEkR_W8D-RK4hORBO0", "permissionToken": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjB5Z3hDX3UzQlpPWXlKZ0Y3eDJ0eWtQaTRCTml2cG9KMDBmYjFzTGliUVUiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2MTcwOTU3NDQsImlhdCI6MTYxNzA5MjE0NCwicyI6IjA6LTEjOTIzIiwicCI6IkJpREVsX0NnZmFrcWFoY1hqTHJGZXRfR0dwRWtSX1c4RC1SSzRoT1JCTzAiLCJuYmYiOjE2MTcwOTIxNDh9.39GWvNjNMSKKhKOF4t4HcDnZGNJmLmPT3f612z1VKko", "bindingMessage":"Farlig frakk" }
6. Initiate backchannel request¶
- Make a POST request to the bc-authorize endpoint.
- Include the
permissionToken
from step 3 as thelogin_hint_token
in the bc-authorize endpoint. - In the scope, include
openid permission/ciba
.
Below is an example of a request to the bc-authorize endpoint:
POST /oidc/v1/ HTTP/1.1
Host: api.current.aletheia-test.idtech.no
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <access token from step 1>
{
"login_hint_token": "string",
"scope": "openid permissions/ciba",
"biding_message": "string",
"expires_in": integer,
}
Note: Replace string with the actual login_hint_token
and provide appropriate values for other fields.
After calling the bc-authorize endpoint, you will receive the following response:
The bc-authorize endpoint returns auth_req_id
which you will use when posting a request to the token endpoint afterwards.
7. Poll for the result¶
-
Make a POST request to the token endpoint using the
CibaTokenRequest
schema.POST /oidc/v1/ HTTP/1.1 Host: api.current.aletheia-test.idtech.no Content-Type: application/x-www-form-urlencoded Authorization: Bearer <access token from step 1> { "client_assertion": "string", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "grant_type": "urn:openid:params:grant-type:ciba", "auth_req_id": "string" }
Note: Replace string with the actual values, including the auth_req_id.
-
While the user haven't completed the authentication yet the token endpoint will respond with a 400
authorization_pending
error. Keep polling this endpoint until you get a different error with a 400 response, or a 200 response with theid_token
in the response body.Here's an example of a successful response:
8. Get the signed permission (optional)¶
To get the signed permission you can send in a GET request to the permissionId/grant
endpoint. The permissionId
you use is the one that you
got from your permissions POST request. Be aware that it can return a 404 error code
(permission not yet granted) but as mentioned in the api specification you can set up a polling request on the permissionId/grant
endpoint until your initial permission has been signed.
If your permission has been successfully granted you will receive this response:
{
"gv": 1,
"pt": "string",
"type": "string",
"rpId": "bankid-app",
"sv": "2020-10-30@deadbeef",
"iat": 1800000000,
"iss": "string",
"nonce": "string",
"proofKeyId": "string",
"sub": "nnin:010112345",
"permissionId": "string",
"digest": "string"
}
The grant is a JWT token that can be validated as follows:
- In the BankID with Biometrics OIDC configuration (as mentioned here) get the Grant JWK set from the URI pointed to by the
jwks_uri_grants
property in this document. - Check that the JWT token is signed by one of the keys in the Grant JWK set. You can find a suitable library for performing this verification at https://jwt.io/libraries.
- Check that the
nonce
claim inside the token payload is equal to thenonce
in the permission statement created in step 2.