Implementing custom Open Banking Brazil compliant consent page

Learn how to implement an Open Banking Brazil compliant custom consent page. Developers can find here not only information on how the custom consent page works in the Open Banking Brazil (OB) ecosystem but also guidelines on how to produce a consent page in accordance with OB Brazil standards.

The use of consents, which are fundamental for privacy assurance, guarantees that the access to data is always consciously granted by the data owner, with the time and the scope limited as needed. To enable the proper flow of contents in the OB ecosystem, its participants are required to create and manage specific consents types as defined in OB standards. Properly-processed consents are means of communication between different OB parties allowing for the information exchange between them and, ultimately, their integration.

Cloudentity delivers you with an open-sourced GitHub repository, Openbanking Quickstart. This project is an artificial bank environment where you can go through mock banking-Fintech scenarios and check how a sample application produces the custom consent page. The OB scenarios cover the flow of custom consents, which enables you to explore the technical details on the consent page provided in the quickstart. There is a possibility to customize the CSS desing of the Openbanking Quickstart environment. You can also modify .go templates for more advanced use-cases. Both of the solutions, however, have its limits.

To have a full control over your custom consent page and to be able to tailor it to exactly match your needs you can implement your own consent page. It can be, later on, integrated and enabled with ACP. What technology you use to implement custom consent pages is totally up to you, but to be Open Banking Brazil compliant, your custom consent application has to fulfill some requirements.

  1. Consent page applications must be of the confidential client type. It means that your application should be able to store client credentials securely. Such credentials are used in the client credentials OAuth grant flow.

    Remember

    Your custom consent page is also going to make calls to your bank internal APIs. Such requests may contain your customers personal data.

    When the third-party provider’s application gets authorized, as the result of the users authentication, consent pages may receive your customer’s identity (authentication) context. Such request can consist of sensitive data and, because of that, full confidentiality of your consent page application is a must.

  2. When the user gets redirected, your custom consent page receives the following parameters needed later on:

    Parameter Description
    login_id The identifier of the user’s session
    login_state Used to mitigate Cross-site request forgery (CSRF) attacks.
    consent_type Type of a consent. For Open Banking Brazil, there are two types available: consent type used for consents that are concerned with customer’s accounts, and payments type used for consents that are concerned with customer’s payments.
  3. Consent pages should be able to make requests to your bank’s internal APIs to fetch all data that is needed for the authenticated customer to consciously make a consent decision.

    Example

    Your consent page should be able to call appropriate internal bank APIs to fetch the list of your customer’s accounts and display them in the UI.

  4. The consent should be displayed to the user according to Open Banking Brazil Guidelines.

  5. The user should be able to select their accounts.

    • For accounts consent, the user should be able to select an account that they wish to share its data with a third party provider application.

    • For payments consent, the user should be able to select an account from which the payment is made.

      Note

      Accounts' balances should be displayed in the UI.

  6. On account selection, a bank can apply additional checks using its internal APIs.

    Example

    For payments, the bank can check if the account the user wish to select has enough funds to make the payment.

  7. For accounts consents, you consent page can accept or reject the consent using one of the ACP APIs:

    • POST /api/system/{tid}/open-banking-brasil/consent/{login}/accept

    • POST /api/system/{tid}/open-banking-brasil/consent/{login}/reject

    Note

    The {tid} path parameter stands for the identifier of your tenant.

    The {login} path parameter stands for the login identifier described in the second step.

    The request should also include the login_state as its request body.

    For both requests, ACP’s response contains the redirect_to field.

  8. For payments consents, you consent page can accept or reject the consent using one of the ACP APIs:

    • POST /api/system/{tid}/open-banking-brasil/payment/{login}/accept

    • POST /api/system/{tid}/open-banking-brasil/payment/{login}/reject

    Note

    The {tid} path parameter stands for the identifier of your tenant.

    The {login} path parameter stands for the login identifier described in the second step.

    The request should also include the login_state as its request body.

    For both requests, ACP’s response contains the redirect_to field.

  9. Consent page should redirect the user to the URL that it received in the redirect_to field in the 7th or 8th step.

What’s next

After you implement your custom consent page, you should Enable the consent page within ACP