FDX Consent APIs

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 Authorization 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"
                  ]
               }
            ]
         }
      }
   ]
}            

SecureAuth 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, SecureAuth 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 - SecureAuth 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 - SecureAuth 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 - SecureAuth 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"
}