This page must be considered part of the iSHARE Framework
This page is considered normative and is therefore compliant with RFC 2119.
Machine to Machine (M2M) Authentication
iSHARE refers to the OAuth 2.0 protocol for authenticating parties and providing access tokens based on the iSHARE agreements when requesting access to a iSHARE compliant service. For the most recent version of the OAuth 2.0 specification visit oauth.net. In addition or overriding to the OAuth 2.0 specifications, the following requirements apply for iSHARE:
Clients MUST NOT be pre-registered. A look-up in the Participant Registry is sufficient. It is up to the server to create a new entry for Clients that perform requests for the first time.
The client_id MUST contain a valid Party Identifier of the client.
In case of potential HTTP message size restrictions on the server, a POST call alternative MUST be offered to the /oauth2.0/token endpoint. Therefore, to avoid unaccepted HTTP GET calls, HTTP GET calls MUST be disabled to the /oauth2.0/token endpoint.
Servers MUST NOT issue refresh tokens
In OAuth 2.0 clients are generally pre-registered. Since in iSHARE, servers interact with clients that have been previously unknown this is not a workable requirement. Therefore this spec implements a client identification and authentication scheme, which allows participants to still establish the connection with each other based on the claims about themselves which are digitally signed with a PKI certificate which are trusted in the iSHARE Trust Framework and thereby trusted by its members.
M2M Interaction sections explain how authentication and authorization happens between participants of iSHARE. Authentication part requires a proper /token endpoint implementation. If you are already familiar how authentication works within iSHARE and ready to implement the endpoint, please visit access token section.
Generic Authentication Flow
Based on the described standards and specifications in this scheme, the generic iSHARE Authentication flow is described in the following sequence diagram.
For a deeper understanding of the various roles within the iSHARE network, take a look at the Framework and Roles page in the iSHARE Trust Framework.
The sequence diagram refers to Service Consumer, Service Provider and Participant Registry. Please note that this Authentication flow applies to various possible interactions. Each party that needs to authenticate another party requesting data or services can be authenticated through this flow.
In the demo section you can find Postman Collections that demo this authentication flow from the perspective of a Service Provider.
In the following flowchart, we describe the steps within the authentication flow in greater detail.
Certificate Validation
Validating the certificate mainly consists of two steps:
Verifying the validity of the certificate (steps 2.2.2 and 2.2.3 of the above generic authentication flow).
Verifying the iSHARE Status of the party (step 2.2.6 of the above generic authentication flow).
It is always the responsibility of the receiving iSHARE Party to verify the certificate and the status of the requesting iSHARE Party. During conformance testing (see Conformance Test Tool) it can only be tested how test-certificates are validated. It is important to make sure that real certificates are validated in a proper way, as described below.
1. Verifying the validity of the certificate
A request in iSHARE must always be signed by a certificate that is issued by a certificate authority on the trusted list of iSHARE. Participants can get the trusted list via the /trusted_list endpoint. The trusted list consists of certificate authorities of the qualified Trust Service Providers. The party receiving the request signed by such a certificate is responsible for verifying that the certificate is issued by a certificate authority on the trusted list.
For eIDAS eSEALs it is “Is the Key Usage ( 2.5.29.15 ) equal to "Non-Repudiation".
Any other best practices for validating certificates (such as a check on revocation lists) still apply.
2. Verifying the iSHARE Status
Within iSHARE, it is necessary to match the identity on the certificate that is used to sign the client_assertion with the party identifier within that client_assertion. It is possible that the party identifier is not recorded on the certificate. Therefore, the standard procedure to verify the status of an iSHARE Party is as follows:
Authenticate yourself with the Participant Registry at the /token endpoint.
Send a request to the /parties endpoint of the Participant Registry. Parameter party_id value should be client_id from request (it should be equal to iss or sub in client_assertion).
Decode the parties_token received and check the signature.
In the information, the status of the party is listed under “status” and should be equal to “Active”. The x5c value or x5t#s256 of the certificate can be compared with the certificate which has signed the client assertion in the request.
Note
The old method of validating participant using the certificate subject name is highly discouraged as in practice that method was quite unreliable. In any case the party validating token request (client_assertion) is responsible for proper validation of the incoming requests and with the whole certificate provided in the parties_token must be used for that purposes. This specifications can only provide guidance about it.
Example of iSHARE status verification of Test Service Consumer (seeTest participants):
The call to /parties/{party_id} endpoint to verify the iSHARE status:
GET /parties/did:ishare:EU.NL.NTRLNL-10000001
(URL encoding removed)
The decoded response lists Test Service Consumer as “Active” and includes certificate x5c and x5t#s256 values of the certificate used during registration. One of these certificates should be matching the certificate used for signing the JWT (client assertion):
Besides Machine2Machine interaction, it can occur that it is relevant if a specific person requests data or a service. In order to provide a Service Provider with identity information about a human subject, iSHARE refers to the OpenID Connect 1.0 protocol.
The iSHARE use of OpenID Connect 1.0 is based on the requirements from the official standard. In addition to the OpenID Connect 1.0 specification, the following requirements apply:
Clients (a.k.a. service providers) MUST NOT be pre-registered. A look-up in the iSHARE adherence registry is sufficient. It is up to the server to create a new entry for Clients that perform requests for the first time.
The client_id MUST contain the valid Party Identifier of the client.
Servers SHALL NOT issue refresh tokens.
Generic Authentication Flow
Based on the described standards and specifications in this scheme, the generic iSHARE Human2Machine Authentication flow is described in the following sequence diagram.
The sequence diagram shows how the Service Provider interacts with an Identity Provider in order to receive identity information on the human user (who uses a browser to interact with the Service Provider). The specific details of the steps in this authentication flow are described in the generic API documentation of iSHARE:
Human user might interact with Service Provider in a different way than using a web browser.
After the Service Provider initiates a POST /token request, the Identity Provider can verify their iSHARE Adherence with the Participant Registry. Adherence checks or certificate validation is not displayed in this flow as this flow only describes the generic OpenID Connect 1.0 flow
This flow only describes Identification & Authentication of a human user, while in iSHARE it is always relevant that their Authorization (acting on behalf of an organization) is also verified. This process is described in the Human Authorization section.
