Getting started
Before getting started, it is highly recommended to familiarise yourself with the essentials of the iSHARE Trust Framework.
You need to apply for an iSHARE Test Certificate to use our test environment. How this is done is described in the Test Certificate section.
Consuming iSHARE Services
Creating JSON Web Tokens
A good first step is to familiarise yourself with JWT, JWS, and how to create/sign these tokens. Find various libraries and additional information for JSON Web Tokens on jwt.io.
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 iSHARE JWT section:
Construct the correct JWT header.
Construct the required JWT payload.
Sign token according to JWS specifications.
Tip
Take into account that an iSHARE-compliant JWT is going to be used almost everywhere. Make sure that the code you write can be easily extended according to specific JWT payload requirements.
Get an OAuth 2.0 Access Token
The first workflow you should implement is an OAuth access token request. The wider use case of it is described in the M2M Authentication section.
Choose a test party from the iSHARE Test Participants and create a client_assertion with the correct audience.
Head over to the Access Token Endpoint section to see the contract of /token endpoint HTTP request.
Implement a token request according to the contract.
If done correctly, the test party should respond with an access token.
Request Services With Access Tokens
Choose a test party from the iSHARE Test Participants that exposes a service, with access control based on the access token. E.g. /capabilities is not restricted to additional authorisation requirements.
Get an access token which you’ve implemented based on the previous section.
Provide the access token as specified in the documentation as an authorisation header.
If done correctly, the test party should respond with the service that is requested.
Exposing iSHARE services
Before exposing any of the iSHARE services, firstly, you should have a proper implementation of the iSHARE services consumption. It is needed to retrieve an access token from the Participant Registry or other iSHARE parties.
Certificate Validation
Familiarise yourself with PKI, certificates and how the process of certificate validation works. iSHARE has a certificate cheat sheet.
Implement a function that retrieves the trusted list of Certificate Authorities from the Participant Registry /trusted_list endpoint.
Implement a service that can validate certificates within the scope of iSHARE (see Certificate Validation. The implemented service should check the validity of the certificate itself (such as expiry date, signature, CRL) and whether the certificate issuer is on the trusted list retrieved from the /trust_list endpoint.
Expose Access Token Endpoint
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 sent as described in the /token request from the iSHARE specifications.
For incoming token requests, make sure that they comply with the specified iSHARE token requests.
Validate the certificate used for this request. It is in a JWT header of
client_assertion.Send the client’s party identifier (found
isswithin the request’sclient_assertion) to the Participant Registry /parties endpoint for status check. Response for party status should be equal to Active.If the party is Active, respond to their request with an access token; else, with a Bad Request.
Expose Capabilities Endpoint
To allow other parties to know what your party is capable of, the capabilities endpoint must be implemented. Participants of iSHARE will use this endpoint to see what iSHARE-enabled services your organisation provides. Implementation is pretty straightforward, and the API endpoint specification can be found in the Capabilities Endpoint section.
Additional Authorisation
Services that require additional evidence for authorised access can make use of the iSHARE authorisation protocol. This section should be interesting mostly for Authorisation Registries, Service Providers and Entitled Parties.
Firstly, you will have to familiarise yourself with the iSHARE delegation mask and delegation evidence data models.
Understanding Delegation Mask
Refer to the /delegation endpoint API specification of the Authorisation Registry or Entitled Party. The request body contains a delegation mask, which is in other words, could be called the actual question that is asked. The question contains:
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.
An action field to indicate the kind of action regarding the resource is expected.
Creating Delegation Mask
In order to create a delegation mask (a.k.a. the question), you need to translate an incoming Service Request. Through the Service Request, you should be able to:
Define which party is asking for 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 or service should be able to fill in 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 the Authorisation Registry or the Entitled party should be sent.
Interpreting Delegation Evidence
Delegation evidence will be an iSHARE-compliant JWT which contains the JWT payload described in the delegation evidence section. Based on JWT information, an authorisation decision should be made and enforced for the client.
What’s Next?
After implementing what is described above, you will have to implement endpoints which are required specifically for your organisation. Endpoints could be found in the right menu, under your organisation’s specific role. Once that is done, you will have to pass the Conformance Test Tool.
Last updated