Skip to main content

Dynamic Client Registration and Management for FDX

In this article, we delve into how SecureAuth empowers its clients in the Financial Data Exchange (FDX) ecosystem to leverage a specialized approach to Dynamic Client Registration (DCR). SecureAuth introduces a unique solution tailored specifically for FDX specification, addressing the distinctive requirements associated with FDX DCR.

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 SecureAuth FDX workspaces. If you don't have one, please follow FDX API Security Profile - Workspace article.

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, SecureAuth 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 SecureAuth 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 SecureAuth that is able to obtain tokens using Client Credentials flow with a client_register scope. The client_register scope 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.

  1. To obtain access token with client_register scope 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:

    {
     "access_token":"[token_here]",
     "expires_in":3599,
     "scope":"client_register",
     "token_type":"bearer"
    }

  2. 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:

{
   "client_name":"My Example Client123",
   "description":"Recipient Application servicing financial use case requiring permissioned data sharing",
   "client_uri":"https://example.net/",
   "logo_uri":"https://client.example.org/logo.png",
   "policy_uri":"",
   "tos_uri":"",
   "organisation_id":"",
   "client_id":"f06e13a45ed742098eeb40aaa6483053",
   "application_type":"web",
   "application_types":[
      "server_web",
      "service",
      "dcr"
   ],
   "redirect_uris":[
      "https://partner.example/callback"
   ],
   "grant_types":[
      "authorization_code",
      "client_credentials"
   ],
   "response_types":[
      "code"
   ],
   "scope":"ACCOUNT_DETAILED INVESTMENTS TRANSACTIONS",
   "scopes":[
      "ACCOUNT_DETAILED",
      "INVESTMENTS",
      "TRANSACTIONS"
   ],
   "audience":[
      "f06e13a45ed742098eeb40aaa6483053"
   ],
   "token_endpoint_auth_method":"tls_client_auth",
   "revocation_endpoint_auth_method":"tls_client_auth",
   "introspection_endpoint_auth_method":"tls_client_auth",
   "token_exchange":{
      "actor_claims":null
   },
   "token_endpoint_auth_signing_alg":"",
   "jwks":{
      "keys":[]
   },
   "jwks_uri":"",
   "request_object_signing_alg":"any",
   "request_object_encryption_alg":"",
   "request_object_encryption_enc":"",
   "request_uris":[],
   "client_id_issued_at":1687958480,
   "created_at":"2023-06-28T13:21:20.111504215Z",
   "updated_at":"2023-06-28T13:21:20.111504215Z",
   "client_secret_expires_at":0,
   "sector_identifier_uri":"",
   "userinfo_signed_response_alg":"none",
   "id_token_signed_response_alg":"ES256",
   "id_token_encrypted_response_alg":"",
   "id_token_encrypted_response_enc":"",
   "tls_client_certificate_bound_access_tokens":false,
   "tls_client_auth_subject_dn":"CN=cid1.authorization.cloudentity.com,OU=Authorization,O=Cloudentity,L=Seattle,ST=Washington,C=US",
   "tls_client_auth_san_dns":"",
   "tls_client_auth_san_uri":"",
   "tls_client_auth_san_ip":"",
   "tls_client_auth_san_email":"",
   "privacy":{
      "scopes":null
   },
   "subject_type":"pairwise",
   "backchannel_token_delivery_mode":"",
   "backchannel_client_notification_endpoint":"",
   "backchannel_authentication_request_signing_alg":"",
   "backchannel_user_code_parameter":false,
   "require_pushed_authorization_requests":false,
   "authorization_signed_response_alg":"ES256",
   "authorization_encrypted_response_alg":"",
   "authorization_encrypted_response_enc":"",
   "dpop_bound_access_tokens":false,
   "client_status":"active",
   "developer_id":null,
   "system":false,
   "trusted":false,
   "use_custom_token_ttls":false,
   "token_ttls":{
      "access_token_ttl":"10m0s",
      "refresh_token_ttl":"4h0m0s",
      "authorization_code_ttl":"5m0s",
      "id_token_ttl":"10m0s"
   },
   "contacts":[
      "support@example.net"
   ],
   "duration_type":[
      "ONE_TIME"
   ],
   "duration_period":365,
   "lookback_period":365,
   "registry_references":[
      {
         "registered_entity_name":"Official recipient name",
         "registered_entity_id":"4HCHXIURY78NNH6JH",
         "registry":"GLEIF"
      }
   ],
   "intermediaries":[
      {
         "name":"Digital Service Provider Name",
         "description":"Digital Service Provider to the Recipient",
         "uri":"https://sub-partner-one.example/",
         "logo_uri":"https://sub-partner-one.example/logo.png",
         "contacts":[
            "support@sub-partner-one.com"
         ],
         "registry_references":[
            {
               "registered_entity_name":"Service Provider listed company Name",
               "registered_entity_id":"9LUQNDG778LI9D1",
               "registry":"GLEIF"
            }
         ]
      }
   ],
   "status":"Pending",
   "client_secret":"Ok0WEG0MejoHH1FrvpiQan5pemkg82dFyqLOt8hlNMg",
   "hashed_secret":"ec30bfe5613825eed97b48aa89098d768bdacf5da1bca4fbf5e3635b7e0d8c8fa1b794cebe8867607dd179b03c684b6916cd81c9c714ed5ad3608094ba75bcb06b8ecb4089841032542391ce60c1cbb857860c08bd0cf0a0b83f149ec878f1d755ca2296b489d00e1cd463a0d96268d75dd0ff46c899f6e4aa6f7352884fd73c",
   "registration_client_uri":"https://authorization.cloudentity.com:8443/default/fdx/dcr/register/f06e13a45ed742098eeb40aaa6483053"
}

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 SecureAuth 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 SecureAuth. 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 data API

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

SecureAuth 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 SecureAuth for FDX DCR ensures simplicity and convenience.

In this section: