FDX Dynamic Client Registration Overview
Note
To configure DCR for FDX, you need to have a workspace with FDX profile enabled. Dynamic Client Registration is enabled by default in Cloudentity FDX workspaces. If you don’t have one, please follow FDX API Security Profile - Workspace artcile.
The FDX specification takes a unique approach to client registration, setting it apart from the
standard OAuth 2.0 Dynamic Client Registration (DCR) process. Unlike the traditional DCR, FDX does
not rely on a central registry or Software Statement Assertion (SSA). Instead, it introduces its own
method to safeguard the registration API from unauthorized usage. FDX DCR is specifically designed
for intermediaries, acting as integration platforms that offer external APIs to simplify the
connection between developers' applications and financial institutions. This approach effectively
conceals the intricacies of the FDX specification. In a typical scenario, a user requests client
registration through the intermediary’s external API. The intermediary then proceeds to register the
client using the FDX API.
In addition to its other features, the FDX specification includes a Dynamic Client Registration
(DCR) process that incorporates offline approval. This means that when a client is newly
registered, it is initially in an Pending state and requires activation by a third party, such as
a bank worker. The specific method for activating DCR clients is not covered in the official FDX
specification. However, Cloudentity offers a convenient solution for transitioning the states of DCR
clients, simplifying the process of client activation.
In the next chapter, we delve into how intermediaries can utilize Cloudentity to simplify and hide the complexity involved in dynamic client registration for FDX. This solution offers an easy and efficient way for intermediaries to manage the registration process seamlessly.
Client Registration
Note
As a prerequisite for FDX Dynamic Client Registration (DCR) process, an intermediary requires a client registered in Cloudentity that is able to obtain tokens using Client Credentials flow with a
client_registerscope. Theclient_registerscope defined by FDX specification, grants the intermediary client the authority to perform client registration operations on behalf of third-party applications. With this scope, the intermediary can securely register and manage clients within the FDX ecosystem, ensuring compliance, security, and adherence to the FDX DCR guidelines.
-
To obtain access token with
client_registerscope send request to OAuth /token endpoint, for example:Note
All FDX apis are protected by mTLS. Please remember to provide proper certificates to your requests.
curl -X POST --cert cert.pem --key cert-key.pem https://authorization.cloudentity.com:8443/default/fdx/oauth2/token \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-raw "grant_type=client_credentials&client_id=intermediary_client&scope=client_register"Sample Response:
-
To register a client, use access token from the previous step and send a request to the Dynamic Client Registration endpoint, for example:
curl -X POST --cert cert.pem --key cert-key.pem https://authorization.cloudentity.com:8443/default/fdx-demo-muy-lahc7f/fdx/dcr/register \ -H "authorization:bearer $AT" \ -H "Content-Type: application/json" \ --data-raw '{"client_name":"My Example Client123","client_uri":"https://example.net/","contacts":["support@example.net"],"created_at":"0001-01-01T00:00:00Z","description":"Recipient Application servicing financial use case requiring permissioned data sharing","durationPeriod":365,"duration_type":["ONE_TIME"],"grant_types":["authorization_code","client_credentials"],"intermediaries":[{"contacts":["support@sub-partner-one.com"],"description":"Digital Service Provider to the Recipient","logo_uri":"https://sub-partner-one.example/logo.png","name":"Digital Service Provider Name","registry_references":[{"registered_entity_id":"9LUQNDG778LI9D1","registered_entity_name":"Service Provider listed company Name","registry":"GLEIF"}],"uri":"https://sub-partner-one.example/"}],"logo_uri":"https://client.example.org/logo.png","lookback_period":365,"redirect_uris":["https://partner.example/callback"],"registry_references":[{"registered_entity_id":"4HCHXIURY78NNH6JH","registered_entity_name":"Official recipient name","registry":"GLEIF"}],"scope":"ACCOUNT_DETAILED INVESTMENTS TRANSACTIONS","tls_client_auth_subject_dn":"CN=cid1.authorization.cloudentity.com,OU=Authorization,O=Cloudentity,L=Seattle,ST=Washington,C=US","token_endpoint_auth_method":"tls_client_auth"}Note
Please note that register endpoint URI is specific to FDX.
Sample response:
The response contains two significant pieces of information. Firstly, the client’s status is indicated as Pending, indicating that the newly created client is not yet active. You can establish the initial state of the client through the Cloudentity portal, where you can choose from a range of options such as Approved, Tentative, Pending, Rejected, or Inactive.
Secondly, the response includes the registration_client_uri, which provides you with the capability to manage the registered client.
Client Management
To manage client you need to obtain an access token for this client as a prerequisite. With obtained token you can utilize APIs to manage registration:
Get Registration Data
curl --cert cert.pem --key cert-key.pem https://authorization.cloudentity.com:8443/default/fdx/fdx/dcr/register/$CID \
-H "authorization:bearer $AT"
The response data is identical as for registration API
Update Registration Data
In order to modify a client, you are required to provide the complete client data along with the specific modification you wish to apply, which in this scenario is the client_name.
curl --cert cert.pem --key cert-key.pem https://authorization.cloudentity.com:8443/default/fdx/fdx/dcr/register/$CID \
-H "authorization:bearer $AT" \
-H "Content-Type: application/json" \
--data-raw '{"client_name":"My Modified Client","client_uri":"https://example.net/","contacts":["support@example.net"],"created_at":"0001-01-01T00:00:00Z","description":"Recipient Application servicing financial use case requiring permissioned data sharing","durationPeriod":365,"duration_type":["ONE_TIME"],"grant_types":["authorization_code","client_credentials"],"intermediaries":[{"contacts":["support@sub-partner-one.com"],"description":"Digital Service Provider to the Recipient","logo_uri":"https://sub-partner-one.example/logo.png","name":"Digital Service Provider Name","registry_references":[{"registered_entity_id":"9LUQNDG778LI9D1","registered_entity_name":"Service Provider listed company Name","registry":"GLEIF"}],"uri":"https://sub-partner-one.example/"}],"logo_uri":"https://client.example.org/logo.png","lookback_period":365,"redirect_uris":["https://partner.example/callback"],"registry_references":[{"registered_entity_id":"4HCHXIURY78NNH6JH","registered_entity_name":"Official recipient name","registry":"GLEIF"}],"scope":"ACCOUNT_DETAILED INVESTMENTS TRANSACTIONS","tls_client_auth_subject_dn":"CN=cid1.authorization.cloudentity.com,OU=Authorization,O=Cloudentity,L=Seattle,ST=Washington,C=US","token_endpoint_auth_method":"tls_client_auth"}
The response data is identical as for registration API
Delete Registration
curl -X DELETE --cert cert.pem --key cert-key.pem https://authorization.cloudentity.com:8443/default/fdx/fdx/dcr/register/$CID \
-H "authorization:bearer $AT"
Offline Registration Approval
As a third party entity seeking to approve client registration or change the client’s state, it is necessary to have a client registered in Cloudentity. This client should be able to request an access token with the specific scope of update_client_status. With this scope, the client’s status can be modified using the following API:
Note
Client status can not be changed using
Update registration dataAPI
curl -X PUT --cert cert.pem --key cert-key.pem https://authorization.cloudentity.com:8443/default/fdx/fdx/dcr/register/$CID \
-H "authorization:bearer $AT"
--data-raw "new_status=Approved"
Summary
Cloudentity offers a comprehensive implementation of the FDX DCR process, encompassing client registration and efficient management through user-friendly APIs. Additionally, it facilitates offline DCR approval by providing third-party APIs for modifying client status and approving registrations. Choosing Cloudentity for FDX DCR ensures simplicity and convenience.