Getting started
Last updated
Last updated
Before getting started it is highly recommended to familiarise yourself with essentials of the
You need to apply for an iSHARE Test certificate in order to use our test environment. This is described in the . Additional information is also available .
A good first step is to familiarise with JWT, JWS, and how to create/sign these tokens. Find various libraries and additional information for JSON Web Tokens on .
Various requests or responses that follow the iSHARE specifications contain signed JSON Web Tokens. Start by creating a self-signed identity claim, a client_assertion, following the specifications found on the :
Construct the correct JWT header.
Construct the required JWT payload.
Sign token according to JWS specifications.
Tip
Take into account that iSHARE compliant JWT is going be used almost everywhere. Make sure that the code you write could be easily extended according to specific JWT payload requirements.
The first workflow you should implement is an OAuth access token request. The wider use case of it is described on .
Choose a test party from the and create a client_assertion with the correct audience.
Head over to to see the contract of /token endpoint HTTP request.
Implement a token request according to contract.
If done correctly, the test party should respond with an access token.
Get an access token which you’ve implemented based on the previous section.
Provide the access token as specified in the documentation as an authorization header.
If done correctly, the test party should respond with the service that is requested.
Familiarize yourself with PKI, certificates and how the process of certificate validation works. iSHARE has a certificate cheat sheet.
In order to be a party of iSHARE your system must expose an API service that allows parties to request OAuth access tokens from your server. iSHARE does not prescribe your exact implementation or access token format, but your system should be able to handle requests send as described in the /token request from the iSHARE specifications.
Validate the certificate used for this request. It is in a JWT header of client_assertion.
If the party is Active, respond to their request with an access token, else with Bad Request.
Two parties between which a certain right is passed.
Resource fields that are used to specify the resource or service for which delegation evidence is requested.
Action field to indicate the kind of action regarding the resource is expected.
Define which party is asking for an access to a resource or service.
Indicate the second party that is needed for the mask. Your system’s knowledge of ownership of this resource of service should be able to fill this information.
Define the resource or service itself (as long as it is clear through the Service Request).
Indicate what kind of action is expected.
Once the delegation mask (a.k.a. the question) is created, a request towards /delegation endpoint of Authorisation Registry or Entitled party should be sent.
A video demonstrating how access tokens are requested in iSHARE can be found at . In order to try it out with existing parties, please visit .
Choose a test party from the that exposes a service, with access control based on the access token. E.g. is not restricted to additional authorization requirements.
Before exposing any of iSHARE services, firstly you should have a proper implementation of . It is needed in order to retrieve an access token from the iSHARE Satellite or other iSHARE parties.
Implement a function that retrieves the trusted list of Certificate Authorities from the iSHARE Satellite .
Implement a service that can validate certificates within the scope of iSHARE (see . Implemented service should check validity of certificate itself (such as expiry date, signature, CRL) and whether the certificate issuer is on the trusted list of iSHARE.
iSHARE has example projects and code snippets on GitHub, it also contains certificate validion, .
For incoming token requests, make sure that they comply with the specified iSHARE .
Send the client’s iSHARE ID or EORI (found as iss within the request’s client_assertion) to the iSHARE Satellite for status check. Response for party status should be equal to Active.
Sequence diagram of this flow can be found at .
To allow other parties to know what your party is capable of, capabilities endpoint must be implemented. Participants of iSHARE will use this endpoint to see what iSHARE enabled services your organization provides. Implementation is pretty straightforward and API endpoint specification can be found at .
Services that require additional evidence for authorized access can make use of the . This section should be interesting mostly for Authorisation Registries, Service Providers and Entitled Parties.
Firstly you will have to familiarize yourself with iSHARE and data models.
Refer to the of the Authorisation Registry or Entitled Party. The request body contains a , which is in other words could be called the actual question that is asked, the question contains:
You can find a video with an explanation how delegation mask is used within Authorisation Registry in .
In order to create (a.k.a. the question), you need to translate an incoming Service Request. Through the Service Request, you should be able to:
Delegation evidence will be which contains JWT payload described at . Based on JWT information, an authorization decision should be made and enforced to the client.
After implementing of what is described above you will have to implement endpoints which are required specifically for your organization. Endpoints could be found in the right menu, under your organisation’s specific role. Once that is done, you will have to pass .