How-tos

FDX Data Provider API Protection

This article provides an overview of how how data providers within the FDX ecosystem can protect their APIs exposed for the purposes of financial data sharing.Learn how data providers can use FDX-compliant security tokens and consent grants issued by the Cloudentity platform.

Data Provider API Access Requirement

Data providers can share the industry-specific OpenData APIs with data recipient (DR) or Data access platforms after ensuring the calling application is authorized to access the requested data set. One of the important FDX requirements is to ensure consumer data is being released to requesting data recipient only after confirming the data recipient has presented the consumer consent proof in some manner.

Consumer consent is represented as a FDX consent grant identifier and is available as a claim within the OAuth compliant access tokens. DRs should present these access tokens to the data provider API endpoints to access the data authorized by the consumers.

Financial data exchange ecosystem overview

FDX Data API Security And Access Control

While calling the data APIs as specified in the FDX specification, the DRs must present the authorization token obtained on behalf of the consumer from the Cloudentity authorization platform as Bearer token in the authorization header.

Tip - Best Practices

Access tokens issued by Cloudentity are timebound. Cloudentity FDX compliant workspace has a default access token lifetime of 10 minutes(max limit recommended by the FDX specification) but can be configured within the Cloudentity platform to reduce the lifetime of access token. Cloudentity recommends lower time-to-live for access tokens to reduce the attack surface.

Cloudentity provides out-of-the-box integration with multiple API gateways through localized authorizers. Irrespective what product you use to expose financial data APIs, you will be able to connect to it to apply security profile to APIs. Easily integrate with any of your existing API gateways to enforce data sharing conformance checks.

FDX API Gateways

There are a couple of ways to approach the API data access protection:

Cloudentity authorizers offer solution for various API Gateway implementations as described in API Gateway authorization with Cloudentity article.

Verification Using Cloudentity Authorizer

Cloudentity provides micro-satellites that can be plugged into any existing API gateway that can offload this functionality being implemented by the data provider in their existing API gateway. Usage of Cloudentity authorizers to enforce data access is up to the discretion of the data provider. Cloudentity authorizers have the added benefit of implementing the check for validity of authorization tokens presented, checking additional data API access policy, and also pushing the API access authorization decision audit events back to Cloudentity platform for detailed auditing and time series based metrics.

[mermaid-begin]
sequenceDiagram Title: FDX Data API access with Cloudentity authorizer autoNumber participant adr as Data Recipient (DR) participant ce as Data Provider -
Infosec provider
(Cloudentity) participant dhapigw as Data Provider -
API GW participant dh as Data Provider -
API service adr->>ce: Obtain FDX compliant access token Note right of adr: Authn, authz and consent flow details
omitted for brevity ce->>adr: access token containing grant_id adr->>dhapigw: Call data API endpoint alt API access authorization by Cloudentity Authorizer Note right of dhapigw: Cloudentity authorizer introspects
and validate tokens and acts as policy decision point dhapigw->>dhapigw: Attach Cloudentity authorizer to API flow and fetch decision response end alt Authorization success dhapigw->>dh: Forward API traffic dh->>ce: Fetch consent grant details dh->>dh: Process response data based on
consent grant and agreements dh->>adr: API response end alt Authorization failure dhapigw->>adr: Deny API traffic end

Verification Using API Gateway Extensions

Data provider API interception points can invoke the FDX Introspect API endpoint generally exposed for data folder components to verify the presented authorization token.

[mermaid-begin]
sequenceDiagram Title: FDX Data API access with API GW introspection autoNumber participant adr as Data Recipient (DR) participant ce as Data Provider -
Infosec provider
(Cloudentity) participant dhapigw as Data Provider -
API GW participant dh as Data Provider -
API service adr->>ce: Obtain FDX-compliant access token Note right of adr: Authn, authz and consent flow details
omitted for brevity ce->>adr: access token containing grant_id adr->>dhapigw: Call data API endpoint alt API access authorization by API GW extensions Note right of dhapigw: API GW/extensions itself
should introspect and validate tokens and
acts as policy decision point dhapigw->>dhapigw: Validate presented access token dhapigw->>ce: Fetch jwks ce->>ce: jwks (cache response) dhapigw->>ce: Introspect access token ce->>ce: introspect response dhapigw->>dhapigw: Check the introspected response
for scope checks/enforcement end alt Authorization success dhapigw->>dh: Forward API traffic dh->>ce: Fetch FDX consent grant details dh->>dh: Process response data based on
consent grant and agreements dh->>adr: API response end alt Authorization failure dhapigw->>adr: Deny API traffic end

The API gateway component can decide whether to let the traffic to its destination data API based on the scopes, account identifier, customer identifier, and subject involved based on the introspect response.

API Integrations

To integrate the data provider with Cloudentity use the following APIs as depicted in the above sequence diagrams.

Introspect FDX Token

Cloudentity provides a dedicated API to allow introspection of FDX access tokens by internal data provider components. FDX Introspect API expects the FDX access token in the request body. The response of this API has the FDX grant_id (consent identifier) and details of the consent in the response.

..
"fdx_arrangement": {
  "account_ids": [
    "string"
  ],
  "amending_arrangement_id": "string",
  "authorization_server_id": "string",
  "cdr_arrangement_id": "string",
  "client_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "customer_id": "string",
  "expiry": "2019-08-24T14:15:22Z",
  "scope_grants": [
    {
    "client_id": "string",
    "given_at": "2019-08-24T14:15:22Z",
    "granted_scope_name": "string",
    "language": "string",
    "scope_name": "string",
    "server_id": "string",
    "subject": "string",
    "tenant_id": "string"
    }
  ],
  "sharing_type": "one_time",
  "spec_version": "v1",
  "status": "string",
  "subject": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z"
},
"fdx_arrangement_id": "string",
..

Tips - API access

Register a client application in the FDX-compliant workspace with the client_credentials grant type and assign introspect_openbanking_tokens scope to the client application.

For the above client app, get an access token from the Cloudentity authorization server token endpoint.

Use above token as the Bearer token to access the FDX Introspect API.

Get FDX Arrangement

It may be required that the Data API implementation layer requires the knowledge about the FDX consent grant to make further decisions within the Data API implementation layer.

There are multiple approaches to address this problem:

  • The data API implementation can call the Get Consent Grant API to fetch arrangement details.

  • API gateway or similar facade can inject the required details onto the request retrieved as headers, extra parameters, or extra payload during the introspection call above.

Cloudentity is not opinionated on that last mile and is up to the data API platform application architecture to pick the integration pattern based on their usage patterns.

Tips - API access

Register a client application in the FDX-compliant workspace with the client_credentials grant type and assign manage_openbanking_consents scope to the client application.

For the above client app, get an access token from the Cloudentity authorization server token endpoint.

Use above token as the Bearer token to access the Get Consent Grant.

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!

Updated: Oct 14, 2022