Building and Integrating CDR Consent Administrator Portal
Learn how to configure and integrate CDR-compliant consent administrator portals with built-in consent APIs provided by SecureAuth.
Sandbox
SecureAuth 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 SecureAuth 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
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.
Consent administrator portal applications must be created within the System workspace of your SecureAuth 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 SecureAuth Sales Team.
Consent administrator portal applications must have the
manage_openbanking_consentsscope assigned.Add New Scope
When you have no
manage_openbanking_consentsscope available for assigning to your application, add it to the required CDR service first. Then, you can assign it to your client app.The same scope is recommended to be explicitly defined when calling the
/tokenendpoint . Pass it as the value of thescopeparameter to make the flow compliant with the best security practices.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 SecureAuth 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 SecureAuth, use the following APIs:
- Authentication (step 7)
Authenticate your consent admin portal to SecureAuth. : The consent admin portal calls the
/tokenendpoint for the only purpose of authenticating itself before calling SecureAuth consent APIs.Authentication can be performed before steps 9, 13, 15, and 19 as well.
- Fetching arrangements (steps 9 and 13)
POSTList CDR Customer ArrangementsThis 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
GETList Clients by Authorization ServerFetch 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
GETGet CDR Arrangement by IDObtain 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
DELETERevoke CDR Arrangement by IDRevoke an arrangement.
Pass the identifier of the required arrangement as the path parameter.
- Bulk revocation
DELETERevoke CDR ArrangementsRevoke 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 SecureAuth APIs require the access token to be obtained in such a way:
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.
SecureAuth Tenant
Set up your System workspace and configure token claims:
Add the
customer_idattribute under AuthN Context.Add the
customer_idattribute to the identity provider you use for authentication.Map it with the AuthN Context attribute.
Add the
customer_idclaim to access tokens issued for the workspace.Source type: AuthN context
Source path: the
customer_idattribute from the AuthN Context.Adding Claims with Data Lineage
You can use SecureAuth 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
/tokenendpoint to obtain an access token.
Add server-side web 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
Create a JSON Web Token (JWT). Add the
customer_idparameter along with the required value to the token's payload.All mandatory claims must be included in JWT as well.
Sign the JWT with the private key you created with the key generator tool.
Obtain Access Token
Call the SecureAuth OAuth 2.0 token API to get an access token for your client application.
In your request to the /token endpoint:
Set the
grant_typeparameter tourn:ietf:params:oauth:grant-type:jwt-bearerAs the value for the
assertionparameter provide your signed JWT.Use the client authentication method that you set for the Consent Admin Portal's client application.
Define the
manage_openbanking_consentsscope.
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.