How-tos

CDR Quickstart

Quickly see all the CDR actors in action and also understand Cloudentity capabilities and the customer journey in CDR.

CDR Quickstart

Cloudentity has created a reference Open Banking Quickstart GitHub project that helps to understand different CDR actors and workflows and how all these are integrated with the Cloudentity platform. Cloudentity Open Banking Quickstart is built to showcase multiple open data initiatives across the world and CDR is one of such initiatives riding on top of FAPI standards for secure API interaction with consumer consent.

This quickstart allows you to either quickly spin up a local dockerized version of Cloudentity solution or connect to a SaaS tenant. You may choose and proceed with one of the option for quick verification of the platform capabilities.

For the demonstration purposes, this article contains references to artifacts created as reference apps by CDR regulators:

Above reference applications have a built in Identity Server implementation but, as a part of this article, you will swapp that out with Cloudentity solution that offers more powerful, flexible and dynamic authorization for CDR & FAPI compliance.

Clone the Repo

Git clone the Cloudentity repo with Open Banking Quickstart artifacts. There is a README within the project to quickly set up the required pre-requisites.

git clone git@github.com:cloudentity/openbanking-quickstart.git

Cloudentity SaaS vs Local

Before proceeding further, decide on whether you want to utilize Cloudentity platform in SaaS(preferred) or deploy Cloudentity solution in a machine locally.

Cloudentity-cdr-reference-apps-layout

Note

To access Cloudentity solution in local deployment, make a host entry in local file system for 127.0.0.1 authorization.cloudentity.com. All the components are auto configured to use Cloudentity in a local mode.

Tip

To use the Cloudentity SaaS platform, signup for a free tenant and utilize the tenant url and endpoints in the configuration for your environment.

Connect apps with Cloudentity

All the references application must be able to connect/consume Cloudentity for various workflows as shown below.

cloudentity-cdr-reference-apps-integration

Tip

Below configurations are already in place for running these locally. Attached configurations and instructions are for educational purposes or in case you need to point to a different environment/location for Cloudentity services.

Configure Data Recipient

Data recipients must register with the registry first to register their software product. Once registered, recipients are issued a software statement assertion and are accredited. We will refer to these as accredited data recipients (ADR). In this reference application, mock-data-recipient takes the role of ADR and is registered with mock-register for accreditation. Once that is done, it needs to interact with Cloudentity to perform DCR to register itself to obtain data from Data Holder. Cloudentity is part of Data Holder ecosystem and provides the security profile implementation, so all the Oauth & FAPI related endpoints are exposed by Cloudentity that need to be consumed by ADR to obtain consumer consent and access tokens to access data APIs.

In the Quickstart environment, it is possible to configure the mock-data-recipient by adjusting the environment variables in the additional_configuration.sh script. The script generates a recipient.json file out of the recipient.template and mounts it as the configuration for the mock recipient when running make run-cdr-local command.

Configure Data Holder

Data Holder application requires configuration of the CDR security profile provider(aka Cloudentity).

In the Quickstart environment, it is possible to configure the mock-data-holder by adjusting the environment variables in the additional_configuration.sh script. The script generates a holder.json file out of the holder.template and mounts it as the configuration for the mock holder when running make run-cdr-local command.

Deploy Applications

To run the reference applications, there are certain pre-requisites and the details can be found in the repo README.

make run-cdr-local

Application Access

Once the applications are deployed and running, you can access the following components at below mentioned urls.

  • Cloudentity admin portal: https://authorization.cloudentity.com:8443/app/default/admin admin / admin
  • CDR data recipient: https://localhost:9001/

ADR Configurations

Now that you have all the applications deployed and connected to the Cloudentity authorization platform, you need to get into the reference data recipient application.

  1. Verify configuration.

    The reference mock-data-recipient application has screens that shows integration configurations with mock-registry and mock-data-holder components. Let’s quickly verify the application settings are accuratelly configured to talk to the Cloudentity authorization platform.

    Navigate to https://localhost:9001/settings. The following settings should be pointing to the Cloudentity authorization platform:

    • DataHolder - infosecBaseUri

    • DataHolder - jwksUri

    • DataHolder - oidcDiscoveryUri

    • DataHolder - registrationEndpoint

    cdr_qs_mock_adr_settings.png

  2. Load data holder registrations

    Now, let’s load the data holder registrations seeded from registry onto this app. Click on Refresh within the Discover Data Holders panel.

    cdr_qs_load_dh_from_registry

ADR Client Registration

  1. Register client using DCR

    This action registers a client application (representing ADR) in Cloudentity. Initiate the app registration process in the mock-data-recipient application.

    cdr_qs_dcr

    cdr_qs_dcr_app_registered

    Tip

    In real implementation, ADR registers against your Cloudentity tenant. Cloudentity CDR workspace has DCR enabled by default, more details about DCR capability in Cloudentity can be found here

  2. Check client registration in Cloudentity

    Navigate to the Cloudentity tenant and choose the CDR workspace profile. Navigate to Applications. You will see a client application that is registered and all appropriate CDR scopes assigned to the application.

    cdr_qs_dcr_client_app

    cdr_qs_dcr_consents

  1. Construct consumer authorization

    Accredited Data Recipients(ADR) must initiate an OAuth authorization request with the client application registered above to get required consumer consents to fetch consumer data from Data Holder. To construct the OAuth authorization URL, navigate manually to Consent screen in Data Recipient application and choose the Data Holder against which the authorization needs to be trigerred.

    cdr_qs_consent_request_construct

    cdr_qs_consent_request_url

  • Initiate consumer authorization

    Now that we have the authorization url, data recipient ideally would redirect user to the authorization URL. Since this is a technical reference app, you will just copy the URL from above screen and paste into a browser. This call will initiate an OAuth authorization request to the Cloudentity authorization platform. Cloudentity platform redirects the user to the Data holder authentication provider. By default, we have configured a mock identity provider in Cloudentity, so the user can login. (use user/p@ssword! as credentials). Once authenticated, the Cloudentity platform serves the consent application to the user. Consent application is served based on the Cloudentity authorization server setting, for example based on default setting, it redirects the user to http://localhost:7080.

cdr_qs_consent_setup_acp

cdr_qs_sample_consent_app.png

Once user consents to the application, Cloudentity platform stores the consents and issues relevant authorization tokens back to Data Recipient application. The user is redirected back to the mock-data-recipient application.

Tip

Keep in mind the consent app is just a reference application and we recommend you to build your own consent application with rich user and customer journery experiences. To build you own consumer consent application, follow these articles:

Cloudentity-cdr-reference-apps-saas

As the result, the data recipient obtaines the consumer consent to fetch their data from Data Holders. Data Recipient can now use the consent in the form of access tokens to call the Data Holder data APIs.

Invoke CDR API’s

Now that we have the cdr-arrangement-id and associated accessToken, we can invoke the API’s exposed by the data-holder using the accessToken..

cdr_qs_cdr_api

Sample curl where the $AT environment variable stands for the access token:

curl -kv -X  'GET' \
  'https://datarecipient.mock:9001/data-sharing/proxy/cds-au/v1/banking/accounts?open-status=ALL&page=1&page-size=2' \
  -H 'accept: application/json' \
  -H 'x-v: 1' \
  -H 'x-inject-cdr-arrangement-id: c7mf3n75ajjjteq461ig' \
  -H 'x-fapi-auth-date: Fri, 01 Jan 2021 00:00:00 GMT' \
  -H 'Authorization: Bearer $AT'

This mock data holder application does not showcase how to completely protect Data holder API. To learn more about it, see the Consumer data API access & protection article.

Manage Consents

CDR specifies that consumer should be able to manage their own consents and should be able to revoke them at any point. To manage all the consents and view the access token, ID token, and to see and revoke all the consents, the Data Recipient application provides some UI interfaces.

Cloudentity-cdr-reference-apps-saas

To build you own consumer consent management dashboards, follow these articles:

Cleanup

If you want to clean up all the locally deployed resources, use the following command:

make clean
Updated: Jul 12, 2022