Data Holder API Access Requirement

Data Holders can share the industry-specific OpenData APIs for banking and energy sectors, as outlined in CDR specification, with Accredited Data Recipient (ADR) systems after ensuring the calling application is authorized to access the requested data set. One of the important CDR requirements is to ensure consumer data is being released to requesting ADR only after confirming the ADR has presented the consumer consent proof in some manner.

Consumer consent is represented as a CDR arrangement identifier and is available as a claim within the OAuth compliant access tokens. ADR should present these access tokens to the Data Holder API endpoints to access the data authorized by consumers.

Data API Access Verification

While calling the Data APIs as specified in the CDR specification, the ADRs 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 CDR compliant workspace has a default access token lifetime of 10 minutes(max limit recommended by the CDR specification) but can be configured within the Cloudentity Administrative Control Plane to reduce the lifetime of accessToken. Cloudentity recommends lower time-to-live for access tokens to reduce the attack surface.

Data Holder’s API gateway or a similar component responsible for handling the API access traffic must verify the authorization tokens presented by ADR.

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

• Using Cloudentity Authorizers

• Using Api Gateway introspections

Cloudentity authorizers offers solution for various API Gateway implementations as described in protecting endpoints and controlling access articles.

Verification using Cloudentity Authorizer

Cloudentity provides microsatellites that can be plugged into any existing API gateway that can offload this functionality being implemented by the Data Holder in their existing API gateway. Usage of Cloudentity authorizers to enforce data access is up to the discretion of the Data Holder. 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.

Verification using API gateway extensions

Data holder API interception points can invoke the CDR Introspect API endpoint generally exposed for Data Dolder components to verify the presented authorization token.

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 holder with Cloudentity, use the following APIs as depicted in the above sequence diagrams.

Introspect CDR token

Cloudentity provides a dedicated API to allow introspection of CDR access tokens by internal data holder components. Introspect CDR access token API expects the CDR access token in request body. The response of this API will have the CDR arrangement id and details of the arrangement in the response

..
"cdr_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"
},
"cdr_arrangement_id": "string",
..

Tips - API access

Register a client application in the CDR 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 Introspect CDR access token API

Get CDR Arrangement

It may be required that the Data API implementation layer would require the knowledge about the CDR arrangement agreement 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 CDR Arrangement by ID 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 CDR 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 CDR Arrangement by ID API.