Getting started with iSHARE!

This developer portal provides everything needed to get started with implementing iSHARE for your organisation. This section gives insights on how to actually start with implementing iSHARE, and where to find relevant information of specifications.

If you are looking for demo content, such as videos and Postman collections, that showcase how iSHARE works technically, head over to the Demo section!

Currently no full iSHARE libraries exist, and the open standards used need to be configured towards iSHARE usage. It is therefore essential to familiarise yourself with some technical concepts, in order to be able to smoothly implement iSHARE for your organisation. There do exist some code snippets which you can find on our GitHub-repository. If you'd like to add your own code to our repository and help the iSHARE Community please let us know at tooling@ishareworks.org.

If you have any questions on iSHARE, be sure to visit the iSHARE Community Forum! Here you can create topics to discuss issues that may arrive during iSHARE implementation. You can also subscribe to updates to the Developer Portal and technical updates in general via this topic on the forum.

Read this page!
                  

We know developers aren’t fond of reading descriptions, but it will seriously help you in your iSHARE implementation. We will keep it as short as possible!

Version: 1.10

What to know beforehand


iSHARE is not a platform

  • iSHARE (from a technical perspective) is an authentication/authorisation protocol for both machine2machine and human2machine communication based on a JSON REST API architecture
  • Authentication is heavily based on Public Key Infrastructure (PKI) and therefore certificates and public/private key pairs

Regarding message content:

  • iSHARE relies heavily on (signed) JSON Web Tokens (JWS / JWT) for protecting the integrity of message content
  • Your systems need to be able to validate signatures and interpret the content of JWTs
  • Your systems must be able to create and sign these tokens depending on the context (for example client/server, timestamps)

Regarding authorisation:

  • Authorisation within iSHARE is a proprietary solution
  • The authorisation section within the Technical Agreements page covers the iSHARE data model for authorisation
  • Depending on your iSHARE use case, you might not even need iSHARE authorisations
Essential knowledge
  • Familiarise yourself with PKI, certificates and how the process of certificate validation works
  • iSHARE has an example certificate validation code snippet on our GitHub-repository, check it out
  • iSHARE has a ‘certificate cheat sheet’, check it out

  • Familiarise yourself with JWT, JWS, and how to create/sign these tokens
  • Refer to jwt.io for everything on JSON Web Token and various libraries for JWT creation/validation

  • Familiarise yourself with the iSHARE authorisation data model if needed for your use case

Starting development

  • You need to apply for an iSHARE Test certificate in order to use our test environment
  • If necessary, apply for a test account for our dummy authorisation registry:

A video demonstrating how certificates are used in iSHARE can be found here.

Section checklist
  • I have received an iSHARE Test certificate
  • I have successfully activated my Authorisation Registry account

Actual development

Consuming iSHARE services

Creating JSON Web Tokens

  • Various requests or responses that follow the iSHARE specifications contain signed JSON Web Tokens
  • Start with creating a self-signed identity claim, a “client_assertion”, following the specifications found on the Technical Agreements page in the authentication section (JWS)
    • Construct the correct JWT header
    • Construct the correct payload depending on the context within which the token is used
    • Sign token according to JWS specifications

A video demonstrating how JSON Web Tokens are used in iSHARE can be found here.

Find various libraries and additional information for JSON Web Tokens on jwt.io


Section checklist
  • Construct a correct JWT Header and Payload
  • Sign the token according to JWS specifications
  • Construct a correct client_assertion

Get an OAuth access token

  • The first workflow you should implement, is an OAuth access token request
  • In the iSHARE OAuth 2.0 section on the Technical Agreements page, the content for the token request is described
  • Choose a test party from the iSHARE Test environment, and create a “client_assertion” with the correct audience
  • Create a token request based on the above specifications, containing your iSHARE Test certificate and test-certificate based “client_assertion”
  • If done correctly, the test party should respond with an access token

A video demonstrating how access tokens are requested in iSHARE can be found here.


Section checklist
  • I am able to create a correct token request
  • I have successfully received an access token

Request services with access tokens

  • Select a test party from the iSHARE Test environment that exposes a service, with access control based on the access token (for example /capabilities is not restricted to additional authorisation requirements)
  • 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

A video demonstrating examples of services being consumed can be found here.


Section checklist
  • I have successfully used the access token to consume a service

Exposing iSHARE services

Implement iSHARE consuming steps

  • All previous steps under ‘consuming iSHARE services’ need to be implemented in order to expose services
Section checklist
  • I have implemented the steps under ‘consuming iSHARE services’

Certificate validation

  • Implement a function that retrieves the ‘trusted list of Certificate Authorities’ from the Scheme Owner /trusted_list service
  • Implement a service that can validate certificates within the scope of iSHARE
    • Check validity of certificate itself (such as expiry date, signature, CRL)
    • Check whether the certificate issuer is on the trusted list of iSHARE

More detailed information on how to validate certificates can be found here.

Section checklist
  • I have successfully retrieved the trusted list
  • I have implemented a function that validates a certificate itself
  • I have implemented a function that verifies whether the certificate Issuer is on the trusted list

Expose /token endpoint

  • 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
  • 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
  • Check Scheme Owner response for party status "Active"
  • If the party is "Active", respond to their request with an access token

More detailed information on how to validate token requests can be found here.

Section checklist
  • I have successfully exposed an API endpoint that handles token requests
  • I can check the validity of the certificate used
  • I can check whether the party is an active iSHARE participant
  • I can provide an access token to a valid iSHARE party

Expose /services

Services may already exist, but also new services could be exposed. The important factor is to incorporate the iSHARE access token within your authorisation protocol for usage of these services. For example, require the access token as Authorization header in requests send to your APIs, or in any way that you see fit. Have a function that validates the access token, and start sharing your services in a secure way, even with unknown iSHARE parties.

  • Within iSHARE, exposing a /capabilities endpoint is required
  • Participants of iSHARE can use this endpoint to see what iSHARE enabled services your organisation provides
Section checklist
  • I can check whether the access token is issued by myself and valid (not expired)
  • I have a service that accepts access tokens, acquired based on the iSHARE authentication flow, as valid authorisation
  • I am exposing a /capabilities endpoint which takes an access token as valid authorisation

Test conformance to iSHARE Standards

To make sure that you have done all of the above steps correctly and are implementing the iSHARE Standards correctly, you can run some tests on your endpoints. This is done in the Conformance Test Tool. You can request access to this endpoint by mailing your EORI, company name and e-mailadress to tooling@ishareworks.org. Please read the content on the Conformance Test Tool carefully, with special regards to the test cases (PDF) that will be run on your endpoints.

Section checklist
  • I have requested access to the Conformance Test Tool
  • I have tested my endpoints at the Conformance Test Tool.
  • All of my endpoints passed the Conformance Test Tool

Authorisations

  • Services that require additional ‘evidence’ for authorised access can make use of the iSHARE authorisation protocol
  • Familiarise yourself with the iSHARE authorisation data model on the Technical Agreements page in het authorisation section

A video demonstrating the authorisation protocol can be found here.

Section checklist
  • I understand the iSHARE authorisation data model

Understanding the question format

  • Refer to the /delegation endpoint API specification of the Authorisation Registry or Entitled Party
  • The requestBody contains a ‘delegation_mask’ property, which is 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
  • You can find a video with an explanation of the 'delegation_mask' here.

Section checklist
  • I understand what a question aimed at an Authorisation Registry or Entitled Party should look like, for interoperability purposes

Creating the question

  • Translate an incoming Service Request to a ‘delegation_mask’
  • Through the Service Request, you should be able to:
    • Define which party is asking access to a resource or service
    • Your system’s knowledge of ownership of this resource of service should indicate the second party that is needed for the mask
    • The resource or service itself is clear through the request
    • The nature of the exposed service can indicate what kind of action is expected
  • Send the full /delegation request to an Authorisation Registry or Entitled party

Section checklist
  • I can successfully translate an incoming service request to a ‘delegation_mask’
  • Send this information to the /delegation endpoint according to the specifications of iSHARE

Interpreting delegation evidence

  • The response will contain a signed JWT, which contains:
    • a timestamp for which it is valid;
    • the two concerning parties;
    • the legal framework that applies to the requested delegation;
    • describes the resource that is requested; and
    • indicates whether the requested access should be ‘Permit’ or ‘Deny’
  • Based on this information, an authorisation decision can be made and enforced to the client

Section checklist
  • I can interpret whether delegation evidence indicates if a positive or negative authorisation decision can be made

Still reading?


You appear to have completed the iSHARE implementation. Check out the 5-step plan on the iSHARE website to become a full iSHARE participant and go live!

Section checklist
  • Success!

Questions?

Visit the iSHARE Community Forum