Skip to content
Connect2id

Authorisation

1. Purpose

The OAuth 2.0 authorisation endpoint is where the end-user is sent for two purposes:

  1. To get authenticated. This can be done with a username / password credential, some other authentication method, an existing session cookie, or a federated identity provider, such as a social login.

  2. To allow (or deny) the client application to be issued with an ID and / or access token. The consent can be given explicitly, through a form, or implicitly, by a rule or policy.

OAuth 2.0 and OpenID Connect free implementers 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 the exact authentication methods and authorisation logic their applications require, and devise their own UX around that.

2. The authorisation endpoint URL

The authorisation endpoint URL can be found out from the server metadata endpoint and may look like this:

https://c2id.com/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. Authorisation / authentication request

4.1 Constructing the request

The client constructs the request by taking the authorisation endpoint URL and appending the request parameters to it as a query string:

[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. Regardless of how the action is triggered, it must result in sending the user browser to the authorisation endpoint of the Connect2id server with the URL-encoded parameters.

4.2 Request parameters

4.2.1 OpenID Connect

The OpenID authentication request parameters are described in the following documents:

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

Summary of the minimal required OpenID authentication 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.

4.2.2 OAuth 2.0

Clients that only need an access token can make a plain OAuth 2.0 authorisation request.

Summary of the minimal required OAuth 2.0 authorisation 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 token.

  • client_id The OAuth 2.0 client identifier, obtained at registration.

The default redirect_uri is inferred from the client registration and so can be the default requested scope.

4.2.3 Optional PKCE

Proof Key of Code Exchange (PKCE) can be added to the request to prevent code interception attacks on public clients and improve the overall security for confidential 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.

4.2.4 Optional JAR

JWT-secured authorisation requests (JAR) are supported. The client must be registered for the JWS algorithm intended to secure the JWT and may optionally also be registered for a JWE algorithm to apply encryption over the signed JWT.

To pass a JAR by value:

  • request The request JWT which can be signed or signed-and-encrypted.
  • client_id The client ID.

To pass a JAR by URL reference:

  • request_uri An HTTP(S) URL where the request JWT can be retrieved. The URL must be pre-registered for the client in the request_uris metadata parameter.
  • client_id The client ID.

If the authorisation request includes other unsecured query parameters they will be ignored or merged, according to the configured JAR policies for OAuth 2.0 and OpenID Connect.

4.2.5 Optional PAR

The authorisation request parameters can alternatively be submitted directly to the Pushed Authorisation Request (PAR) endpoint to obtain a request_uri handle to complete the request here.

  • request_uri The request URI returned from the PAR endpoint.
  • client_id The client ID.

If the authorisation request includes other unsecured query parameters they will be ignored or merged, according to the configured JAR policies for OAuth 2.0 and OpenID Connect.

5. Authorisation / authentication response

The Connect2id server will send the 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 / or access token from the token endpoint.

  • [ state ] The state value, if one was passed with the request. Clients must validate the value before proceeding.

  • [ session_state ] Optional parameter if the OpenID Connect check session extension is enabled.

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.

  • [ session_state ] Optional parameter if the OpenID Connect check session extension is enabled.

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.

  • [ session_state ] Optional parameter if the OpenID Connect check session extension is enabled.

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