Before getting started it is highly recommended to familiarize yourself with essentials of iSHARE that are described in introduction section.
You need to apply for an iSHARE Test certificate in order to use our test environment. How to do that is described at Get Test Certificate section.
Exposing iSHARE services
Before exposing any of iSHARE services, firstly you should have a proper implemention of iSHARE services consumption. It is needed in order to retrieve an access token from the Scheme Owner 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, check it out.
Implement a function that retrieves the trusted list of Certificate Authorities from the Scheme Owner /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 of iSHARE.
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 iSHARE ID or EORI (found as subject within the request’s client_assertion) plus the certificate’s subject_name to the Scheme Owner /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.
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 Authorization
Services that require additional evidence for authorized access can make use of the iSHARE authorization protocol. This section should be interesting mostly for Authorization 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 Authorization 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
You can find a video with an explanation how delegation mask is used within Auhorization Registry in Videos section.
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 Authorization 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.