Receive Data
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.
- Your organisation is onboarded within the ecosystem/federation and active.
- Your organisation has an Authorisation Domain and a Role assigned by the Trust Framework Participants.
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.
Navigate to your organisation.
Select Applications > New Application to open up the Connect's Wizard.
A software statement is a JSON Web Token (JWT RFC7519) containing metadata about the client software -- your application. It is included in the client registration request to the Data Provider's Authorisation Server and must be signed using JSON Web Signature (JWS).
For more information on how to set up applications, see the Add and Manage Applications article.
Select Next and fill in the details of your application.
Field name | Required | Field description | Example |
Client Name | Yes | It is recommended to use the brand name that the customers are familiar with. This is the name of your software application a user sees while providing their consent to share data. | Raidiam |
Client URI | Yes | Website or root URI from the resource. | https://raidiam.com/info.html |
Policy URI | Yes | Must be a defined text sequence that represents a single unique policy URI. | https://raidiam.com/policy.html |
Logo URI | Yes | Brand logo URI | https://raidiam.com/logo.svg |
Terms of service URI | No | Must be a text string that represents the unique URI for ToS | https://raidiam.com/tos.html |
Application and Technical Redirects | Yes | Must be a text string that represents an unique URI for application and redirects. This is the URI where the user is redirected back after they provide their consent. You can provide one or more URIs that will be registered at the authorisation server. | https://raidiam.com/cb1 https://raidiam.com/cb2 |
Description | No | A text description of your application. | Raidiam your service solution |
Version | Yes | Version of your application. Must be defined by a numeric value, an integer, or a floating point number. | 1.2 |
Select Save and Next.
At this point, your application is created and you can either proceed further with the wizard (recommended) or finalize working on the next steps later on -- note, however, you are not able to get back to the wizard itself to configure the same application again.
The amount of roles and what roles are available depend on the roles assigned to your organisation by the Trust Framework Administrator.
If you see no roles available within the Wizard, you can skip this step and later on assign it manually.
It is considered a good practice not to assign all available roles to client applications, but only the ones the client application needs. For example, if you are going to call the Connect's APIs in the future, create a separate client application for that need and assign the appropriate role to that end.
In this step, you will create a private and public key pair and a Certificate Signing Request (CSR) to request a transport Certificate. This certificate can be used in mutual TLS (mTLS) communication between the Data Providers and Data Receivers technical resources.
Such certificates -- both the participants can trust -- empower your technical assets, such as your client application, to establish a secure connection with the Data Provider's authorization server and resource server, enabling them to engage in TLS handshakes and enable secure connection during the data exchange.
Select TRANSPORT certificate type and continue.
Execute the provided CSR generation command in your terminal
The CSR is generated and saved within the same directory you execute the command.
Upload the generated CSR file.
Once your application is set up, you need to integrate it with a Data Provider and their Authorisation Server 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).
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.
To get a list of authorisation servers registered within the framework, you can utilize the following APIs:
- Get All Authorisation Servers for Given Organisation - lists all authorisation servers registered within an organisation along with their configuration.
- Get Authorisation Server by Identifier - returns a selected authorisation server along with its configuration.
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.
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.
Retrieve authorisation servers using one of the APIs listed above.
Include the access token you got in the step #1 to authenticate your client application's request.
The platform returns a list of authorisation servers and their configuration.
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 Data Provider's Authorisation Server if DCR is used as the framework.
If OpenID Federation or Raidiam's FedLite 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.
While getting a list of authorisation servers during the process described in the Find Data Providers and Authorisation Servers section, you receive configuration of an authorisation server registered within the Trust Framework. Such configuration contains useful information you can use in the future.
Most importantly, the configuration of a server in Raidiam Connect includes the OpenIDDiscoveryDocument URI you can use to pull a detailed configuration of the authorisation server itself including the Dynamic Client Registration endpoint.
For an example of the OpenID Dicovery Document, reference the Raidiam's Authorisation Server /.well-known endpoint. It contains the "registration_endpoint": "https://auth.sandbox.raidiam.io/reg" DCR endpoint where dynamic client registration requests could be posted.
Utilize the OpenID Discovery endpoint (/.well-known) to discover the authorisation server's configuration.
The data provider's authorisation server returns a JSON OpenID Discovery document containing its configuration.
Extract the desired metadata, particularly the Dynamic Client Registration URI.
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.
Raidiam Connect's Authorisation Server validates the certificate as part of the tls_client_auth client authentication process.
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.
Retrieve Software Statement Assertion (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.
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:
The Data Provider's authorisation server requests the key set from the Raidiam Connect's JWKS URI.
Raidiam Connect returns the key set.
The returned key set is used to validate the Software Statement Assertion provided by your client.
The DCR request is validated by the Data Provider's authorisation server.
The authorisation server returns the configuration of your dynamically registered client.
Discover Data Provider's APIs in order to integrate with them. API discovery process can differ between Open Data Ecosystems where the Participants API returns a list of organisations and all their technical resoruces, and other ecosystems or federations where the data about an organisation can be accessed only through Connect's Data APIs.
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 technical resources, including the published APIs.
Within the JSON payload above, you can see the ApiResources object which is a list of all the APIs and their endpoints you can integrate with.
In order to get information about the published APIs for an organisation, utilize the below Connect APIs. Since all APIs published within Connect are tied to an authorisation server, you need to first check all authorisation servers added for an organisation and then check the published APIs.
- Get All Authorisation Servers for Given Organisation - lists all authorisation servers registered within an organisation along with their configuration.
- Get Authorisation Server by Identifier - returns a selected authorisation server along with its configuration.
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.
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.
Retrieve authorisation servers using one of the APIs listed above.
Include the access token you got in the step #1 to authenticate your client application's request.
Retrieve a list of all API resources published for an authorisation server once you have its authorisation server identifier.
Utilize OAuth and any OAuth library you want to integrate with the Data Provider's APIs.
Depending on your needs and the Data Provider's Authorisation Server 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). To check where to get the endpoint's URL, go back to the Find Data Providers and Authorisation Servers section. Allowed grant types may include but are not limited to:
- 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-machine scenarios.
- And more...
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, go back to the Request Transport Certificate section.
Using your transport certificate naturally implies the authorisation server will use theirs as well to establish a secure connection. Learn how to validate certificates for production scenarios.
To access non-public APIs published by any Data Provider, you need to authenticate your client application at the Data Provider's Authorisation Server.
Depending on the server's and your client application configuration, it happens using:
- private_key_jwt client authentication (described in RFC7521 Assertion Framework specification and RFC7523 JWT Profile for Client Authentication specification)
Using the authorisation servers OIDC Discovery endpoint (/.well-known) get the /token endpoint URL. Once you have this, request security tokens you need (access tokens, refresh tokens, or ID tokens).