CDR DH API protection

This article provides an overview of protecting Data Holder(DH) APIs exposed by Data Holder ecosystem using the CDR compliant authorization tokens issued by Cloudentity authorization platform.

Data Holder API access requirement

Data Holders can share the industry specific OpenData APIs, as outlined in CDR specification, with Accredited Data Recipient (ADR) systems after ensuring authorization of the data request. One of the major CDR requirements is to ensure consumer data is being released to requesting ADR only after ensuring the ADR has presented the consumer consent captured in some manner.

Consumer consent is represented as an CDR arrangement identifier and is avaialable as 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.

CDR data API access protection

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

AccessTokens issued by Cloudentity platform is timebound. Cloudentity CDR profile workspace has a default access token lifetime of 10 minutes(max limit recommended by 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.

Authorization tokens presented by ADR must be verified by Data Holder’s API gateway or any similar component that is responsible for handling the Data Holder API traffic.

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

Using Cloudentity Authorizers
Using Api Gateway introspections

Cloudentity authorizers vary based on different types of API Gateway implementations as described in the protecting endpoints and controlling access articles.

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 Holder in their existing API gatewat. Usage of Cloudentity authorizers to enforce data access is up to the discretion of Data Holder. Cloudentity authorizers have the added benfit of enforcing validatity of authorization tokens presented, checking additional data API access policy, and also can push the API access authorization decision audit events back to Cloudentity platform for detailed auditing and time series based metrics.

sequenceDiagram Title: CDR Data API access with Cloudentity authorizer autoNumber participant adr as Data Recipient(ADR) participant ce as Data Holder -
Infosec provider
(Cloudentity) participant dhapigw as Data Holder -
API GW participant dh as Data Holder -
API service adr->>ce: Obtain CDR compliant accessToken Note right of adr: Authn, authz and consent flow details
omitted for brevity ce->>adr: accessToken containing cdr_arrangement_id adr->>dhapigw: Call data api endpoint alt API access authorization by Cloudentity Authorizer Note right of dhapigw: Cloudentity authorizer will introspect
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 cdr arrangement details dh->>dh: Process response data based on
cdr arrangement and agreements dh->>adr: API response end alt Authorization failure dhapigw->>adr: Deny API traffic end

Verification using API gateway extensions

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

sequenceDiagram Title: CDR Data API access with API GW introspection autoNumber participant adr as Data Recipient(ADR) participant ce as Data Holder -
Infosec provider
(Cloudentity) participant dhapigw as Data Holder -
API GW participant dh as Data Holder -
API service adr->>ce: Obtain CDR compliant accessToken Note right of adr: Authn, authz and consent flow details
omitted for brevity ce->>adr: accessToken containing cdr_arrangement_id adr->>dhapigw: Call data api endpoint alt API access authorization by APIGW extensions Note right of dhapigw: API GW/extensions itself
should introspect and validate tokens and
acts as policy decision point dhapigw->>dhapigw: Validate presented accessToken dhapigw->>ce: Fetch jwks ce->>ce: jwks (cache response) dhapigw->>ce: Introspect accessToken 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 cdr arrangement details dh->>dh: Process response data based on
cdr arrangement 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 continue onto its destination data API based on the scopes, account identifier, customer identifier, and subject involved based on the introspect response.

API Integrations

To integrate data holder with Cloudentity, use the following APIs as depicted in above sequence diagrams:

Introspect CDR token

This is a dedicated API provided by Cloudentity to allow introspection of CDR access token by internal data holder components. Introspect CDR access token expects the CDR access token in request body. Calling application should get a Cloudentity access token with introspect_openbanking_tokens scope and provide that as Bearer token while calling this API.

Get CDR Arrangement

It may be required that the Data API implementation layer would require the knowledge about the CDR arragement agreement to make further decision within the Data API implementation layer.

There can be mulitple approaches to address this

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.

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

To invoke the Get CDR Arrangement by ID API:

Register a client application in the CDR-compliant workspace with the client_credentials grant type set and assign the 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.