How-tos

6 mins read

FDX Consent APIs

If you are a Financial Institution looking for advanced OAuth server that allows you to build FDX compliant consent page, this article describes the integration pattern that Cloudentity provides for our customers to build and integrate consent pages with Financial ecosystem.

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.

End user consent in FDX is of the utmost importance to support the core FDX principles especially the Control, Access, Traceability and Transparency principle which directly talks about the permissions on user data:

  • Control - consumers should be able to permission their data for services and applications.

  • Access - consumers should have access to their data and the ability to determine who has access to their data.

  • Transparency - consumers should be able to learn how, when, and for what purpose their data is used. Only the absolutely required data should be shared with the consuming service or application.

  • Traceability - All data transfers should be traceable. Consumers should be able to learn about all entities within the user-permissioned financial data ecosystem and that are involved in the data sharing flow.

Below, you can see a simplified consent experience scenario that involes an end user, a financial institution that holds the data of the user, and a fintech application that requests access to the user data.

FDX user consent journey

The FDX specification defines how data recipients must make consents requests. It covers how data providers should respond to consent requests and get the user’s permissio to share their data.

FDX relies on OAuth 2.0 Rich Authorization Request (RAR) and Pushed Authorization Request (PAR) extension profiles to be used by data recipients to convey the creation of a consent request.

In FDX, data recipient discloses the parameters of the consent request to the End User; Data Provider collects authorization from End User; Data Provider provides the record of consent to the data recipient.

Cloudentity provides Consent APIs and capabilities as per FDX guidelines that allows each of the above parties to:

  • Initiate Consent Request
  • Capture Consent Grant
  • Retrieve/Query Consent state
  • Revoke Consent

As mentioned above, FDX relies on OAuth 2.0 Rich Authorization Request (RAR) and Pushed Authorization Request (PAR) extension profiles to be used by data recipients to convey the creation of a consent request.

Data recipient initiates a POST request to data providers /par endpoint using the Pushed Authoirzation Request (PAR) method. Within this request object, the authorization_details request parameter must contain a JSON-formatted payload that has the ConsentRequest entity as per the RAR format.

{
   "authorization_details":[
      {
         "type":"fdx_v1.0",
         "consentRequest":{
            "durationType":"ONE_TIME",
            "lookbackPeriod":60,
            "resources":[
               {
                  "resourceType":"ACCOUNT",
                  "dataClusters":[
                     "ACCOUNT_DETAILED",
                     "TRANSACTIONS",
                     "STATEMENTS"
                  ]
               }
            ]
         }
      }
   ]
}

Cloudentity supports PAR out-of-the-box and no further configuration is required othen than enforcing it on the authorization server level or client application level.

Once the consent intent is registered with the data provider, the data provider returns a valid URI to continue if it meets the specification of the intent. Then, Cloudentity validates the presented PAR request and returns the request_uri to the data recipient application to enable it to construct a request to the OAuth 2.0 authorize endpoint.

Once the request_uri is returned to the data recipient, it can request the authorization of the request from the data provider explictly using the GET call to OAuth 2.0 authorize endpoint. Data provider redirects the user to authenticate with its system and displays the consent authorization prompt/page.

This page is driven as per the FDX consent user guidelines.

Following the OAuth specification, once the authorization flow is complete, the data provider using the POST request to the /token to get an access token which includes the OAuth-compliant contents along with the FDX-specific grant_id parameter containing the ConsentId.

Sample response:

{
  "access_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6IjIzNzcyODUzMDQzODY5MDQzNjY3NTYxNzg3ODcyOTUzNjE2MTIxOSIsInR5cCI6IkpXVCJ9.eyJhY3IiOiIxIiwiYWlkIjoiZmR4IiwiYW1yIjpbInB3ZCJdLCJhdWQiOlsiYnVrajVwNms3cWRtbTVmZEpqSnZoRyIsInNwaWZmZTovL2F1dGhvcml6YXRpb24uY2xvdWRlbnRpdHkuY29tL2RlZmF1bHQvZmR4L2ZkeC1wcm9maWxlIiwic3BpZmZlOi8vYXV0aG9yaXphdGlvbi5jbG91ZGVudGl0eS5jb20vZGVmYXVsdC9mZHgvZmR4LWZkeCJdLCJjbmYiOnsieDV0I1MyNTYiOiJueUotYm9XYy1NVVFnQWU3YzJGcHkyM2VuU2ltNS1lS2FHZ0M4ZEhtWVg0In0sImV4cCI6MTY2NTcyNTAwNSwiaWF0IjoxNjY1NzI0NDA1LCJpZHAiOiJidWdrZ2FpM2c5a3JlZ3R1MDR1MCIsImlzcyI6Imh0dHBzOi8vYXV0aG9yaXphdGlvbi5jbG91ZGVudGl0eS5jb206ODQ0My9kZWZhdWx0L2ZkeCIsImp0aSI6IjhhOWM0ZmM4LTNkZjYtNGI3ZS05ZDYzLTE5NGIzODI2N2QxMCIsIm5iZiI6MTY2NTcyNDQwNSwic2NwIjpbIm9wZW5pZCIsIlJFQURfQ09OU0VOVFMiLCJVUERBVEVfQ09OU0VOVFMiXSwic3QiOiJwYWlyd2lzZSIsInN1YiI6ImMyZTQ3MTI1Yzg3ZGU0ZTIzNjA4OTI1YWQzMmQ5MzMwYzYyNjhlYjQ0OTI0OTIyNGZiMDEwMDVhNGNjYzQzYWQiLCJ0aWQiOiJkZWZhdWx0In0.maVXt7ygsjzFvX2eOWtEfo4_FPU-Ja-6tJ65qqJjzY1VZaeTDS8K5oRD1_mX89_WB-sOFDAppETNw1S2Sk_9qyujpSrIey2xaZhe8B9VidFx5INZKBODMizKzWeKgIjnVTP7P43CZN3oOB9PPTGZFtH2qXX_EcoSiLSqS50WulDtWe5wj1clv1lTByXzrH28rH2_0Ir0ekvpVIoaCPl97mwmcwVWGBlGPnraX0hFt2IKQ5YLRAHvbEnv8PagM5v9rscSAyryg2aTXhBQ0HubuPB-P0KSHHcWgr7UoVYRSMXphGlYCUT-j4iLuXVjiXHN1fXzgjx0ylJv-6kmFJxfNQ",
  "id_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6IjIzNzcyODUzMDQzODY5MDQzNjY3NTYxNzg3ODcyOTUzNjE2MTIxOSIsInR5cCI6IkpXVCJ9.eyJhY3IiOiIxIiwiYW1yIjpbInB3ZCJdLCJhdWQiOiJidWtqNXA2azdxZG1tNWZkSmpKdmhHIiwiYXV0aF90aW1lIjoxNjY1NzI0NDAxLCJleHAiOjE2NjU3MjUwMDUsImlhdCI6MTY2NTcyNDQwNSwiaWRwIjoiYnVna2dhaTNnOWtyZWd0dTA0dTAiLCJpZHBtIjoic3RhdGljIiwiaXNzIjoiaHR0cHM6Ly9hdXRob3JpemF0aW9uLmNsb3VkZW50aXR5LmNvbTo4NDQzL2RlZmF1bHQvZmR4IiwianRpIjoiNTU2ZjM1NDEtYTM2My00YjBkLTgzYjQtMzVhZTM5MWViMDA1IiwicmF0IjoxNjY1NzI0NDA1LCJzdWIiOiJjMmU0NzEyNWM4N2RlNGUyMzYwODkyNWFkMzJkOTMzMGM2MjY4ZWI0NDkyNDkyMjRmYjAxMDA1YTRjY2M0M2FkIn0.xaLFzdkHoWIpAFywylanRRLmgBnKMpca6EjgLeZ0Os8S0Iw9E-o66c8ZhFfuvdQohWnGNDI7BxzAskkQ6yAd21S3OK3ZI0lsHwkjcnjc5UXyy9aqE0e7F0tLqQdGUxPRVwN8hMWc2L_w7yDaduIRtCjupmlBdTOqOfw78oM-V5W9PMQXZCi4MEkMtqNzxmJwx8BIUPPS7fpOtTuFRtmKnPrxmAfUK_mvrlmm1NSdl10NE70dYyu8YK87TGDhkoRTBcR9xFtQgyFuLougDggg4gsiJ4NOJLbBegimSalnbSnjSmrwkwcTwif7P4_H_h64n2shtSETbxYVgDSjjnIUeQ",
  "refresh_token": "",
  "token_type": "bearer",
  "scope": "openid READ_CONSENTS UPDATE_CONSENTS",
  "expires_in": 599,
  "grant_id": "b80713711b2b4331928d30183df33cb0"
}

Sample FDX compliant access token:

{
  "acr": "1",
  "aid": "fdx",
  "amr": [
    "pwd"
  ],
  "aud": [
    "bukj5p6k7qdmm5fdJjJvhG",
    "spiffe://authorization.cloudentity.com/default/fdx/fdx-profile",
    "spiffe://authorization.cloudentity.com/default/fdx/fdx-fdx"
  ],
  "cnf": {
    "x5t#S256": "nyJ-boWc-MUQgAe7c2Fpy23enSim5-eKaGgC8dHmYX4"
  },
  "exp": 1665725005,
  "iat": 1665724405,
  "idp": "bugkgai3g9kregtu04u0",
  "iss": "https://authorization.cloudentity.com:8443/default/fdx",
  "jti": "8a9c4fc8-3df6-4b7e-9d63-194b38267d10",
  "nbf": 1665724405,
  "scp": [
    "openid",
    "READ_CONSENTS",
    "UPDATE_CONSENTS"
  ],
  "st": "pairwise",
  "sub": "c2e47125c87de4e23608925ad32d9330c6268eb449249224fb01005a4ccc43ad",
  "tid": "default"
}

Such an access token means that the end user authorized the data provider’s application to access their (user’s) resources. The data provider passes the reference to that information to the data recipient in the grant_id parameter (within the token). The data recipient must securely store the access token and the grant_id for further interactions with the data provider.

Once the data recipient has the access token, it can query the ConsentGrant from the data provider using a dedicated API as recommended by FDX. In the below URL, {consentID} needs to be replaced with the grant_id which was provided to the data recipient when fetching a token.

Get Consent Grant - Cloudentity API specification

Sample request:

curl --request GET --url https://localhost:8443/default/default/consents/{consentID}

Sample response:

{
  "authorization_server_id": "string",
  "client_id": "string",
  "createdTime": "2019-08-24T14:15:22Z",
  "durationPeriod": 0,
  "durationType": "string",
  "expirationTime": "2019-08-24T14:15:22Z",
  "id": "string",
  "lookbackPeriod": 0,
  "parties": [
    {
      "homeUri": "string",
      "logoUri": "string",
      "name": "string",
      "registeredEntityIdentifier": "string",
      "registeredEntityName": "string",
      "registryName": "string"
    }
  ],
  "resources": [
    {
      "dataClusters": "ACCOUNT_DETAILED TRANSACTIONS STATEMENTS",
      "id": "b14e1e714693bc00",
      "resourceType": "ACCOUNT"
    }
  ],
  "revocationReason": {
    "initiator": "\"INDIVIDUAL\"",
    "reason": "\"USER_ACTION\""
  },
  "status": "string",
  "tenant_id": "string",
  "updatedTime": "2019-08-24T14:15:22Z"
}

A ConsentGrant can be revoked at any point by any party involved in the consent flow triggered by the end user.

Revoke FDX Consent - Cloudentity API specification

Sample request:

curl --request PUT --url https://localhost:8443/default/default/consents/{consentID}/revocation

Sample response:

{
  "initiator": "\"INDIVIDUAL\"",
  "reason": "\"USER_ACTION\""
}

Once a ConsentGrant is revoked, interested parties can find the details about the revocation of a particular consent.

Retrieve Consent Revocation Record - Cloudentity API specification

Sample request:

curl --request GET --url https://localhost:8443/default/default/consents/{consentID}/revocation

Sample response:

{
  "initiator": "DATA_RECIPIENT",
  "reason": "BUSINESS_RULE",
  "status": "string",
  "updatedTime": "2019-08-24T14:15:22Z"
}

Summary

Above sections cover the APIs that are currently specified by FDX. FDX is still evolving to make consent management and all related notifications in this area smoother and more transparent for all parties involved. Now that you have got an idea of all the consent related APIs, follow our custom consent application builder tutorial to build a customized consent page for your end user.

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!

try now
Updated: Apr 14, 2023