OAuth 2.0

This part of the iSHARE Scheme is considered normative and is therefore compliant with RFC 2119.

iSHARE uses the OAuth 2.0 protocol for authenticating parties and providing access tokens when requesting access to a service within iSHARE.

On this page a brief description of OAuth is provided. For the most recent version of the OAuth 2.0 specification click on this link.

Furthermore this page describes the generic iSHARE Authentication flow.

iSHARE facilitates an ecosystem within which parties can interact with previously unknown parties, pre-registration is therefore not a prerequisite and thus requires alterations to the official standard.

Generic OAuth 2.0 requirements

In addition to the specifications below, for all uses of OAuth 2.0 the following requirements apply:

Clients MUST NOT be pre registered. A look-up in the iSHARE adherence registry is sufficient. It is up to the server create a new entry for Clients that perform requests for the first time ¹
The client_id MUST contain the valid iSHARE identifier of the client
For interoperability reasons clients SHALL only make HTTP GET calls to the /oauth2.0/token endpoint.
Servers SHALL NOT issue refresh tokens

Additional rationale

¹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 iSHARE implements a generic client identification and authentication scheme, based on iSHARE whitelisted PKIs.

iSHARE authentication flow

Based on the described standards and specifications in this scheme, the generic iSHARE Authentication flow is described in the following sequence diagram.

Access token specifications in OAuth 2.0

Used to obtain an OAuth access token from a party that exposes an iSHARE API.

Based on the requirements in https://tools.ietf.org/html/rfc6749

OAuth access token API specifications example

Parameter	Contained in	Type	Required	Description
Used to obtain an OAuth access token from the Authorisation Registry
`grant_type`	query	string	Yes	OAuth 2.0 grant type. MUST contain “authorization_code”
`scope`	query	string	No	OAuth 2.0 scope. Defaults to "iSHARE", indicating all rights are requested. Other values MAY be specified by the API owner and allow to get tokens that do not include all rights
`client_id`	query	string	Yes	OpenID Connect 1.0 client ID. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain a valid iSHARE identifier
`client_assertion_type`	query	string	Yes	OpenID Connect 1.0 client assertion type. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain “urn:ietf:params:oauth:client-assertion-type:jwt-bearer”
`client_assertion`	query	string	Yes	OpenID Connect 1.0 client assertion. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain JWT conform iSHARE specifications
	Example OAuth token request Expand source https://randomserver.com/authorisation_registry/oauth2.0/token?grant_type=client_credentials& scope=iSHARE&client_id=EU.EORI.NL000000001&client_assertion_type=urn:ietf:params:oauth:client -assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIng1YyI6WyJNS UlHQVRDQ0ErbWdBd0lCQWdJQ0VBb3dEUVlKS29aSWh2Y05BUUVMQlFBd2daQXhDekFKQmdOVkJBWVRBazVNTVFzd0NRWU RWUVFJREFKT1NERVBNQTBHQTFVRUNnd0dhVk5JUVZKRk1SRXdEd1lEVlFRTERBaFRaV04xY21sMGVURW9NQ1lHQTFVRUF 3d2ZhVk5JUVZKRklFNU1JRU5sY25ScFptbGpZWFJsSUVGMWRHaHZjbWwwZVRFbU1DUUdDU3FHU0liM0RRRUpBUllYYVc1 bWIwQnBjMmhoY21VdGNISnZhbVZqZEM1dmNtY3dIaGNOTVRjeE1ERXlNRGd6TXpVNVdoY05NVGd4TURJeU1EZ3pNelU1V 2pDQmxURUxNQWtHQTFVRUJoTUNUa3d4Q3pBSkJnTlZCQWdNQWs1SU1SSXdFQVlEVlFRSERBbEJiWE4wWlhKa1lXMHhEek FOQmdOVkJBb01CbWxUU0VGU1JURVdNQlFHQTFVRUN3d05SSFZ0YlhrZ1ptOXlJRkJQUXpFVU1CSUdBMVVFQXd3TFRrd3d NREF3TURBd01ERXhKakFrQmdrcWhraUc5dzBCQ1FFV0YybHVabTlBYVhOb1lYSmxMWEJ5YjJwbFkzUXViM0puTUlJQklq QU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF2LzVmdElwdTE0bnl2MG9DUmRydEpsVk9icEV0TmpkT FNNSSs3SzJOL05GWHlOUGFQM3c0ajB2a29Ma0lVUmJEaTJ3S29oUXNqanJEM21yR1RWN1ZqdWlaSzM1WlZPMGtlczlyZU hoeTNHNnIxMTJ4S2x1N3QwWmJxU2I2U3hrMW94c0FxQWppOUsyemtwN055UW00NVd4OFJEQzBsTytYalBpbExUZEp2VlV nWktlVkRmc1l6QjV5NXc2WG90aE1VNGgyNzBoVUNibkYwZ1FyQjFzL0RPeC9yd2xqMHc5ZmRTYjlsZk9SdzE2SUM5T3B3 VzdsQU5kdTFkeTY4RnpGdHdxK1BHNXJBWThXOGU3MGNiT0hSSVRERjNKSjRlelEzY0NsaFlBQ3JPdUEvdkV2bnU0MzNOb ml3UGVGa2VWSGhqQlIzOG53RzljQWJGU2d2Sm9rM1FJREFRQUJvNElCWERDQ0FWZ3dDUVlEVlIwVEJBSXdBREFSQmdsZ2 hrZ0JodmhDQVFFRUJBTUNCa0F3TXdZSllJWklBWWI0UWdFTkJDWVdKRTl3Wlc1VFUwd2dSMlZ1WlhKaGRHVmtJRk5sY25 abGNpQkRaWEowYVdacFkyRjBaVEFkQmdOVkhRNEVGZ1FVZnpHMElFMEV2OFBxZUNTbHJvTXVOTmlkNFA0d2diNEdBMVVk SXdTQnRqQ0JzNEFVamtaTjB4U0pxbGNpWlZTTDFQYlZtd0kzM091aGdaYWtnWk13Z1pBeEN6QUpCZ05WQkFZVEFrNU1NU XN3Q1FZRFZRUUlEQUpPU0RFU01CQUdBMVVFQnd3SlFXMXpkR1Z5WkdGdE1ROHdEUVlEVlFRS0RBWnBVMGhCVWtVeEVUQV BCZ05WQkFzTUNGTmxZM1Z5YVhSNU1SUXdFZ1lEVlFRRERBdHBVMGhCVWtVZ1VtOXZkREVtTUNRR0NTcUdTSWIzRFFFSkF SWVhhVzVtYjBCcGMyaGhjbVV0Y0hKdmFtVmpkQzV2Y21lQ0FoQUFNQTRHQTFVZER3RUIvd1FFQXdJRm9EQVRCZ05WSFNV RUREQUtCZ2dyQmdFRkJRY0RBVEFOQmdrcWhraUc5dzBCQVFzRkFBT0NBZ0VBRGpvUVlxdjVIS3pKckY5bUttUy9PQjMvM 0FodFJQVm1WRHFkTmNPdytHVTE0SXNLczQwN3ArbFhuMmhON2VaUEpwSVpyVDdqQzl2ZnVOTG1PbzEybXZ0YlBGeTdDcT krU1lCNkEvZ2NXK0NZemIrKzBWM3o0ZlR5Y1ZjRXVRQWc4ODM5TWM2clNhSXRha0Q3YnN1Y2EvTldyZFVqSUU1eDBNQ2Z YQ21WTS9NeXdlNHdGdEE5ZU5yN0Z1SUN4L0JhdkVnSU8rVmRFdDBKVUp6WGNYK0wrbGM1T0FCQlNidHZjT2pWblRHRDVu T3ZodFdrQy80eWpaVmx3Y2EyK1E4OVBGcVI2OTRYRjhvc0szWFZTWGZVK2pmUk50K0EyeXpWTmpaemVucDF6a1RiZkdua XBDek9QcllaMGxDUzZPUkF3cDdoZ1BrS3hJb1BqTjJkTE11TzAyWVZkV2t2SFVvTXNoN0F0Mjh0RGM2TEVsTjc1Zlgxbn VPdjgxMUcyYURxU0d6Rnc0SkdRU25lR3hsaDlMekdzaEkxaWorTm5pQm5uOTYrMGpHSm5OSjJGY3F1Y2dpZ21tSWVvY0h 6QjlLV3Q3eFRzZmdnVFduZjd3dzA3OGgvZStrNFZ3V2JITjUrcXdURHFra2poTHh6Vm9jTzRHVWw2RzZXUmg2VHp6ekFq SUNiS1BZclI5VWcxaGYxSFNOcG93RHU1MWlxVStmV1VZV0FRcVVSakV2Z0k0aFBmcVhya0x5NVR6OVdLQ1diR0hyRnR5Z VlXdGpxenhXdzlpN3Fwc3d3S002M1RLQ1dVVWJoNTlJTitFSTZqczhUMTc2b2tkSkVUUFRaOXpGcjNvNHBIVERBS0VORE hmcjJwT293emZsazlhM3F3RTkvNndxMlhhalI1R289Il19.eyJpc3MiOiJFVS5FT1JJLk5MMDAwMDAwMDAxIiwic3ViIj oiRVUuRU9SSS5OTDAwMDAwMDAwMSIsImp0aSI6InpGMXFHS0J2NzgiLCJpYXQiOiIxNTEzMDcwODY3IiwiZXhwIjoxNTE zMDcwODk3LCJuYmYiOjE1MTMwNzA4NjcsImF1ZCI6Ik5MLkVPUkkuTkw4MTI0NTg4MzcifQ.bPOTFBBg8pedWkfoRKMt1 uaa0albfWkgSObePtOSKxV0VOPUb1uencLihV086HWJeqO7DBZ2jx_rn96FfpojJnn2z2aQnBSX06IYPTYYcze543-wb- 8vCor7hM6idGBbDCmeKQvFrIYaYmt34GeU0UjWnNMPGdh90vzbhqgPUlZixtUWfQYn0NxYJf7RGmEhmRybXm2zFl0ooom 1d-zoZzwuTAzfZqa2rM986VG8WikewxN2IUafhKoQ_w42MB6WpPki8a0EJ07xUZozSybSQvFRWyKxN-TCtixp3B5nGo9T uZvkOf1f0RpL8-zTU2DQOFnhz8p7gwF10srNYYv3Sw
Responses
Code	Description
200	OK Example value Expand source { "access_token": "string", "token_type": "string", "expires_in": 3600 }

OAuth 2.0 general description

OAuth is an open standard for authorisation which is used by i.e. Google, Facebook, Microsoft, Twitter etc. to let their users exchange information about their accounts with other applications or websites. OAuth is designed to work with HTTP.

Through OAuth users can authorise third party applications or websites to access their account information on other "master" systems without the need of exchanging with them their credentials to login onto the platform. OAuth provides a "secure delegated access" to resources (email accounts, pictures accounts, etc.) on behalf of the resource owner.

It specifies a method for resource owners to authorise third parties access to their resources without exchanging their credentials (username, password). Authorisation servers (of the platform) issue access tokens to third party clients (applications or websites) with the approval of the resource owner (= end user). The third party client needs the access token to get access to the resources that are stored on the resource server (of the master system).