Authorize
Last updated
Last updated
sub
String.
This parameter overrides iSHARE compliant JWT payload. A URN specifying subject for this authorization request. Since ID or pseudonym of the user is not known upfront, 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.
OAuth 2.0 Response Type. In order to use the Authorization Code Flow in iSHARE, value code is REQUIRED. MUST be identical to the response_type value in the body parameter of the /authorize request.
client_id
String.
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 /authorize request.
scope
String.
OAuth 2.0 scope for OpenID Connect 1.0. The scope parameter MUST contain at last the openid and the iSHARE scope values. In addition to that it and 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 /authorize request. MUST be identical to the scope value in the body parameter of the /authorize 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_uri’s 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 IdP /authorize 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 IdP /token endpoint response.
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 login page according to provided language, else should display default page.
Example
Level of Assurance
Authentication assurance
Low
Single factor, e.g. username and password
Substantial
Multi-factor, e.g. mobile phone + PIN
High
Multi-factor, e.g. mobile phone + PIN
Must access private data/keys stored on tamper-resistant hardware token
Cryptographic protection of personally identifying information (PII)
Tip
(URL encoding removed, and line breaks added for readability)
Warning
Authorize callback endpoint usually requires the same parameters that were sent towards authorize endpoint in order to identify which request was that. Signed and encrypted JWT is too long and MUST NOT be included into returnUrl.
(URL encoding removed, and line break added for readability)
On successful callback Identity Provider should redirect user to URI which was provided in a request JWT payload redirect_uri parameter with added query parameters that are defined in a section below.
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.
(Line breaks added for readability)
This parameter is an , with additional parameters within this token. The request JWT contains the modified sub parameter and the following additional parameters:
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 .
request parameter is encrypted, so you won’t be able to inspect its payload. However, if you’d like to see JWT payload please refer to the .
When a valid request is sent a redirection should happen to to allow user to authenticate himself.
When invalid request is sent a redirection should happen to Identity Provider’s error page. Redirection should not be made to URI which was provided in a request JWT payload redirect_uri parameter due to potential security risks. To learn more please read .
returnUrl
On successful request a redirection to login should happen. Once user has logged in, endpoint needs to be done in order to issue a code to Service Provider. This parameter value should be an encoded URL to the callback endpoint.
On successful login callback towards authorize endpoint is invoked. It’s out of iSHARE’s scope to document Identity Provider’s internal functionality. However there still are a few requirements because expects a specific call.
code
Authorization code which is going to be used to request for an . The authorization code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes is RECOMMENDED. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI.
OpenID Connect endpoint for redirecting Human Service Consumer for authentication by the Identity Provider. Server response is directed to the /service_provider/openid_connect1.0/return endpoint.
Defines request body content type. MUST be equal to application/x-www-form-urlencoded.
x-www-form-urlencodedOAuth 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.
response_typeOAuth 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.
scopeOpenID 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.
client_idOpenID 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.
requestOK