Note
All articles on FDX contain references to the Cloudentity platform and assume that Cloudentity provides the API security profile, OAuth and consent capabilites at the data providers end.
FDX Consent Management
A crucial aspect of the FDX specification is not only the ability to request and grant consents but also effective consent management. Consent management encompasses the maintenance and modification of existing consents. Upholding the principles of Control, Access, Traceability, and Transparency outlined by FDX, the consent management process must be accessible to both Fintech Application users and Financial Institutions that share data with these applications. This ensures that all stakeholders have the necessary tools and visibility to manage consents in accordance with regulatory requirements.
Note
If you want to learn more about FDX consent grant flow please follow our Consent APIs guide.
According to the FDX specification, consumers should have the ability to view comprehensive details of consent grants, including the permissions granted to Fintech Applications and the duration of the grants. They should also be able to revoke consent to prevent data sharing with Fintech Applications. Once a revocation is completed, users should be able to retrieve information about the initiator of the revocation and the reason behind it.
In terms of Consent Management APIs, let’s clarify the specific needs and which APIs are defined by the FDX specification.
-
Fintech Application Consent Management: As per FDX, Fintech applications are responsible for managing user consent grants within their own applications. They should provide users with a user interface to manage their consents. To access the Consent Management APIs, the Fintech application must authenticate itself (not the user) and can only access consent grants associated with its own client ID. The application needs to store consent IDs as there is no option to list all consents owned by the app for valid reasons.
-
Data Provider (Financial Institution or Data Access Platform) Consent Management: The APIs defined for Fintech applications cannot be used for self-management at the data provider’s (bank) side because these APIs do not support fetching consents created with multiple clients. While the API signatures may be the same, the policy applied to these APIs must be different to allow cross-client operations on consent grants. Additionally, there is a need for an API to list all user grants, which is not currently defined by the specification.
-
Bank Admin Consent Management: There is a third use case where bank administrators need to manage and list consent grants. They require more advanced filtering options, such as listing grants for specific users or filtering based on consent validity and parties involved.
It is important to note that consent APIs are not provided by default within an OAuth authorization server. Implementing FDX and utilizing an OAuth authorization server requires significant effort and complexity. By opting for the Cloudentity platform, the complexities of implementing consent management applications can be alleviated, providing a more streamlined and efficient solution.
This article primarily focuses on use cases 2 and 3, highlighting the integration and management of consent grants for data providers (banks) and their administrators. The specific needs and APIs associated with these use cases will be elaborated upon to provide a comprehensive understanding.
FDX Consent Management APIs
Cloudentity offers a comprehensive set of APIs to Financial Institutions, enabling them to manage all FDX consents granted for a specific Fintech Application. These APIs provide the capability to filter and view detailed information about consent grants. Additionally, Financial Institutions can utilize these APIs to revoke individual consents or revoke all consents granted for a particular Fintech Application.
By leveraging the APIs provided by Cloudentity, which will be further described in detail below, you will have the tools necessary to develop and integrate a Consent Self-Service application for customers. Moreover, you can create a Consent Admin application for Financial Institutions, allowing them to effectively manage all consent grants associated with the Fintech Applications connected to their institution.
Quickstart
Cloudentity offers FDX quickstart that can be used as reference application to build your own FDX consent management applications and showcases how you can integrate FDX workflows with the Cloudentity platform. Additionally, if you need guidance on how to use reference portals, see Using reference consent self-service and admin portals article.
Consent Listing
Sample request:
curl --request POST \
--url https:///localhost:8443/default/default/servers/default/fdx/consents \
--header 'Authorization: Bearer <BEARER_TOKEN>' \
--data '{"limit":20,"resource":{"ids":["b14e1e714693bc00"],"resourceType":"ACCOUNT"}'
200
Response code should be returned with FDX consents list if the request is successful.
You can use this API to fetch a list of FDX consent grants. Returned consent list list can be narrowed by using filters provided in the request body. Especially you can filter consents by client_id
to get all consents that were granted for a given Fintech Application (client). Another useful filter is resource
where you can provide a resourceType
, i.e. ACCOUNT
and a list of resource ids
which are values of the resource (in this case account numbers) that you are looking for. This enables you to get all consents granted for a given account.
There are also other filters available like limit
, order
, etc. that can be used for proper pagination implementation.
Single Consent Revocation
Sample request:
curl --request DELETE \
--url https:///localhost:8443/default/default/servers/default/fdx/consents/{consentID} \
--header 'Authorization: Bearer <BEARER_TOKEN>' \
--data '{"initiator":"DATA_ACCESS_PLATFORM","reason":"BUSINESS_RULE"}'
204
Response code should be returned with no response if a revocation is successful.
This API should be used when there is a need to revoke single consent by its id
which has to be passed in URL. There are also two mandatory parameters: Initiator
and Reason
which have to be provided in request body. Initiator
is a party that revokes a consent - available values are: DATA_ACCESS_PLATFORM
, DATA_PROVIDER
, DATA_RECIPIENT
, INDIVIDUAL
, MERCHANT
, VENDOR
. Reason
is a reason of consent grant revocation - it can be one of: BUSINESS_RULE
or USER_ACTION
Revocation of all consents for a given Fintech Application
Sample request:
curl --request DELETE \
--url https:///localhost:8443/default/default/servers/default/fdx/consents \
--header 'Authorization: Bearer <BEARER_TOKEN>' \
--data '{"RevocationDetails":{"initiator":"DATA_ACCESS_PLATFORM","reason":"BUSINESS_RULE"},"client_id":"fdx-developer-tpp"}'
204
Response code should be returned with number_of_consents_removed
in response body if a revocation is successful.
You can use this API if for some reason there is a need to revoke all consents for the given Finantial Application. Finantial Application whose consents are to be removed can be specified by client_id
parameter. Initiator
and Reason
which have to be provided in request body as for single consent grant revocation and will be applied to all revoked consents. In the response body you will get the nuumber of consent grants revoked.
List clients by authorization server
Sample request:
curl --request GET \
--url https:///localhost:8443/api/system/default/clients/{wid} \
--header 'Authorization: Bearer <BEARER_TOKEN>' \
200
Response code should be returned with Fintech application (client) list if the request is successful.
This API allows you to fetch all Fintech Applications registered within your FDX-compliant workspace in Cloudentity platform. It is worth to notice that within Cloudentity platform you may have more than one FDX compliant workspace (authorization server). You can use this API to display all Fintech Application for possible consent revocation. wid
parameter is the identificator of Authorization Server (workspace).
Client Application Authentication API
You must be able to authenticate your Application to Cloudentity when making your API requests. Use this API to obtain Access Token
needed by all APIs described above. The client application that you create in Cloudentity platform must be created within the System
workspace for your tenant (as you will be using System level APIs) and have the manage_openbanking_consents
scope assigned. Additionally for List clients by authorization server
API view_clients
scope needs to be assigned.
Management applications overview and integration
Having all necessary APIs described we can build custom Consent Self Service Application and Consent Admin Application and integrate them with Cloudentity.
Consent Self Service Application
Consent Self Service Application must be of the confidential client type. It means Consent Self Service Application must be able to store client credentials securely. Such credentials are used in the client credentials
OAuth grant flow. Remember to configure client credentials
while registering Consent Self Service Application in Cloudentity System Workspace. Also do not forget to enable granting manage_openbanking_consents
scope.
The example requests flow in consumer Self Service Application integrated with Cloudentity and using APIs described above can look like this:
(Cloudentity) user->>IDP: Authenticate user->>cd: Consumer is redirected cd->>acp: Request to /system/oauth2/token with `client credentials` grant type
& `manage_openbanking_consents` scope acp->>cd: Cloudentity Access token with `manage_openbanking_consents` scope cd->>acp: List FDX consents with `customer_id` and `ACCOUNT` `resource` with customer account id's in request body POST /fdx/consents Note over cd, acp: The request contains the token the Consent Self Service got in the 4th step acp->>cd: List of consent grants for the customer cd->>user: Display consents and its details user->>cd: Consumer browse consents user->>cd: Select consent for revocation cd->>acp: DELETE /fdx/consents/{consentID} Note over cd, acp: The request may contain the same token Consumer Dashboard
got in the 4th step if it is still valid.
If it is not, the dashboard must again authenticate itself.
Consent Admin Application
To build a Consent Self-Service Application, it is important to note that it should be of the confidential client type. This ensures that the application can securely store client credentials. These credentials are utilized in the client credentials
OAuth grant flow. When registering the Consent Self-Service Application in the Cloudentity System Workspace, remember to configure the client credentials
and enable the granting of the manage_openbanking_consents
scope.
It’s worth mentioning that you will need to develop this application yourself. However, Cloudentity provides a reference application that can serve as a valuable resource and guide during the development process.
The example requests flow in Consent Admin Application integrated with Cloudentity and using APIs described above can look like this:
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. end alt Admin wants to revoke all consents for given Fintech Application user->>cap: Admin accesses the view with Fintech Applications cap->>acp: GET /clients/{wid} Note over cap, acp: The request may contain the same token the admin portal
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. acp->>cap: List of Fintech Applications connected to the FDX workspace cap->>user: Display list of Fintech Applications user->>cap: Select Fintech Application for revocation cap->>acp: DELETE /fdx/consents with `client_id`, `Initiator` and `Reason` passed in request body Note over cap, acp: The request may contain the same token the admin portal
got in the 4th step if it is still valid.
If it is not, the portal must again authenticate itself. end
Summary
Above sections cover the APIs that Cloudentity makes available for you to easliy manage consent grants. FDX is still evolving to make consent management and all related notifications in this area smoother and more transparent for all parties involved. Now you have learned about of all the consent management related APIs to build a customized Consent Self Service and Consent Admin applications and a way how to integrate them with Cloudentity ecosystem.
Cloudentity offers a higly available SaaS region in North America. If you want to host the solution yourself, we offer the same binary and tools that we use to run our SaaS infrastructure to your DevOps team. Your team can run our high scale solution on the infrastructure of your choice. Read about all the offered deployment models here
Register for free to get access to a Cloudentity tenant and accelerate the FDX adoption journey with us!