Getting Started
This page describes the steps you have to undertake to consume services provided by iSHARE compliant Service Providers (this page assumes general knowledge of the iSHARE framework and roles).
Prerequisites
Make sure you execute the following steps before trying to consume services provided by iSHARE Providers.
- Obtain a valid identity (private key + certificate)
Staging: Click here to request a test certificate. More information on Get Test Certificate section.
Production: Acquire a certificate from an eIDAS certificate provider.
- Register yourself as iSHARE Consumer
Staging: If you want to register at a specific iSHARE Satellite, contact the iSHARE Satellite through their communication channels. A registration via the Scheme Owner is also possible: contact us at support@ishare.eu.
Production: Register yourself with any iSHARE Satellite using their registration procedure.
Implementation
Every iSHARE Service Provider has implemented 2 standardised endpoints: * Access Token (M2M) * Capabilities
As an iSHARE Service Consumer, a minimum implementation requires connecting to the Access Token endpoint. For more information about requesting an Access Token, refer to the section about the Access Token Endpoint. The request includes an iSHARE JWT, which is documented here. After obtaining an Access Token, this token can be used to consume services from the Service Provider. These services themselves are not standardised by iSHARE.
For your implementation, choose one of the following scenarios. A combination of scenarios is possible. All scenarios assume that a protected service will be consumed.
Scenario 1: Minimum implementation
The endpoint and specifications of the service that will be consumed are already available. Delegation evidence is acquired by the Service Provider.
Connection with the Service Provider
Use Access Token to consume service
Scenario 2: Using the /capabilities endpoint to discover services
The endpoints of the service that will be consumed are obtained through the /capabilities endpoint. Further specifications are assumed already available. Delegation evidence is acquired by the Service Provider.
Connection with the Service Provider
Consume /capabilities endpoint to discover where to get an Access Token
Use Access Token to consume /capabilities endpoint to discover where to consume services
Use result of /capabilities endpoint + Access Token to consume services
Scenario 3: Perform prechecks on the Service Provider
If the Service Consumer provides data to a Service Provider (i.e. data that belongs to an Entitled Party), for full legal coverage it is advised to check adherence of the Service Provider, before a service is consumed. The implementation would then be as follows.
Connection with iSHARE Satellite
Use Access Token to request the /trusted_list endpoint
Validate adherence of the Service Provider by invoking the /parties endpoint, searching for the EORI of the Service Provider that should be used at the Satellite. Check if the party can be found, if the certificate is valid (check with trusted list) and if the party has the role of Service Provider.
Connection with the Service Provider
Use Access Token to consume service
Scenario 4: Full implementation, with prechecks and delegation evidence
If the Service Consumer wishes to provide delegation evidence to the Service Provider, the minimum implementation is as follows.
Connection with iSHARE Satellite
Use Access Token to request the /trusted_list endpoint
Validate adherence of the Authorization Registry by invoking the /parties endpoint, searching for the EORI of the Authorization Registry that should be used at the Satellite. Check if the party can be found, if the certificate is valid (check with trusted list) and if the party has the role of Authorization Registry.
Validate adherence of the Service Provider by invoking the /parties endpoint, searching for the EORI of the Service Provider that should be used at the Satellite. Check if the party can be found, if the certificate is valid (check with trusted list) and if the party has the role of Service Provider.
Connection with the Authorization Registry
Use the Access Token to invoke the Delegation endpoint, to obtain Delegation Evidence
Connection with the Service Provider
Use Access Token and Delegation Evidence to consume service
