Sandbox

Cloudentity offers CDR quickstart that you can use as a reference application to build your CDR consent management applications. Also, it showcases how you can integrate CDR workflows with the Cloudentity platform.

For guidance on how to use reference portals, see Using reference consent self-service and admin portals.

Consent Administrator Portal

Consent administrator portals are tools for Data Holder administrators to manage the arrangements on behalf of consumers. The following options are available:

• View consents for a given account.

• See arrangement details.

• Withdraw arrangements on behalf of the consumer.

• View all data recipients the consumer authorized at any point.

• Revoke all arrangements issued to all users and tied to the specified data recipient.

Requirements

1. Applications connected to the consent administrator portals must meet the confidential client type requirement to store client credentials securely. This requirement is essential since the Client Credentials grant type is applied to the part of API requests.

2. Consent administrator portal applications must be created within the System workspace of your Cloudentity tenant since you’ll be calling the system-level APIs.

   System Workspace

   Access to the System workspace is behind a feature flag. To request access to the System workspace, contact Cloudentity Sales Team.

3. Consent administrator portal applications must have the manage_openbanking_consents scope assigned.

   Add New Scope

   When you have no manage_openbanking_consents scope available for assigning to your application, add it to the required CDR service first. Then, you can assign it to your client app.

4. The same scope is recommended to be explicitly defined when calling the /token endpoint. Pass it as the value of the scope parameter to make the flow compliant with the best security practices.

5. Upon authentication, the administrative app must provide account numbers for a consumer automatically. For this, integration with the underlying data API is required. Alternatively, you can provide account numbers as the input data to Cloudentity APIs.

Based on the application architecture and security required within the CDR ecosystem, you can integrate your consent administrator portal app per one of the following patterns:

• Trusted System Token Pattern. The straightforward pattern applicable for cases where all actors are tightly integrated.

• User Bound Trusted System Token Pattern. This pattern allows user context transfer across the system actors and boundaries. An access token must be obtained applying the JWT Bearer Flow.

Integration Per Trusted System Token Pattern

According to this pattern, administrator calls the endpoints on behalf of the user, providing only the essential info, like customer identifier. The Client Credentials grant type is applied to the Trusted System Token pattern for authorization. No additional operations with tokens are required.

Integration Per User Bound Trusted System Token Pattern

This pattern requires obtaining a token bound to the subject (the administrator) and audience (the authorization server URL) to get the requested data. As a result, the token issued is bound to this info, and user authorization context is passed across system boundaries for more effective auditing.

To integrate your Consumer Dashboard with Cloudentity, use the following APIs:

Authentication (step 7)

POST OAuth 2.0 token endpoint

Authenticate your consent admin portal to Cloudentity.

The consent admin portal calls the /token endpoint for the only purpose of authenticating itself before calling Cloudentity consent APIs.

Authentication can be performed before steps 9, 13, 15, and 19 as well.

Fetching arrangements (steps 9 and 13)

POST List CDR Customer Arrangements

This endpoint returns a list of CDR arrangements for a required customer.

With it, you can provide administrators the list of all consents for a given consumer.

To narrow the list down, pass filters in the request body.

Fetching clients

GET List Clients by Authorization Server

Fetch all client applications (in this case, client applications from Data Recipients) registered within your CDR-compliant workspace.

For example, this allows the administrator to revoke all consents for the required Data Recipient software.

Getting arrangement details

GET Get CDR Arrangement by ID

Obtain the details of a specific consent after the consumer selects an arrangement on the consent page.

This allows you to display the arrangement details to the consumer.

Revocation

DELETE Revoke CDR Arrangement by ID

Revoke an arrangement.

Pass the identifier of the required arrangement as the path parameter.

Bulk revocation

DELETE Revoke CDR Arrangements

Revoke all CDR arrangements for a workspace. Pass the workspace identifier in the path.

Also, you can pass the client application identifier in the query to revoke all CDR arrangements for the given data recipient app.

Adjust Access Token

As per the User Bound Trusted System Token pattern, the access token must be obtained using the JWT Bearer flow. For user context passing across system boundaries, the access token must include the customer_id claim.

The following Cloudentity APIs require the access token to be obtained in such a way:

• GET List CDR Customer Clients

• DELETE Revoke CDR Customer Arrangements

• POST List CDR Customer Arrangements

To get an access token using the JWT Bearer Flow with the customer_id claim included, follow the steps listed below.

Key Generator Tool

Generate a public and private keypair. You can use any algorithm type, for example RS256 or ES256. Save your keys securely.

Cloudentity Tenant

1. Set up your System workspace and configure token claims:

   • Enable the JWT Bearer Grant Type.

   • Add the customer_id attribute under AuthN Context.

   • Add the customer_id attribute to the identity provider you use for authentication.

     Map it with the AuthN Context attribute.

   • Add the customer_id claim to access tokens issued for the workspace.

     Source type: AuthN context

     Source path: the customer_id attribute from the AuthN Context.

     Adding Claims with Data Lineage

     You can use Cloudentity Data Lineage to configure token claims. In this case, a scope of the same name is created automatically. As a result, you only need to request this scope when calling the /token endpoint to obtain an access token.

2. Create a client application. Go to its page to configure settings under the following tabs:

   • OAuth:

     Option	Value
     Trusted	ON
     Grant Type	JWT Bearer
     JSON Web Key Set (JWKS)	The private key generated with the key generator tool

     Client Authentication

     It’s recommended to use secure methods for Consent Administrator Portal client applications. For example, OAuth 2.0 Mutual TLS Client Authentication.

   • Scope:

     Option	Value
     Your client app service	manage_openbanking_consents

JWT Generator Tool

1. Create a JSON Web Token (JWT). Add the customer_id parameter along with the required value to the token’s payload.

   All mandatory claims must be included in JWT as well.

2. Sign the JWT with the private key you created with the key generator tool.

Obtain Access Token

Call the Cloudentity OAuth 2.0 token API to get an access token for your client application.

In your request to the /token endpoint:

• Set the grant_type parameter to urn:ietf:params:oauth:grant-type:jwt-bearer

• As the value for the assertion parameter provide your signed JWT.

• Use the client authentication method that you set for the Consent Admin Portal’s client application.

• Define the manage_openbanking_consents scope.

Sample cURL

curl -X POST https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/system/oauth2/token -v \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-raw "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&assertion=$SIGNED_JWT&scope=manage_openbanking_consents"

Use the access token obtained to call endpoints per User Bound Trusted System Token pattern.

Next Steps

• Add a custom consent page for customizing user journey following CX guidelines
• Build consumer consent self-service dashboard
• Plan towards achieving CDR conformance with all systems integrated together