Getting started
Before getting started it is highly recommended to familiarise yourself with essentials of the iSHARE Trust Framework.
You need to apply for an iSHARE Test Certificate in order 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 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 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.
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 on M2M Authentication section.
Choose a test party from the iSHARE Test Participants and create a client_assertion with the correct audience.
Head over to Access Token Endpoint section 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.
Note
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 authorization 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 authorization header.
If done correctly, the test party should respond with the service that is requested.
Exposing iSHARE services
Before exposing any of iSHARE services, firstly you should have a proper implementation of iSHARE services consumption. It is needed in order to retrieve an access token from the Participant Registry or other iSHARE parties.
Certificate Validation
Familiarize 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. Implemented service should check validity of certificate itself (such as expiry date, signature, CRL) and whether the certificate issuer is on the trusted list retrieved from the /trust_list endpoint.
Note
iSHARE has example projects and code snippets on GitHub, it also contains certificate validion, check it out.
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 send 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 as
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 Bad Request.
Note
More about iSHARE ID can be found here.
Sequence diagram of this flow can be found at Generic Authentication Flow section.
Expose Capabilities Endpoint
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 Capabilities Endpoint section.
Additional Authorisation
Services that require additional evidence for authorized 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 familiarize yourself with 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.
Action field to indicate the kind of action regarding the resource is expected.
Note
Creating Delegation Mask
In order to create 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 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.
Interpreting Delegation Evidence
Delegation evidence will be iSHARE compliant JWT which contains JWT payload described at delegation evidence section. Based on JWT information, an authorization decision should be made and enforced to the client.
What’s Next?
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 Conformance Test Tool.
Last updated