Skip to main content

Getting Started as Data Receiver

Securely get customer-permissioned data. Add applications. See all available Data Providers. Authenticate with their authorisation servers. Discover published APIs for you to integrate with in a standardized way.

Prerequisites​

Onboard Application​

To enable your software application to become a part of the Trust Framework and request resources from Data Providers, you need to register it within the Centralized Directory first.

  1. Add Application.

  2. Add Roles that will enable you to access Raidiam's APIs.

    The amount of roles and what roles are available depend on the roles assigned to your organisation by the Trust Framework Administrator.

    Roles govern, for example, the Access Scopes your application can request.

  3. Obtain Transport Certificate for your application.

Find Data Providers and Authorisation Servers​

Once your application is set up, you need to integrate it with a Data Providers and their Authorisation Servers in order to get an access token. Such token enables your application to authenticate itself while accessing the Data Provider's Data APIs (resource server).

Getting Data Providers and Their Servers in Open Data Ecosystems​

If your framework is an Open Data Ecosystem, client application's can utilize the Participants API to receive a JSON document containing a list of all participants and their authorization servers.

Getting Data Providers and Their Servers in Other Ecosystems​

  1. Authenticate client application using client credentials flow and request the directory:software scope.

  2. Get a list of authorisation servers registered within the framework using the below APIs:

Register Client Application at Authorisation Server​

Depending on the type of the Registration Framework used within the Framework, OAuth Dynamic Client Registration (DCR), OpenID Federation, or Raidiam's Simple Registration Endpoint, you may need to register your client application at the Authorisation Server if DCR is used as the framework.

OpenID Federation and Raidiam's Simple Registration Endpoint​

If OpenID Federation or Raidiam's SRE is used, there is no need to register the client application as it simply initiates a request to the server's OAuth /authorisation or /par (pushed authorisation request) endpoint setting the client_id (client identifier) to the organisation's (entity) identifier. Within both frameworks, the responsibility for maintaining an up-to-date list of active applications lies on the Data Providers' side.

Register Application at Authorisation Server Using OAuth DCR​

DCR Diagram​

Prepare Application for DCR​

  1. Utilize the OpenID Discovery endpoint (/.well-known) to discover the authorisation server's configuration.

  2. The data provider's authorisation server returns a JSON OpenID Discovery document containing its configuration.

  3. Extract the desired metadata, particularly the Dynamic Client Registration URI.

  4. Get an Access Token.

    Use the OAuth Client Credentials flow as the grant type and tls_client_auth as client authentication method.

    Request the directory:software access token scope.

    Raidiam Connect's Authorisation Server validates the certificate as part of the tls_client_auth client authentication process.

  5. Raidiam Connect's Authorisation Server validates the certificate as part of the tls_client_auth client authentication process.

  6. If validation is successful, the server returns an access token you can use to call Raidiam's APIs and retrieve information about the authorisation servers and their configuration.

  7. Retrieve Assertion (SSA) (SSA) from Raidiam using the Get Software Statement Assertion for Given SoftwareStatementID API.

    Utilize the access token you got from Raidiam Connect's authorisation server to authenticate your request.

    The platform returns a JSON Web Token containing the Software Statement Assertion.

Software Statement Assertion (SSA) Example​

{
    "application_type": "web",
        "grant_types": [
            "client_credentials",
            "authorization_code",
            "refresh_token",
            "implicit"
        ],
            "id_token_signed_response_alg": "PS256",
                "require_auth_time": false,
                    "response_types": [
                        "code id_token",
                        "id_token"
                    ],
                        "software_statement": "eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9tb2RlIjoiTGl2ZSIsInNvZnR3YXJlX3JlZGlyZWN0X3VyaXMiOlsiaHR0cHM6XC9cL3d3dy5yYWlkaWFtLmNvbVwvYWNjb3VudGluZ1wvY2IiXSwic29mdHdhcmVfc3RhdGVtZW50X3JvbGVzIjpbeyJyb2xlIjoiREFET1MiLCJhdXRob3Jpc2F0aW9uX2RvbWFpbiI6Ik9wZW4gQmFua2luZyIsInN0YXR1cyI6IkFjdGl2ZSJ9LHsicm9sZSI6IlBBR1RPIiwiYXV0aG9yaXNhdGlvbl9kb21haW4iOiJPcGVuIEJhbmtpbmciLCJzdGF0dXMiOiJBY3RpdmUifV0sInNvZnR3YXJlX2NsaWVudF9uYW1lIjoiUmFpZGlhbSBBY2NvdW50aW5nIiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsInNvZnR3YXJlX2NsaWVudF9pZCI6IkNraTFFYnZqd3loUEIxMk5HTGx6MiIsImlzcyI6Ik9wZW4gQmFua2luZyBPcGVuIEJhbmtpbmcgQnJhc2lsIHByb2QgU1NBIGlzc3VlciIsInNvZnR3YXJlX3Rvc191cmkiOiJodHRwczpcL1wvd3d3LnJhaWRpYW0uY29tXC9hY2NvdW50aW5nXC90b3MuaHRtbCIsInNvZnR3YXJlX2NsaWVudF9kZXNjcmlwdGlvbiI6IlJhaWRpYW0gQWNjb3VudGluZyBsZXZlcmFnZSBjdXR0aW5nIGVkZ2Ugb3BlbiBiYW5raW5nIGFjY2VzcyB0byBicmluZyB5b3UgcmVhbCB0aW1lIHVwIHRvIGRhdGUgdmlld3Mgb2YgeW91ciBmaW5hbmNlcyIsInNvZnR3YXJlX2p3a3NfZW5kcG9pbnQiOiJodHRwczpcL1wva2V5c3RvcmUuZGlyZWN0b3J5Lm9wZW5iYW5raW5nYnJhc2lsLm9yZy5iclwvYjk2MWM0ZWItNTA5ZC00ZWRmLWFmZWItMzU2NDJiMzgxODVkXC8yNTU1NmQ1YS1iOWRkLTRlMjctYWExYS1jY2U3MzJmZTc0ZGVcL2FwcGxpY2F0aW9uLmp3a3MiLCJzb2Z0d2FyZV9wb2xpY3lfdXJpIjoiaHR0cHM6XC9cL3d3dy5yYWlkaWFtLmNvbVwvYWNjb3VudGluZ1wvcG9saWN5Lmh0bWwiLCJzb2Z0d2FyZV9pZCI6IjI1NTU2ZDVhLWI5ZGQtNGUyNy1hYTFhLWNjZTczMmZlNzRkZSIsInNvZnR3YXJlX2NsaWVudF91cmkiOiJodHRwczpcL1wvd3d3LnJhaWRpYW0uY29tXC9hY2NvdW50aW5nLmh0bWwiLCJzb2Z0d2FyZV9qd2tzX2luYWN0aXZlX2VuZHBvaW50IjoiaHR0cHM6XC9cL2tleXN0b3JlLmRpcmVjdG9yeS5vcGVuYmFua2luZ2JyYXNpbC5vcmcuYnJcL2I5NjFjNGViLTUwOWQtNGVkZi1hZmViLTM1NjQyYjM4MTg1ZFwvMjU1NTZkNWEtYjlkZC00ZTI3LWFhMWEtY2NlNzMyZmU3NGRlXC9pbmFjdGl2ZVwvYXBwbGljYXRpb24uandrcyIsInNvZnR3YXJlX2p3a3NfdHJhbnNwb3J0X2luYWN0aXZlX2VuZHBvaW50IjoiaHR0cHM6XC9cL2tleXN0b3JlLmRpcmVjdG9yeS5vcGVuYmFua2luZ2JyYXNpbC5vcmcuYnJcL2I5NjFjNGViLTUwOWQtNGVkZi1hZmViLTM1NjQyYjM4MTg1ZFwvMjU1NTZkNWEtYjlkZC00ZTI3LWFhMWEtY2NlNzMyZmU3NGRlXC9pbmFjdGl2ZVwvdHJhbnNwb3J0Lmp3a3MiLCJzb2Z0d2FyZV9qd2tzX3RyYW5zcG9ydF9lbmRwb2ludCI6Imh0dHBzOlwvXC9rZXlzdG9yZS5kaXJlY3Rvcnkub3BlbmJhbmtpbmdicmFzaWwub3JnLmJyXC9iOTYxYzRlYi01MDlkLTRlZGYtYWZlYi0zNTY0MmIzODE4NWRcLzI1NTU2ZDVhLWI5ZGQtNGUyNy1hYTFhLWNjZTczMmZlNzRkZVwvdHJhbnNwb3J0Lmp3a3MiLCJzb2Z0d2FyZV9sb2dvX3VyaSI6Imh0dHBzOlwvXC93d3cucmFpZGlhbS5jb21cL2FjY291bnRpbmdcL2xvZ28ucG5nIiwib3JnX2lkIjoiYjk2MWM0ZWItNTA5ZC00ZWRmLWFmZWItMzU2NDJiMzgxODVkIiwic29mdHdhcmVfZW52aXJvbm1lbnQiOiJwcm9kdWN0aW9uIiwic29mdHdhcmVfdmVyc2lvbiI6MS4xMCwic29mdHdhcmVfcm9sZXMiOlsiREFET1MiLCJQQUdUTyJdLCJvcmdfbmFtZSI6Ik9wZW4gQmFua2luZyBCcmFzaWwiLCJpYXQiOjE2MTgzMzYyNjIsIm9yZ2FuaXNhdGlvbl9jb21wZXRlbnRfYXV0aG9yaXR5X2NsYWltcyI6W3siYXV0aG9yaXNhdGlvbl9kb21haW4iOiJPcGVuIEJhbmtpbmciLCJhdXRob3Jpc2F0aW9ucyI6W10sInJlZ2lzdHJhdGlvbl9pZCI6IjEzMzUzMjM2LU9CQi1DT05UQSIsImF1dGhvcml0eV9pZCI6IjY4N2ExYzk0LWIzNjAtNGUwNC05NTg5LTBmYTVjYjE2NDUxYiIsImF1dGhvcmlzYXRpb25fcm9sZSI6IkNPTlRBIiwiYXV0aG9yaXR5X2NvZGUiOiJCQ0IiLCJzdGF0dXMiOiJBY3RpdmUifSx7ImF1dGhvcmlzYXRpb25fZG9tYWluIjoiT3BlbiBCYW5raW5nIiwiYXV0aG9yaXNhdGlvbnMiOltdLCJyZWdpc3RyYXRpb25faWQiOiIxMzM1MzIzNi1PQkItREFET1MiLCJhdXRob3JpdHlfaWQiOiI2ODdhMWM5NC1iMzYwLTRlMDQtOTU4OS0wZmE1Y2IxNjQ1MWIiLCJhdXRob3Jpc2F0aW9uX3JvbGUiOiJEQURPUyIsImF1dGhvcml0eV9jb2RlIjoiQkNCIiwic3RhdHVzIjoiQWN0aXZlIn0seyJhdXRob3Jpc2F0aW9uX2RvbWFpbiI6Ik9wZW4gQmFua2luZyIsImF1dGhvcmlzYXRpb25zIjpbXSwicmVnaXN0cmF0aW9uX2lkIjoiMTMzNTMyMzYtT0JCLVBBR1RPIiwiYXV0aG9yaXR5X2lkIjoiNjg3YTFjOTQtYjM2MC00ZTA0LTk1ODktMGZhNWNiMTY0NTFiIiwiYXV0aG9yaXNhdGlvbl9yb2xlIjoiUEFHVE8iLCJhdXRob3JpdHlfY29kZSI6IkJDQiIsInN0YXR1cyI6IkFjdGl2ZSJ9XX0.W6hUAYhjT6I61rxEIVMKYKre93LTbRdzKnk9dJvUdzVgAz5B9KxZNutf27oO3k0hrjYVWBdWq23o_e4Y_AaKdpS9-rtU84JiHtmqV0wcFYIM8nqcUVWqQ-Ux6Nq9L2G-s2YNd3PcJ1e3yGg9h8553Gr7iJusKEgApzXUpkM2rBELQuumktUE_JBiuIkXmWxoRnO1cW-Osbk3MT3bxG43SPcxii07Q5S8qXI6PjCPA3fYlnaUAygwZM3O0oa7jqmSr7d9UsHuDMJfYhIKdq2wyQQKORCN-D2UopmMX-lHMvAVkkrAO08T0-7odjr4PJk-PrwuoCxeAfa7440ZDOrlmQ",
                            "subject_type": "public",
                                "token_endpoint_auth_method": "private_key_jwt",
                                    "request_object_signing_alg": "PS256",
                                        "require_signed_request_object": true,
                                            "require_pushed_authorization_requests": false,
                                                "tls_client_certificate_bound_access_tokens": true,
                                                    "client_id": "aCnBHjZBvD6ku3KVBaslL",
                                                        "client_name": "Sample Fintech App",
                                                            "client_uri": "https://www.sample-fintech-app.com/",
                                                                "request_object_encryption_alg": "RSA-OAEP",
                                                                    "request_object_encryption_enc": "A256GCM",
                                                                        "jwks_uri": "https://keystore.directory.openbankingbrasil.org.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/application.jwks",
                                                                            "redirect_uris": [
                                                                                "https://www.sample-fintech-app.com/app/"
                                                                            ],
                                                                                "webhook_uris": [
                                                                                    "https://www.sample-fintech-app.com/app/webhooks/"
                                                                                ]
}

Register Client Using DCR​

  1. Get the DCR endpoint URL from the Server's .well-known endpoint.

  2. Request dynamic client registration at the authorisation server's DCR API.

    Provide the details of your client along with the JWT SSA as a value of the software_statement request parameter. See example below:

  3. The Data Provider's authorisation server requests the key set from the Raidiam Connect's JWKS URI.

  4. Raidiam Connect returns the key set.

  5. The returned key set is used to validate the Software Statement Assertion provided by your client.

  6. The DCR request is validated by the Data Provider's authorisation server.

  7. The authorisation server returns the configuration of your dynamically registered client.

Discover and Integrate with Data Provider's APIs​

Discover the APIs published by the Data Provider where you registered your client application at their authorization server.

Utilize OAuth and any OAuth library you want to integrate with the discovered Data Provider's APIs.

Depending on your needs and the Data Provider's Authorisation Servers configuration, you need to utilize OAuth & OIDC grant types (flows) to get an access token, a proof your application is what it states it is. You can check which grant types are allowed by checking the server's OIDC Discovery endpoint (/.well-known).

  • Authorization Code Flow - for scenarios where there is a user that needs to be authenticated and provide their consent for third-party access to their resources.

  • Client Credentials Flow - for machine-to-machFine scenarios.

  • And more...

Establish Secure Connection​

While accesing any of the Data Provider's APIs, utilize a transport certificate for establishing a secure connection using mTLS. To see how to get one, see the Obtain Client Certificate article.

Using your transport certificate naturally implies the authorisation server will use theirs as well to establish a secure connection. Validate Certificates for production scenarios.

Authenticate at Data Provider's Authorisation Server​

To access non-public APIs published by any Data Provider, you need to authenticate your client application at the Data Provider's Authorisation Servers.

Depending on the server's and your client application configuration, it happens using:

Using the authorisation server's OIDC Discovery endpoint (/.well-known) get the /token endpoint URL. Once you have this, request security tokens you need (access tokens, refresh tokens, and/or ID tokens).

Next Steps​

Open Book IconTABLE OF CONTENT