iSHARE Test environment API Reference

Welcome to the iSHARE Test Environment!

The purpose of this page is to help you test your implementation of iSHARE.

This page contains:

Examples of iSHARE
  • Postman and Demo examples of iSHARE, to get some feel with the way of working before actual implementation is needed
Test certificates
  • How to get your iSHARE Test Certificate
  • Certificates of the iSHARE Test CA, which you need to trust in order to work within our Test environment
Test API Endpoint overview per Test participant
  • Various dummy implementations of iSHARE compliant parties have been created
  • With your test implementation and iSHARE Test Certificate, you can communicate with these Test participants
Conformance Test Tool
  • If you are ready to become an official iSHARE member, your systems need to be tested on compliance to the iSHARE specifications
  • iSHARE provides a tool for automated testing of your API endpoints and provides reports
  • A list of test cases is available, which also helps with validating API requests correctly
API Endpoint base URL
https://party.isharetest.net
Schemes: https
Version: 1.9

Postman examples

This section contains various Postman collections, which can be used to manually test iSHARE APIs. In these collections, you as a user are impersonating Test participant ‘ABC Trucking’.

In order to impersonate ABC Trucking, these Postman collections contain the private key of ABC Trucking. For non-dummy parties, private keys should never be shared with the Scheme Owner or other iSHARE Parties

Each collection contains all API endpoints of a specific Test participant, and as ABC Trucking you are able to consume these API endpoints.

In order for the collections to work, please download the iSHARE Test Environment and global variables for Postman “ABC Trucking and the Scheme Owner”
  • Click here for the Postman collection
“ABC Trucking and Warehouse 13”
  • Click here for the Postman collection
“ABC Trucking and the Authorisation Registry”
  • Click here for the Postman collection
“ABC Trucking and Awesome Widgets”
  • Click here for the Postman collection
“End-2-End flow: ABC Trucking gets container data from Warehouse 13 (Service Provider requests Delegation Evidence)”
  • Click here for the Postman collection, and here for the accompanying slides. See below for a walkthrough of this demo.
“End-2-End flow: ABC Trucking gets container data from Warehouse 13 (Service Consumer provides Delegation Evidence)”
  • Click here for the Postman collection, and here for the accompanying slides. See below for a walkthrough of this demo.
Postman collection instructions

                  

Request an access token:

  • Open the /connect/token request
  • The client_assertion is generated in the background/
  • Run the request without making additional changes, the response should contain (among others) an access token value

Request a service:

  • Open a service request
  • The access token is automatically copied.
  • Run the request, the response should contain (an encoded) response
  • If the response is encoded, decode the token via https://www.jwt.io and inspect the results

For /delegation service requests:

  • Please view the demo in the next section, this will explain how authorisation in iSHARE can work and Postman examples are shown

Demo examples

This section contains various video demos of iSHARE in action. New material is added when available.

iSHARE End-2-End Flow: Walkthrough of postman (demo 1a)

iSHARE End-2-End Flow: Walkthrough of postman (demo 1b)

iSHARE Authorisation Registry demo:

iSHARE Machine2Machine demo (ICT & Logistics 2017, in Dutch)

iSHARE Video's with links to API endpoints
                  

iSHARE End-2-End Flow: Walkthrough of postman (demo 1a)

At what time in the use case are what API endpoints used.

Time API Time API
07:06 W13 POST /connect/token 10:04 SO GET /parties
07:30 SO POST /connect/token 10:24 AR POST /connect/token
07:40 SO GET /parties 10:38 SO POST /connect/token
09:45 W13 /service 10:43 SO GET /parties
10:00 SO POST /connect/token 11:00 AR POST /delegation

iSHARE End-2-End Flow: Walkthrough of postman (demo 1b)

At what time in the use case are what API endpoints used.

Time API Time API
07:57 SO POST /connect/token 13:48 W13 POST /connect/token
08:15 SO GET /parties 13:54 SO POST /connect/token
10:06 AR POST /connect/token 14:05 SO GET /parties
10:18 SO POST /connect/token 15:32 W13 /service
10:25 SO GET /parties 16:35 SO GET /parties
10:44 AR POST /delegation

Test certificates

Get Test certificate

In order to get an iSHARE Test certificate, the iSHARE organisation needs to have:

  • Your company common name
  • Your company country
  • Your company EORI number (used as iSHARE identifier)

Provide this information to tooling@ishareworks.org, and you will be contacted when your certificate is created and you are added to the Test participants database.

iSHARE Test CA

iSHARE Test certificates are issued by the iSHARE Test Certificate Authority. Please download the certificates as they are needed to trust iSHARE Test certificates when interacting with the test environment.

In case your knowledge of certificates could use a quick refreshment, please refer to the iSHARE Certificate 'Cheat sheet'. This document gives a brief overview of common certificate types, how certificates are used within iSHARE and various OpenSSL commands for certificate conversion. Click here to check out the cheat sheet.

iSHARE Test CA

Click here to download the iSHARE Root CA (.pem)

Click here to download the iSHARE Signing CA (.pem)

Test participants

ABC Trucking

Test implementation of a pure service consuming iSHARE participant. ABC Trucking does not expose any service, they only consume services.

EORI / iSHARE identifier: EU.EORI.NL000000001

Scheme Owner

Test implementation of the iSHARE Scheme Owner. The Scheme Owner maintains a database of active iSHARE participants

API Endpoint base URL: https://scheme.isharetest.net

EORI / iSHARE identifier: EU.EORI.NL000000000

Certificate (.pem) here.

For a detailed API specification, please refer to the Test environment specs page.

API Test endpoints

Scheme Owner - https://scheme.isharetest.net
POST /connect/token Obtains OAuth access token
GET /capabilities Obtains iSHARE enabled services list
GET /parties Obtains information on iSHARE participants
GET /parties/{partyID} Obtains information on iSHARE participant
GET /trusted_list (not yet live) Obtains iSHARE trusted list of CAs
POST /certificate_validation Temporary service, validates a certificate
* POST /testing/generate-jws Generates iSHARE signed JWT client_assertion
* GET /me Returns client info

* NOT part of the official iSHARE specification (provided for additional test functionality only)

Warehouse 13

Test implementation of an iSHARE Service Provider. Besides the required /token and /capabilities endpoints, Warehouse 13 exposes different services under iSHARE.

API Endpoint base URL: https://w13.isharetest.net

EORI / iSHARE identifier: EU.EORI.NL000000003

Certificate (.pem) here

For a detailed API specification, please refer to the Test environment specs page.

API Test endpoints

Warehouse 13 - https://w13.isharetest.net
POST /connect/token Obtains OAuth access token
GET /capabilities Obtains iSHARE enabled services list
* GET /me Returns client info
* POST /boom_access Mock service that returns 'true'

* NOT part of the official iSHARE specification (provided for additional test functionality only)

Awesome Widgets

Test implementation of an iSHARE Service Provider. Besides the required /token and /capabilities endpoints, Awesome Widgets exposes different services under iSHARE.

API Endpoint base URL: https://awesome.isharetest.net

EORI / iSHARE identifier: EU.EORI.NL000000002

Certificate (.pem) coming soon!

For a detailed API specification, please refer to the Test environment specs page.

API Test endpoints

Awesome Widgets - https://awesome.isharetest.net
POST /connect/token Obtains OAuth access token
GET /capabilities Obtains iSHARE enabled services list
* GET /me Returns client info
* POST /boom_access Mock service that returns 'true'

* NOT part of the official iSHARE specification (provided for additional test functionality only)

Banana&Co

Test implementation of an Entitled Party. Besides being a resource owner across many systems, Banana &Co also provides the possibility to manage authorisation in their systems. Just as an Authorisation Registry, this Entitled Party provides a /delegation endpoint.

API Endpoint base URL: https://banana.isharetest.net

EORI / iSHARE identifier: EU.EORI.NL000000005

Certificate (.pem) here.

Contact support@ishareworks.org to request an account for the Register

For a detailed API specification, please refer to the Test environment specs page.

API Test endpoints

Banana &Co - https://banana.isharetest.net
POST /connect/token Obtains OAuth access token
GET /capabilities Obtains iSHARE enabled services list
POST /delegation Obtains delegation evidence
* GET /me Returns client info
* /admin Web interface for policy management

* NOT part of the official iSHARE specification (provided for additional test functionality only)

Authorisation Registry

Test implementation of an Authorisation Registry. Users can get an account for the Authorisation Registry, so they can manage some dummy policies for testing authorisation flows.

DISCLAIMER: This is merely a tool for testing and as such not fit for production/live situations. The Registry gives an idea of what an Authorisation Registry could look like, but the entire interface is not mandatory.

API Endpoint base URL: https://ar.isharetest.net

EORI / iSHARE identifier: EU.EORI.NL000000004

Certificate (.pem) here.

Contact support@ishareworks.org to request an account for the Register

For a detailed API specification, please refer to the Test environment specs page.

API Test endpoints

Authorization Registry - https://ar.isharetest.net
POST /connect/token Obtains OAuth access token
GET /capabilities Obtains iSHARE enabled services list
POST /delegation Obtains delegation evidence
* POST /policy Provides new policy
* GET /me Returns client info
* /admin Web interface for policy management

* NOT part of the official iSHARE specification (provided for additional test functionality only)

Conformance Test Tool

Introduction

The Conformance Test Tool enables users to perform automated tests on their API services. Users can login to the Conformance Test Tool here (request an account at tooling@ishareworks.org) and run a set of test cases on their API services. Different roles in the iSHARE Network require different sets of test cases, as is detailed below.

To be allowed to join the production environment of the iSHARE Network, parties will need to pass all test cases that apply to their role in the iSHARE Network. The Conformance Test Tool will show you per test case whether you passed or failed the case.

After logging in to the Conformance Test Tool, users will be able to configure the URLs of their API services and are able to run a test case on these API Services themselves. After some time, users will receive the results of such a test run in the Conformance Test Tool or by mail notification. The results will detail if you have passed the tests, or if not, what test cases failed, and why. If you fail one or more test cases, your API services are not yet conforming to the iSHARE standards as specified in the scheme and on the developer portal.

Conformance Test Tool: quick facts

                  
  • Request an account at tooling@ishareworks.org
  • Service Providers are tested on /capabilities and /token
  • Authorization Registries are tested on /capabilities, /token and /delegation
  • You will be tested on this List of Test Cases. This list is also useful in checking how to do certificate validation!

Specifications

The API services that need to conform to iSHARE standards differ per party in the iSHARE Network. In this phase, we focus mainly on the Service Consumer, the Service Provider and Authorization Registries. The roles of Identity Provider and Identity Broker will be added, pending the developments in H2M-autorization flow. Other service endpoints need to be conforming to the iSHARE standards and we will add information on this soon.

For Service Consumers:

  • The Service Consumer does not necessarily host API services. The only requirement is to be able to get a valid access token from the Scheme Owner.

For Service Providers:

  • The /connect/token endpoint MUST be conforming to the iSHARE standards
  • The /capabilities endpoint MUST be conforming to the iSHARE standards

For Authorization Registries:

  • The /connect/token endpoint MUST be conforming to the iSHARE standards
  • The /capabilities endpoint MUST be conforming to the iSHARE standards
  • The /delegation endpoint MUST be conforming to the iSHARE standards. For proper testing of this endpoint, users SHOULD provide two valid delegation requests: one that returns a “Permit” when requested, and one that returns a “Deny” when requested.

The full list of test cases per API service can be downloaded here.

As a user of the Conformance Test Tool, you can

  • run the full test run for a specific role in the iSHARE Network (i.e. Service Provider or Authorization Registry) on your API services
  • run a test run on your specific API Service (i.e. /connect/token or /delegation)
  • run a specific test case on your API Service

Requirements

To be able to join the iSHARE network in the production environment, you are required to pass a full test run for your specific role in the network. If you have passed the test run for your specific role, please notify us of this at tooling@ishareworks.org with the identifier of your test run.

Questions?

Visit the iSHARE community forum