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 firstname.lastname@example.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!
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)
- 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
- 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
- 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.
- I have received an iSHARE Test certificate
- I have successfully activated my Authorisation Registry account
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
- 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.
- 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.
- 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
- I have implemented the steps under ‘consuming iSHARE services’
- 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.
- 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.
- 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
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
- 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 email@example.com. 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.
- 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
- 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.
- 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.
- 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
- 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
- I can interpret whether delegation evidence indicates if a positive or negative authorisation decision can be made
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!