Home > Features > OAuth > Grant flows > CIBA > Integration patterns

Client-initiated Backchannel Authentication integration patterns

Learn how integration patterns for CIBA grant flow look like for Authorization Control Plane (ACP). Use them to successfully integrate your authentication device with ACP.

Authentication services in a nutshell

In the CIBA grant flow, authentication device uses the authentication service to communicate with the authorization server, in this case ACP. The authentication service must be able to communicate with ACP using its own and ACP’s APIs. If you want to enable CIBA for your users, you need to implement an authentication service that exposes APIs compliant with the Swagger specification provided by Cloudentity.

The authentication service (AS) you implement is responsible for a couple of steps of the CIBA grant flow:

  • AS verifies if the end-user has the authentication device configured and ready to authenticate themselves and grant their authorization to the consumption device.

  • AS receives requests from ACP and based on them it communicates either with the authentication device or ACP.

  • AS may be responsible for communication with the ACP. The authentication service may, for example, request additional consent data from ACP. to be able to display a consent that provides all necessary information for the end-user to make a conscious decision.

  • AS is responsible for communication with the authentication device. It passes consent details to the authentication device, starts the authentication process for the authentication device, gets the results and, in the end, provides the authentication and authorization results to ACP.

ACP basic authentication

ACP integration with authentication services makes it possible to use Basic access authentication as a means to authenticate ACP. It is a simple authentication scheme that is built into the HTTP protocol. To use it, provide your Basic Auth Username and Basic Auth Password in CIBA configuration that ACP base-64-encodes and uses when sending a request to your exposed APIs.

About integration patterns

To integrate with ACP, there are two different integration patterns. Depending on whether you want to use your authentication service as in a regular CIBA grant flow or as in an Open Banking compliant CIBA grant flow, you must choose an appropriate integration pattern. Both integration patterns are for the PING CIBA mode, but they can be easily adjusted to the POLL mode.

To be able to integrate with ACP CIBA, you must also use an appropriate login_hint parameter. There are three different ways of providing the user’s identifier as described in the Client-initiated Backchannel Authentication grant flow OIDC specification:

  • login_hint

  • login_hint_token

  • id_token_hint

Regular CIBA grant flow

To be able to use a regular CIBA grant flow with ACP, your integration should be compliant with the guidelines and integration patterns provided by Cloudentity.

[mermaid-begin]
sequenceDiagram autonumber participant CD as Consumption Device participant ACP participant AS as Authentication Service CD->>ACP: POST /backchannel/authentication
{"login_hint": "John Doe"} ACP->>AS: POST /user/verify
{ "user_identifier": "John Doe" } AS-->> ACP: OK {"valid": true} ACP-->>CD: OK {"auth_req_id": "123-456-789"} note over ACP, AS: 5th step is asynchronous and may happen
before the response is returned to the consumption device ACP-)AS: POST /authentication/start
{ "login_id": "987-654-321", "user_identifier": "John Doe" "state":"c4ic2vn2brr5gsvq5so0"} AS -->> AS: User authentication and authorization process AS->>ACP: POST /api/system/{tid}/scope-grants/{login}/accept
{ scopes: ["openid"] } ACP-->>AS: OK ACP->>CD: POST /notify-callback
{"auth_req_id": "123-456-789"} CD->>ACP: POST /oauth2/token
{"auth_req_id": "123-456-789"} ACP-->>CD: Token response

  1. A consumption device sends a request to the ACP Backchannel Authentication endpoint.

    The request contains the login_hint parameter. It serves as a hint to ACP regarding the end-user for whom the authentication is requested.

  2. ACP sends a POST request to the /user/verify authentication service endpoint.

    This step is to verify if the user has their authentication configured and ready to be used to authenticate them.

    The request from ACP contains the user_identifier parameter that is derived from the login_hint provided to ACP in the first step by the consumption device.

    user/verify endpoint implementation

    The user/verify API must be implemented according to the swagger specification provided by Cloudentity.

  3. The authentication service responds with the 200 response status.

    The response contains the valid parameter. If the user is allowed to use the authentication device, the value for the valid parameter is set to true. If they are not, the value is set to false and ACP notifies the consumption device with an error and the flow is stopped.

  4. ACP responds to the consumption device with the 200 status.

    The response contains the auth_req_id parameter that stands for an identifier of the authentication request made by the client.

  5. ACP sends a POST request to the /authentication/start authentication service endpoint.

    By sending the request, ACP starts the actual authentication process. The request contains the login_id, user_identifier, and the state parameters.

    As this is an asynchronous step, it may happen before the response from the previous step reaches the consumption device.

    authentication/start endpoint implementation

    The authentication/start API must be implemented according to the swagger specification provided by Cloudentity.

  6. Authentication service performs steps necessary for the user to authenticate themselves and to authorize the consumption device.

  7. Authentication service sends a POST request to the accept scope grant request ACP API.

    The request contains an openid scope.

    The authentication service also provides a list of scopes to be granted based on the request scopes provided by ACP.

    Tip

    If the user denies the authorization, the request should be sent to the reject scope grant request ACP API.

  8. ACP responds to the authentication service with the 200 status.

  9. ACP sends a POST request to the consumptions device registered notify-callback endpoint.

    The request contains the auth_req_id parameter. It references the identifier of the same authentication request that was used in the 5th step.

  10. With the auth_req_id, the consumption device is able to request token by calling the OAuth 2.0 token endpoint.

    Note

    The request must contain the authentication request identifier (auth_req_id).

  11. ACP responds with a token.

Result

The consumption device is now able to make requests to protected APIs.

Open Banking compliant CIBA grant flow

Open Banking compliant CIBA grant flow differs from the regular flow in some of the steps that you need to take to integrate with ACP in an Open Banking ecosystem compliant way. One of the biggest differences is that the consumption device can be a third-party application that is registered within the financial institution that uses the authentication service compliant with ACP guidelines for CIBA grant flow integration.

ACP has built-in compliance with both the Open Banking UK and the Open Banking Brasil directives. Depending on the consent type and whether you want to provide services within the OB UK or OB BR directive, you must use different APIs. The integration pattern provided in this article is based for account access consent for Open Banking UK, but it can be easily adjusted for the needs of payment consents or for the needs of Open Banking Brasil consents.

[mermaid-begin]
sequenceDiagram autonumber participant CD as Consumption Device / TPP participant ACP participant AS as Authentication Service CD->>ACP: POST /{tid}/{aid}/open-banking/v3.1/aisp/account-access-consents ACP-->>CD: OK {"consent_id": "456-789-123"} CD->>ACP: POST /backchannel/authentication
{"login_hint": "John Doe", "openbanking_intent_id": "456-789-123"} ACP->>AS: POST /user/verify
{ "user_identifier": "John Doe" } AS-->> ACP: OK {"valid": true} ACP-->>CD: OK {"auth_req_id": "123-456-789"} note over ACP, AS: The 7th step is asynchronous and may happen
before the response is returned to the consumption device ACP-)AS: POST /authentication/start
{ "login_id": "987-654-321", "user_identifier": "John Doe",
"openbanking_intent_id": "567-789-123" } note over CD, AS: At this point, the authentication service may request additional consent data from the CD/TPP. AS -->> AS: User authentication and authorization process AS->>ACP: POST /system/{loginID}/openbanking-account-access/consent/accept
{ scopes: ["openid"] } ACP-->>AS: OK ACP->>CD: POST /notify-callback
{"auth_req_id": "123-456-789"} CD->>ACP: POST /oauth2/token
{"auth_req_id": "123-456-789"} ACP-->>CD: Token response

  1. A consumption device sends a POST request to the ACP account access consent endpoint.

    Consent types

    The example illustrates how to make an Open Banking UK compliant account access consent. If you wish, you can change the type of the consent and, for example, make a POST request that would be destined for the Open Banking Brasil payments.

  2. ACP responds with the 200 status and returns a consent_id

  3. A consumption device sends a request to the ACP Backchannel Authentication endpoint.

    • The request contains the login_hint parameter. It serves as a hint to ACP regarding the end-user for whom the authentication is requested.

    • The request should also include the openbanking_intent_id parameter, which value is the same as the value of the consent_id parameter from the first step.

      openbanking_intent_id for OB Brasil

      To be Open Banking Brasil compliant, the consumption device should pass the openbanking_intent_id parameter as a dynamic scope.

    • The request should also define the requested scopes including the openid scope.

  4. ACP sends a POST request to the /user/verify authentication service endpoint.

    This step is to verify if the user has their authentication configured and ready to be used to authenticate them.

    The request from ACP contains the user_identifier parameter that is derived from the CIBA authentication request provided to ACP in the first step by the consumption device.

    user/verify endpoint implementation

    The user/verify API must be implemented according to the Swagger specification provided by Cloudentity.

  5. The authentication service responds with the 200 response status.

    The response contains the valid parameter. If the user is allowed to use the authentication device, the value for the valid parameter is set to true. If they are not, the value is set to false and ACP notifies the consumption device with an error and the flow is stopped.

  6. ACP responds to the consumption device with the 200 status.

    The response contains the auth_req_id parameter that stands for an identifier of the authentication request made by the client.

  7. ACP sends a POST request to the /authentication/start authentication service endpoint.

    By sending the request, ACP starts the actual authentication process. The request contains the login_id, user_identifier, and the openbanking_intent_id parameters among other parameters. It should also provide requested scopes that can be, later on, used.

    As this is an asynchronous step, it may happen before the response from the previous step reaches the consumption device.

    authentication/start endpoint implementation

    The /authentication/start API must be implemented according to the swagger specification provided by Cloudentity.

  8. Authorization service performs steps necessary for the user to authenticate themselves and to authorize the consumption device.

    Additional consent data

    Before the authentication device displays the consent, the authentication service may request additional consent data from ACP. It may happen, for example, by making a GET request to the ACP get account access consent endpoint.

    Such practice can be useful, for example, for payment consents, where the consent must provide payment details necessary for the end-user to take a conscious decision on their payment consent.

  9. Authorization service sends a POST request to the accept account-access consent ACP API.

    The request contains an openid scope and requested scopes from the 7th scope.

    Tip

    If the user denies the authorization, the request should be sent to the reject account access consent ACP API.

  10. ACP responds to the authentication service with the 200 status.

  11. ACP sends a POST request to the consumptions device registered notify-callback endpoint.

    The request contains the auth_req_id parameter. It references the identifier of the same authentication request that was used in the 5th step.

  12. With the auth_req_id, the consumption device is able to request token by calling the OAuth 2.0 token endpoint.

    Note

    The request must contain the authentication request identifier (auth_req_id).

  13. ACP responds with a token.