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.

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.

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.8

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 Generic tech 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 Github, 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
    • Send your company namy, country and EORI number to support@ishareworks.org
  • If necessary, apply for a test account for the authorisation registry
    • Send your company name, EORI number and email address to support@ishareworks.org
    • You will receive an email for setting the password of your account
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 generic tech 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

Find various libraries and additional information for JSON Web Tokens on https://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 Generic Tech 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

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

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 /trsuted_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
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’) to the Scheme Owner /parties/{ID} endpoint for status check
  • Check Scheme Owner response for party status
  • If the party is valid, respond to their request with an access token
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

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 generic tech page in het authorisation section
Section checklist
  • I understand the iSHARE authorisation data model

Understanding the question format

  • Refer to the POST /delegation request 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

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!