OpenID Connect endpoint for obtaining the OAuth access token and OpenID Connect id token. Response contains, besides the OAuth access token, also an iSHARE compliant JWT id_token.
Request
HTTP methods
POST
Headers
Content-Type
String.
Defines request body content type. MUST be equal to application/x-www-form-urlencoded.
Parameters
grant_type
String.
OAuth 2.0 grant type. MUST be equal to authorization_code because code which was retrieved from authorize endpoint will be used.
client_id
String.
OpenID Connect 1.0 client ID. This parameter represents iSHARE identifier of Service Provider, so EORI number must be used.
client_assertion_type
String.
OpenID Connect 1.0 client assertion type. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST be qual to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
String (JWT).
OpenID Connect 1.0 client assertion. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain JWT token conform iSHARE specifications, signed by the client.
redirect_uri
String.
Redirect URI which was used in authorize request.
code
String.
Oauth 2.0 authorization code. MUST be equal to a value of authorization code which was received from the Identity Provider or Identity Broker in response to the /authorize request.
(URL encoding removed, and line breaks added for readability)
Response
Headers
Content-Type
String.
Defines response body content type. MUST be equal to application/json.
Cache-Control
String.
Holds instructions for caching. MUST be equal to no-store.
Pragma
String.
It is used for backwards compatibility with HTTP/1.0 caches where the Cache-Control HTTP/1.1 header is not yet present. MUST be equal to no-cache.
HTTP status codes
200 OK
When a valid request is sent an OK result should be returned.
400 Bad Request
When invalid request is sent a Bad Request result should be returned.
Parameters
id_token
String (JWT)
ID Token value associated with the authenticated session. To understand its structure please refer to section below.
access_token
String.
The access token which will be used to access endpoints that require authorization.
token_type
String.
Since we follow OpenID Connect 1.0 specification which is on top of OAuth 2.0 specification, value should be equal to Bearer.
expires_in
Integer.
Access token expiration time in seconds. Should be 3600.
ID Token Parameter JWT
In response to the /token endpoint request, an id_token is provided to the client (as an addition to the regular OAuth access token response). This id_token is an iSHARE compliant JWT, however the sub parameter is changed and additional parameters are added.
The id_token contains the modified sub parameter and the following additional parameters:
sub
String.
OpenID Connect 1.0 locally unique and never reassigned identifier within the Identity Provider for the Human Service Consumer, which is intended to be consumed by the client. Also known as iSHARE human pseudonym. In order to understand more about this value, please refer to human pseudonym section.
auth_time
String.
OpenID Connect 1.0 time when the Human Service Consumer authentication occurred. Formatted in Unix timestamp format.
nonce
String.
OpenID Connect 1.0 value used to associate a client session with an ID Token. Contains value as passed in to the /openid_connect1.0/authorize endpoint. The client application needs to verify if the sent value is equal to the value which comes back from IdP /token endpoint response.
acr
String.
OpenID Connect 1.0 authentication context class reference value. MUST either contain urn:http://eidas.europa.eu/LoA/NotNotified/low, urn:http://eidas.europa.eu/LoA/NotNotified/substantial or urn:http://eidas.europa.eu/LoA/NotNotified/high, depending on the quality of the authentication method. To understand requirements for each level of assurance, please look at LOA table.
azp
String. Optional.
OpenID Connect 1.0 authorized party. MUST be identical to the client_id that requested the ID Token. Also identical to aud.
ID verification performed by registration authority
High
In-person ID proofing at registration authority
ID verification using official government sources and documents
Human Pseudonym
An essential part of the Human2Machine flow is the pseudonym used to refer to humans without exposing their identity.
Pseudonyms are used to obscure the real identities of the human users for privacy issues. It’s possible that a human user may be representing more than one organization, which the service provider may not need to know about. If such user uses a single identity then he could be unwillingly giving away this possibly sensitive information.
Using pseudonyms, the user’s identities are not easily linked to each other. On the other hand, some use cases may require the user’s identities to be linkable to service the user better. In this case the use of pseudonym makes sense as a user could always link them together on his own will.
The following is a list of criteria for generating pseudonyms:
The generation of a pseudonym MUST be non predictable;
The exact method of generating the pseudonym is left out to Identity Providers;
The Identity Provider MUST be able to identify the human user from the pseudonym;
The pseudonym MUST depend on the human user;
The pseudonym MUST depend on the Identity Provider;
The pseudonym MUST depend on the Service Provider.
Tip
One of the approaches to solve this issue could be a storage with user’s identifier, service provider’s identifier and UUID/GUID assigned for the combination which in this case would be called human pseudonym.
