Authorisation

1. Purpose

The authorisation endpoint is the only endpoint where the end-user needs to interact, through their web browser, with the OAuth 2.0 / OpenID Connect server. The endpoint serves two purposes:

Establishes the identity of the end-user. This can be done by means of a username / password login, session cookie, some other authentication method, or a combination thereof.
Grants or denies the requested authorisation, by asking for the end-user’s consent or by executing some business logic where the end-user’s input is not required.

OAuth and OpenID Connect server implementers are free to decide how the actual authentication and authorisation should happen. Connect2id takes advantage of this and provides a powerful integration API for enterprises to plug in any authentication methods and authorisation logic, and devise their own branded UX.

2. The authorisation endpoint URL

The authorisation endpoint URL can be obtained from the server discovery endpoint and may look like this:

https://[base-server-url]/login

3. Clients must be registered

Client applications must be registered with the Connect2id server for one or both of the following OAuth 2.0 grants before they can make requests to the authorisation endpoint:

For more information:

4. Authentication request

In order to authenticate an end-user and / or obtain an access token the client needs to make a request to the authorisation endpoint.

4.1 Constructing the request

The request is formed by taking the authorisation endpoint URL and appending the required parameters to it as query parameters:

[authorization-endpoint]?param-1=value&param-2=value&param-3=value&...

For example:

https://c2id.com/login?
 response_type=code
 &scope=openid%20email
 &client_id=123
 &state=af0ifjsldkj
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

The client application typically renders a “Login” link or button with the constructed URL, or sets the JavaScript window.location property. Both methods should have the effect of directing the browser to the authorisation endpoint of the Connect2id server with the URL-encoded parameters.

4.2 Request parameters

The authentication request parameters are described in the following documents:

For clients that wish to use the OAuth code flow (most clients) – see section 2.1.1 of OpenID Connect basic client 1.0.
For clients that wish to use the OAuth implicit flow (JavaScript-based clients) – see section 2.1.1 of OpenID Connect implicit client 1.0.
For hybrid clients – see section 3.3 of OpenID Connect Core 1.0.

The OpenID Connect Core 1.0 document contains the complete specification and can also be used as a reference.

Summary of the minimal required request parameters:

response_type The OAuth 2.0 response type. For clients using the OAuth code flow it should be set to code. For clients using the implicit flow it should be set to id_token or token id_token.
client_id The OAuth 2.0 client identifier, obtained at registration.
scope Space separated list of the requested scope values. Must include at least the openid value.
redirect_uri The redirection URI to which the response will be sent. It must exactly match one of the registered redirection URIs for the client.
[ state ] Opaque value, e.g. a random string, used to maintain state between the request and the callback. Use of this parameter is not required but highly recommended.
[ nonce ] Opaque value, e.g. a random string, used to associate a client session with an ID Token, and to mitigate replay attacks. Use of this parameter is required in the implicit flow.

The Connect2id server also supports the following request parameters for Proof Key of Code Exchange (PKCE) in order to guard against code interception attacks on public OAuth clients:

[ code_challenge ] The code challenge, computed from the code verifier using a transform.
[ code_challenge_method ] The code transform, defaults to plain if not specified. The supported methods are S256 (recommended) and plain.

5. Authentication response

The Connect2id server will send the authentication response to the callback URI specified in the redirect_uri parameter.

If the Connect2id server finds the client_id or redirect_uri to be invalid, the browser will not be redirected back to the client.

5.1 Success

Upon successful end-user authentication and authorisation the Connect2id server will return the response parameters appended to the redirect_uri.

5.1.1 OAuth code flow

For clients using the OAuth code flow (determined by the response_type) the server will return the parameters specified in section 2.1.5.1 of OpenID Connect basic client 1.0. These will be encoded in the URL query string.

Parameters:

code The OAuth 2.0 authorisation code. Required to obtain the ID token and token from the token endpoint.
[ state ] The state value, if one was passed with the request. Clients must validate the value before proceeding.

Example:

https://client.example.org/cb?
 code=SplxlOBeZQQYbYS6WxSbIA
 &state=af0ifjsldkj

5.1.2 OAuth implicit flow

For clients using the OAuth implicit flow the the server will return the parameters specified in section 2.1.5.1 of OpenID Connect implicit client 1.0. These will be encoded in the URI fragment.

Parameters:

access_token The OAuth 2.0 access token. Required for the UserInfo endpoint and other authorised protected resources.
token_type=bearer The OAuth 2.0 token type, set to bearer.
[ expires_in ] Expiration time of the access token in seconds since the response was generated.
id_token The OpenID Connect ID token.
[ state ] The state value, if one was passed with the request. Clients must validate the value before proceeding.

Example:

https://client.example.org/cb#
 access_token=SlAV32hkKG
 &token_type=bearer
 &expires_in=3600
 &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
 &state=af0ifjsldkj

5.1.3 OAuth hybrid flow

For clients using the OAuth hybrid flow (a combination of code and implicit, which is rarely used) the the server will return the parameters specified in section 3.3.2.5 of OpenID Connect Core 1.0. These will be encoded in the URI fragment.

Parameters:

access_token The OAuth 2.0 access token. Required for the UserInfo endpoint and other authorised protected resources.
token_type=bearer The OAuth 2.0 token type, set to bearer.
[ expires_in ] Expiration time of the access token in seconds since the response was generated.
id_token The OpenID Connect ID token.
code The OAuth 2.0 authorisation code. Required to obtain the ID token and token from the token endpoint.
[ state ] The state value, if one was passed with the request. Clients must validate the value before proceeding.

Example:

https://client.example.org/cb#
 code=SplxlOBeZQQYbYS6WxSbIA
 &access_token=SlAV32hkKG
 &token_type=bearer
 &expires_in=3600
 &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
 &state=af0ifjsldkj

5.2 Error

If the end-user denies the login request or if the request fails for reasons other than an invalid client_id or redirect_uri, the Connect2id server will inform the client by appending the following parameters (to the query string in the OAuth code flow, or the fragment in the implicit and hybrid flows) to the redirection URI:

error The OAuth 2.0 error code, with values (additional codes are specified in OpenID Connect):
- invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
- unauthorized_client The client is not registered for the requested response_type.
- access_denied The end-user or the server denied the request.
- unsupported_response_type The server doesn’t support the requested response_type.
- invalid_scope The requested scope is invalid, unknown, or malformed.
- server_error The server encountered an unexpected internal error.
- temporarily_unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance.
[ error_description ] Optional parameter providing additional human-readable information about the error.
[ error_uri ] A human-readable web page with information about the error, typically intended for the client developer.
[ state ] The state value, if one was passed with the request. Clients must validate the value before proceeding.

Example error response:

https://client.example.org/cb?
 error=invalid_request
 &error_description=Unsupported%20response_type%20value
 &state=af0ifjsldkj