Overview
As per CDR specifications, Data Recipients must register with Data Holder according to OAuth 2.0 Dynamic Client Registration protocol. Cloudentity platform is part of Data Holder ecosystem facilitating all the security profile requirements, including all the OAuth capabilities to handle the dynamic client registration of Data recipient entities. Once registered, Data Recipients can utilize the registered client information to mint CDR compliant tokens from Cloudentity authorization platform to retrieve consumer data from the Data Holder in a secure manner.
Register Data Recipient with CDR Register
ACCC CDR Register acts as the central register where all the Data Recipients must first register their software. CDR Register issues software statement assertion (SSA) about a client software. A Software Statement Assertion (SSA) is a digitally signed JSON Web Token (JWT) created in accordance with JWT that asserts metadata values about the client software.
A sample decoded SSA issued by the CDR register looks like the following:
{
"alg": "PS256",
"kid": "542A9B91600488088CD4D816916A9F4488DD2651",
"typ": "JWT"
}
{
"recipient_base_uri": "https://tpp1.cdr.cloudentity-se.com:9001",
"legal_entity_id": "18b75a76-5821-4c9e-b465-4709291cf0f4",
"legal_entity_name": "Mock Software Company",
"iss": "cdr-register",
"iat": 1647997920,
"exp": 1647998520,
"jti": "5bf24030a32641c099f741d4286027d1",
"org_id": "ffb1c8ba-279e-44d8-96f0-1bc34a6b436f",
"org_name": "Mock Finance Tools",
"client_name": "MyBudgetHelper",
"client_description": "A product to help you manage your budget",
"client_uri": "https://mocksoftware/mybudgetapp",
"redirect_uris": [
"https://tpp1.cdr.cloudentity-se.com:9001/consent/callback",
"https://tpp1.cdr.cloudentity-se.com:9001/consent/callback2"
],
"logo_uri": "https://mocksoftware/mybudgetapp/img/logo.png",
"tos_uri": "https://mocksoftware/mybudgetapp/terms",
"policy_uri": "https://mocksoftware/mybudgetapp/policy",
"jwks_uri": "https://tpp1.cdr.cloudentity-se.com:9001/jwks",
"revocation_uri": "https://tpp1.cdr.cloudentity-se.com:9001/revocation",
"software_id": "c6327f87-687a-4369-99a4-eaacd3bb8210",
"software_roles": "data-recipient-software-product",
"scope": "openid profile bank:accounts.basic:read bank:accounts.detail:read bank:transactions:read bank:payees:read bank:regular_payments:read common:customer.basic:read common:customer.detail:read cdr:registration introspect_tokens revoke_tokens"
}
The CDR Register has chosen to use PS256 as the signing algorithm, conforming to FAPI-RW Section 8.6 for signing the Software Statement Assertion(SSA). Cloudentity will verify the signature of this PS256 signed Software Statement Assertion(SSA) presented by the ADR in DCR request body.
Data Holder Registration Endpoints
As you might already be aware, Data Holders must also be registered with ACCC CDR Register. Once a Data Holder is certified, the Data Holder brand information is available in the CDR Register and ADR must utilize the APIs to extract relevant information. ADR must use getDataHolderBrands API on the CDR-Register to get the DCR APIs of the Data Holder.
GET /cdr-register/v1/{industry}/data-holders/brands
Sample Response:
{
"data": [
{
"dataHolderBrandId": "string",
"brandName": "string",
"industries": [
"banking"
],
"logoUri": "string",
"legalEntity": {
"legalEntityId": "string",
"legalEntityName": "string",
"logoUri": "string",
"registrationNumber": "string",
"registrationDate": "2019-08-24",
"registeredCountry": "string",
"abn": "string",
"acn": "string",
"arbn": "string",
"anzsicDivision": "string",
"organisationType": "SOLE_TRADER",
"status": "ACTIVE"
},
"status": "ACTIVE",
"endpointDetail": {
"version": "string",
"publicBaseUri": "string",
"resourceBaseUri": "string",
"infosecBaseUri": "string",
"extensionBaseUri": "string",
"websiteUri": "string"
},
"authDetails": [
{
"registerUType": "SIGNED-JWT",
"jwksEndpoint": "string"
}
],
"lastUpdated": "2019-08-24T14:15:22Z"
}
],
"links": {
"first": "string",
"last": "string",
"next": "string",
"prev": "string",
"self": "string"
},
"meta": {
"totalPages": 0,
"totalRecords": 0
}
}
ADR must assemble the DCR endpoint using details available in endpointDetail of the JSON structure.
DCR configuration in Cloudentity
DCR is enabled by default in Cloudentity when a CDR compliant workspace is created.
-
In the workspace, go to OAuth » Authorization Server » Client Registration from the sidebar.
-
In the DCR tab, you will see Enable dynamic client registration enabled
-
In the DCR tab, you will see Protected by software statement enabled as well
-
In the DCR tab, you will see Signed request body enabled as well with Source as Client software statement
There are multiple ways to protect the DCR endpoint. If you don’t setup any method, the registration endpoint is anonymously available.
For CDR even though the DCR API itself does not require any specific Bearer or authentication
headers, the DCR endpoint is proteced with Protected by software statement.
With Protected by software statement enabled, the registration endpoint requires the
software_statement attribute in the body. The software statement assertion is a signed JWT
containing information about ADR issued by CDR Register to ADR. You need to configure public
keys (via JSON Web Key Set or URI), which are to be used for verifying this provided software
statement.The JSON Web Key Set or URI should be that of the CDR Register.
CDR also requires the registration request has a signed request body payload and it needs to be verified during the DCR process. Once the SSA signature is verified, Cloudentity will retrieve the JWKS from data recipient JWKS uri obtained from the software statement assertion. The JWKS retrieved from ADR JWKS endpoint is used to do JWT signature validation of the request payload.
Register ADR with Data Holder
To register with a Data Holder, the Data Recipient(ADR) sends an HTTP POST to the Data Holder registration endpoint. Cloudentity platform provides the DCR endpoint. As per the CDR DCR API specification, the registration request JWT must be passed as body param in the request.
While creating the registration request body, the Data Recipient must:
-
provide the request in the format of a RFC7519 compliant JWT.
-
The request MUST use the HTTP POST method, using the application/jwt content type.
-
The JWT MUST be signed using one of the algorithms specified in FAPI-RW Section 8.6. Data recipients have the choice to choose the signing algorithm they use when interacting with data holders. Cloudentity supports the following signing algorithms:
-
PS256
-
ES256
-
-
Cloudentity performs some of the key validations as per CDR specifications for the OAuth Client being registered, so ADR must ensure the created request abides by these validations otherwise they are rejected :
-
the ONLY token endpoint auth method allowed must be
private_key_jwt -
id_token must be encrypted
-
id_token must be signed as constrained by FAPI-RW Section 8.6
-
SSA assertion issued by the CDR register must be present and signature will be validated using the JWKS published by CDR register
-
More detailed client validations can be found in CDR specifications for DCR. A detailed sequence of activities that happens within Cloudentity during the DCR flow is shown below.
Infosec Provider (Cloudentity) participant cdrregister as CDR Register adr->>cdrregister: Configure software product with CDR register adr->>cdrregister: Download software statement cdrregister-->>adr: software statement adr->>dh: GET /.well-known/openid-configuration dh-->>adr: OIDC configuration adr->>adr: Create DCR signed JWT request
with SSA, claims etc in payload adr->>dh: Dynamic client registration request
POST /register alt CDR Register JWKS cache expired dh->>cdrregister: Retrieve CDR register JWKS cdrregister-->>dh: cdr Register jwks end dh->>dh: look up SSA key in cdr Register jwks dh->>dh: Verify SSA JWT signatures
against an associated JWK retrieved above dh->>adr: Retrieive DR JWK
from the jwks_uri extracted from the SSA adr-->>dh: Data recipient JWKS dh->>dh: Verify the registration request JWT signature
against the JWK published by the Data Recipient retrieved above dh->>dh: Validate multiple active registrations
for same software_id does not exist dh->>dh: Validate registration scope claims in request dh->>dh: Register Data Recipient as an OAuth Client dh-->>adr: Return client id and details adr-->adr: Store client id and details for Data holder
Manage registered ADR
As the Infosec provider component of a Data Holder, Cloudentity platform exposes all the Data Recipient Client Registration Management endpoints as defined in the DCR APIs.
OIDC configuration endpoints can be located easily within the Cloudentity
administrative portal.
As a short hand, for a tenant with name cdr-demo that has an authorization server workspace
with name cdr, it can be located at https://cdr-demo.us.authz.cloudentity.io/cdr-demo/cdr/.well-known/openid-configuration
Within the OIDC Discovery configuration endpoint, DCR endpoint location is specified
under registration_endpoint key
"registration_endpoint":"https://cdr-demo.us.authz.cloudentity.io/cdr-demo/cdr/oauth2/register"
Cloudentity provides all the CDR compliant DCR APIs as in the specification for Data recipient dynamic client registration within the Data Holder ecosystem.