# Authorise

{% hint style="info" %}
The ***This page must be considered part of the iSHARE Framework***

*This page is considered normative and is therefore compliant with RFC 2119.*
{% endhint %}

## Redirect human service consumer for authentication

> OpenID Connect endpoint for redirecting Human Service Consumer for  authentication by the Identity Provider. Server response is directed  to the Service Provider's return endpoint.

```json
{"openapi":"3.0.0","info":{"title":"iSHARE API specifications","version":"3.0"},"tags":[{"name":"Identity Provider (Required)","description":"Required endpoints for the iSHARE Identity Provider API."}],"servers":[{"description":"iSHARE test network base domain","url":"https://isharetest.net"}],"paths":{"/connect/authorize":{"post":{"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"required":["response_type","scope","client_id","request"],"type":"object","properties":{"response_type":{"description":"OAuth 2.0 Response Type. For iSHARE using the Authorization  Code Flow, with value ‘code’ is REQUIRED. MUST be identical  to the response_type value in the request JWT.","type":"string"},"scope":{"description":"OAuth 2.0 scope for OpenID Connect 1.0. MUST contain the  ‘openid’ scope value and one or more scopes identifying the  attributes from the Human Service Consumer that are  requested. Supported scopes under iSHARE are described on  the Technical Agreements page, in the Human2Machine  interaction section. MUST be identical to the scope value  in the request JWT. Scope values determine the permissions  to be asked to the user.","type":"string"},"client_id":{"description":"OpenID Connect 1.0 client ID. Used in iSHARE for all client  identification for OAuth/OpenID Connect. MUST contain a  valid iSHARE identifier. MUST be identical to the client_id  value in the request JWT.","type":"string"},"request":{"description":"OpenID Connect 1.0 signed JWT containing all request  parameters. See also Generic iSHARE JWT specifications for  a.o. basic content and signing requirements. Additionally  JWT MUST be encrypted using JWE as a user can access this  JWT itself and decode the data contained therein.","type":"string"}}}}},"required":true},"tags":["Identity Provider (Required)"],"parameters":[{"$ref":"#/components/parameters/content-type_form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/openid-authorize"}}},"description":"OK"}},"deprecated":false,"operationId":"initiate-authorization-flow","summary":"Redirect human service consumer for authentication","description":"OpenID Connect endpoint for redirecting Human Service Consumer for  authentication by the Identity Provider. Server response is directed  to the Service Provider's return endpoint."}}},"components":{"parameters":{"content-type_form":{"deprecated":false,"name":"Content-Type","description":"Defines request body content type. MUST be equal to application/x-www-form-urlencoded.","schema":{"type":"string"},"in":"header","required":true}},"schemas":{"openid-authorize":{"required":["code","state"],"properties":{"code":{"type":"string"},"state":{"type":"string"}}}}}}
```

{% hint style="info" %}
**Note**

Since the [request object](https://dev.ishare.eu/identity-provider/authorize.html#refauthorizerequestobject) is too large for GET requests, only the POST method should be supported.
{% endhint %}

{% hint style="info" %}
**Note**

According to [RFC 6749](https://tools.ietf.org/html/rfc6749), scopes are case-sensitive.
{% endhint %}

### Request

#### Request Parameter JWT

This parameter is an iSHARE-compliant[ JWT](https://dev.ishare.eu/reference/ishare-jwt), with additional parameters within this token. The `request` JWT contains the modified `sub` parameter and the following additional parameters:

* `sub`\
  **String**.\
  This parameter overrides the iSHARE-compliant JWT payload. A URN specifying the subject for this authorisation request. Since the ID or pseudonym of the user is not known upfront, the *urn: TBD* value should be used (TBD means To Be Determined). In response, a pseudonym of the user MUST be returned by the Identity Provider.
* `response_type`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OAuth 2.0 Response Type. To use the Authorisation Code Flow in iSHARE, a value *code* is REQUIRED. MUST be identical to the response\_type value in the body parameter of the /authorise request.
* `client_id`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OpenID Connect 1.0 client ID. Used in iSHARE for all client identification for OAuth/OpenID Connect. MUST contain a valid iSHARE identifier. MUST be identical to the client\_id value in the body parameter of the /authorise request.
* `scope`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OAuth 2.0 scope for OpenID Connect 1.0. The *scope* parameter MUST contain at least the *openid* and the *iSHARE* scope values. In addition to that, it MAY also contain one or more scopes identifying the attributes from the Human Service Consumer that are requested (depending on the OpenID implementation of the Identity Provider). The *iSHARE* scope contains the minimal information required for authorisations. The *scope* parameter MUST be identical to the scope value in the body parameter of the /authorise request. MUST be identical to the scope value in the body parameter of the /authorise request.
* `redirect_uri`\
  **String**.\
  OpenID Connect 1.0 redirection URI to which the response will be sent. Note that by transporting the redirect\_uri in a signed and encrypted JWT, security considerations regarding un-pre-registered redirect\_uris are properly addressed.
* `state`\
  **String**.\
  OpenID Connect 1.0 opaque value used to maintain state between the request and the callback. The client application needs to verify if the sent value is equal to the value which comes back from the IdP /authorise endpoint response.
* `nonce`\
  **String**.\
  OpenID Connect 1.0 value used to associate a client session with an ID Token. The client application needs to verify if the sent value is equal to the value which comes back from the IdP /token endpoint response.
* `acr_values`\
  **String**.\
  OpenID Connect 1.0 authentication context class reference value. Space-separated string that specifies the ACR values that the Identity Provider is being requested to use for processing this request, with the values appearing in order of preference. 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 authentication requirements for each level of assurance, please look at the [LOA table](#levels-of-assurance).
* `language`\
  **String**. *Optional*.\
  iSHARE specific two-letter indicator (ISO 639-1 Code) that guides the language of the user interface shown by the Identity Broker or Identity Provider. If provided, must display the login page according to the provided language; else should display the default page.

**Example**

```json
{
  "iss": "did:ishare:EU.NL.NTRLNL-10000003",
  "sub": "urn:TBD",
  "aud": "did:ishare:EU.NL.NTRLNL-10000006",
  "jti": "378a47c4-2822-4ca5-a49a-7e5a1cc7ea59",
  "iat": 1504683445,
  "exp": 1504683475,
  "response_type": "code",
  "client_id": "did:ishare:EU.NL.NTRLNL-10000003",
  "scope": "openid ishare name contact_details",
  "redirect_uri": "https://example.client.com/openid_connect1.0/return",
  "state": "af0ifjsldkj",
  "nonce": "c428224ca5a",
  "acr_values": "urn:http://eidas.europa.eu/LoA/NotNotified/high",
  "language": "nl"
}
```

#### **Levels of Assurance**

| **Level of Assurance** | **Authentication assurance**                                                                                                                                                                                         |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Low                    | <ul><li>Single factor, e.g. username and password</li></ul>                                                                                                                                                          |
| Substantial            | <ul><li>Multi-factor, e.g. mobile phone + PIN</li></ul>                                                                                                                                                              |
| High                   | <ul><li>Multi-factor, e.g. mobile phone + PIN</li><li>Must access private data/keys stored on tamper-resistant hardware token</li><li>Cryptographic protection of personally identifying information (PII)</li></ul> |

#### Example

{% hint style="success" %}
**Tip**

`request` The parameter is encrypted, so you won’t be able to inspect its payload. However, if you’d like to see the JWT payload, please refer to the [section](https://dev.ishare.eu/reference/ishare-jwt#jwt-payload).
{% endhint %}

```json
> Content-Type: application/x-www-form-urlencoded

POST /connect/authorise

response_type=code&
client_id=did:ishare:EU.NL.NTRLNL0123456789
scope=iSHARE openid&
request=eyJ0eXAiOiJKV1QiLCJ4NWMiOlsiTUlJRWdUQ0NBbW1nQXdJQkFnSUlOOVZpQ0RpM0J3c3dEUVlKS29aSWh2Y05BUUVMQlFBd1NERVpNQmNHQTFVRUF3d1FhVk5JUVZKRlZHVnpkRU5CWDFSTVV6RU5NQXNHQTFVRUN3d0VWR1Z6ZERFUE1BMEdBMVVFQ2d3R2FWTklRVkpGTVFzd0NRWURWUVFHRXdKT1REQWVGdzB4T1RBeU1UVXhNVFEyTVRWYUZ3MHlNVEF5TVRReE1UUTJNVFZhTUVJeEZUQVRCZ05WQkFNTURFRkNReUJVY25WamEybHVaekVjTUJvR0ExVUVCUk1UUlZVdVJVOVNTUzVPVERBd01EQXdNREF3TVRFTE1Ba0dBMVVFQmhNQ1Rrd3dnZ0VpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDME80aFVoRCtWb09LVklaU05NTlRmemMwTzJrWWorWnpwUUVBQlpHdFB0eTBrS1BKZXAwK281eHN0b3UxSytVeHZIZnhFcEh4SEdUZHRxWnVjMjhMaFU0Q2VDZ29lRE1EVCtDSFMzTm9zaUVTUU13aC9aWmVUYzkvZUtDbzU2OUdDbisyWHRUaUdTcEJTd01TV3FOSGdwQVpZS2RIclQva0VNSXlUS29hdXVpS1E4Y1VwN293N21aei85SytxVjNzOUwwMzBXOElhd0xKQkpLLzJhcEF0NWpoMWo0L21GN2YwcTh6aHpockM4djAxUExsWmR1VHpqakJyZTdteit5aS92bFl6L2VhcDBlWVRqaHhJYXR5VjlGRndsbWk0RkMxQ05jTXRMaDhuc2lKb2U1Y0JtMTNMS2JRRnUzR1lINzZvZUxadldxYlBicDExbXhsSGEvS2RBZ01CQUFHamRUQnpNQXdHQTFVZEV3RUIvd1FDTUFBd0h3WURWUjBqQkJnd0ZvQVVGanpuSU9uV2xPOGY1YUx4dVB5KzZ0OHNONEV3RXdZRFZSMGxCQXd3Q2dZSUt3WUJCUVVIQXdFd0hRWURWUjBPQkJZRUZBUEgrOFVyWWlWTFhhS1BSR2Zsa0ErY3VzUTdNQTRHQTFVZER3RUIvd1FFQXdJRm9EQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FnRUFZbDV0V0gwWXRZUzlKeXF5bFpKV29tQTU1U2hLbGxhQlJjdnJvNkNIeGxsSldIbzBxQzlaVE1jdkN5d012MTRWSnlRZDZlRlpxY1Z0T2x1R3JSWkJrbEg5QWFua292cDJKTGFxY0Q3OXQxQ3l1WFpuSXpURmwvQmtNc0U2d2xBSlhZL3Nhcm5veGVpZWpQNEUvRWYvMGV1SUZ2QmFJQ0NGK0tkMldKWWJibjBXeTBkSDQ4NFFKYkh5TXRWZnI0Mm9JcFVOVnVMU3U4NHlLWUFlbTlKQnVZVHAzWTBLMmhpRUFXL2JPS0R2dkhldFZmNWZ1NjZ5ZmVrRFg1M2ozTktpRkpDWFMycktJWm9EdU1GdXhwU3lWa1Mya2JXazErNUpveTdxT1NOQU5SRlBscEhjZ3pMUVpwOEhyZ3Zoc21oSXQxVlRWWWt5eGNkOHFYQWxod3FWZ09xNU5nTHhrcXVsOWhOTUdpTTdzcStINzNRL0ZpOGlmN2dQOElWQVN6UUd3dUhnMlo4N2liNkEydm9uMGZSSlpxM2ZJdWJIb3hJNjNBVHdmY1JLODZ5MTcyeGJGRTNWVTBkdU4xdEk1WjBUQ2cwR0FKWXRKcGJudmV4SXQ1bGs1RklrNFRodlIwTDhtTkx5MURVYTExTitFTXhrcWJmcWxUdXJCOFpnM0NZL1FhU0ttWFk1Q01Vd1dlRUJYUkhoeWZrWlE1alBQVUhyRmFveU9SWDhwMUVyWURrdEIxSzlvNGptdUVWcEIzM2N2Z1lCRWlBeVY1ejQ0MjZGdVZDTWJIYUZEVjdpS1c5ZUJsWG94ZVpvNFhYOCtqWHlTTDVHVzhYd05SVEs1YzR2VzAyUTNWSnlZVmU1dW1lc3RzS1ErTFI4aUF6b1VTcmVLMTgrSmtBakFKVT0iXX0.eyJpc3MiOiJFVS5FT1JJLk5MMDAwMDAwMDAxIiwic3ViIjoidXJuOlRCRCIsImF1ZCI6IkVVLkVPUkkuTkwwMDAwMDAwMDAiLCJqdGkiOiJicXEwem5rY2RvQ3BjRWdRbXNuUEQyYnh3MWJoa0ZVViIsImlhdCI6MTYwMTM3Mjg2MCwiZXhwIjoxNjAxMzcyODkwLCJyZXNwb25zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6IkVVLkVPUkkuTkwwMDAwMDAwMDEiLCJzY29wZSI6ImlTSEFSRSBvcGVuaWQiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL2V4YW1wbGUuY2xpZW50LmNvbS9vcGVuaWRfY29ubmVjdDEuMC9yZXR1cm4iLCJzdGF0ZSI6IjBGcnF5Mzlja3NmNHZaSFk0RHluRHpYQmtBVmdNbFJ5Iiwibm9uY2UiOiJlYlFqVTc1Vkl4cVczM3RITkZmRmlLbVJHUDZFMlZjNCIsImFjcl92YWx1ZXMiOiJ1cm46aHR0cDovL2VpZGFzLmV1cm9wYS5ldS9Mb0EvTm90Tm90aWZpZWQvbG93IiwibGFuZ3VhZ2UiOiJubCJ9.ZXlKcGMzTWlPaUpGVlM1RlQxSkpMazVNTURBd01EQXdNREF4SWl3aWMzVmlJam9pZFhKdU9sUkNSQ0lzSW1GMVpDSTZJa1ZWTGtWUFVra3VUa3d3TURBd01EQXdNREFpTENKcWRHa2lPaUppY1hFd2VtNXJZMlJ2UTNCalJXZFJiWE51VUVReVluaDNNV0pvYTBaVlZpSXNJbWxoZENJNk1UWXdNVE0zTWpnMk1Dd2laWGh3SWpveE5qQXhNemN5T0Rrd0xDSnlaWE53YjI1elpWOTBlWEJsSWpvaVkyOWtaU0lzSW1Oc2FXVnVkRjlwWkNJNklrVlZMa1ZQVWtrdVRrd3dNREF3TURBd01ERWlMQ0p6WTI5d1pTSTZJbWxUU0VGU1JTQnZjR1Z1YVdRaUxDSnlaV1JwY21WamRGOTFjbWtpT2lKb2RIUndjem92TDJWNFlXMXdiR1V1WTJ4cFpXNTBMbU52YlM5dmNHVnVhV1JmWTI5dWJtVmpkREV1TUM5eVpYUjFjbTRpTENKemRHRjBaU0k2SWpCR2NuRjVNemxqYTNObU5IWmFTRmswUkhsdVJIcFlRbXRCVm1kTmJGSjVJaXdpYm05dVkyVWlPaUpsWWxGcVZUYzFWa2w0Y1Zjek0zUklUa1ptUm1sTGJWSkhVRFpGTWxaak5DSXNJbUZqY2w5MllXeDFaWE1pT2lKMWNtNDZhSFIwY0RvdkwyVnBaR0Z6TG1WMWNtOXdZUzVsZFM5TWIwRXZUbTkwVG05MGFXWnBaV1F2Ykc5M0lpd2liR0Z1WjNWaFoyVWlPaUp1YkNKOQ
```

(URL encoding removed, and line breaks added for readability)

### Response

#### HTTP status codes

#### 302 Found

* When a valid request is sent, a redirection should happen to the [Identity Provider’s login page](https://dev.ishare.eu/identity-provider/login) to allow the user to authenticate themselves.
* When an invalid request is sent, a redirection should happen to the Identity Provider’s error page. Redirection should not be made to a URI which was provided in a request JWT payload redirect\_uri parameter due to potential security risks. To learn more, please read the [OAuth 2.0 Security: OAuth Open Redirector section 2](https://tools.ietf.org/html/draft-bradley-oauth-open-redirector-00#section-2).

#### Parameters

* `returnUrl`\
  On a successful request, a redirection to the login should happen. Once the user has logged in, a [callback to authorise](#callback) endpoint needs to be done in order to issue a *code* to the Service Provider. This parameter value should be an encoded URL to the callback endpoint.

{% hint style="warning" %}
**Warning**

Authorise callback endpoint usually requires the same parameters that were sent towards the authorise endpoint in order to identify which request was. Signed and encrypted JWT is too long and *MUST NOT* be included in `returnUrl`.
{% endhint %}

#### 302 Found Example

```
< Location: https://identity-provider/login?
    returnUrl=https://identity-provider/connect/authorize/callback?authzId=MDK9NtaDCdas75LKQjggWpM8
```

(URL encoding removed, and line break added for readability)

### Callback

On successful login callback towards the authorise endpoint is invoked. It’s out of iSHARE’s scope to document the Identity Provider’s internal functionality. However, there are still a few requirements because the [Service Provider’s return endpoint](https://dev.ishare.eu/service-provider-role/return) expects a specific call.

On successful callback, Identity Provider should redirect the user to the URI which was provided in the request JWT payload redirect\_uri parameter with added query parameters that are defined in a section below.

#### Parameters

* `code`\
  An authorisation code, which is going to be used to request an [access token](https://dev.ishare.eu/identity-provider/access-token). The authorisation code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorisation code lifetime of 10 minutes is RECOMMENDED. The client MUST NOT use the authorisation code more than once. If an authorisation code is used more than once, the authorisation server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorisation code. The authorisation code is bound to the client identifier and redirection URI.
* `state`\
  OpenID Connect 1.0 opaque value used to maintain state between the request and the callback. The client application needs to verify if the sent value is equal to this returned value.

#### 302 Found Example

```json
< Location: https://example.client.com/openid_connect1.0/return?
    code=Dmn-TbSj7OcKl5ym1j5xZsgkabzVP8dMugC81nzmeW4&
    state=ZqVQm4zHaEDyBhzpm1ZRH7fsxy703lq2
```