OAuth 2.0 authorisation endpoint

1. Purpose

The OAuth 2.0 authorisation endpoint is where the end-user is sent to:

  1. 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. 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 let implementers decide how the actual authentication and obtaining of user authorisation get performed. Connect2id takes advantage of this to provide a powerful integration API to plug in the authentication methods and consent logic required by the identity provider and its applications, with a suitable UX.

2. The authorisation endpoint URL

It can be found out from the authorization_endpoint advertised in the Connect2id server metadata 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. Web API overview

Representations

5. Authorisation / authentication request

5.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 window.location in JavaScript. 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.

5.2 Request parameters

5.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, to maintain state between the request and the callback and to prevent CSRF. 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.

5.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.

  • [ state ] Opaque value, to maintain state between the request and the callback and to prevent CSRF. Use of this parameter is not required but highly recommended.

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

5.2.3 Optional PKCE

Proof Key of Code Exchange (PKCE) (RFC 7636) is recommended to be added to the request to prevent code interception attacks on public clients and harden the overall security for confidential clients:

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

Note, the Connect2id server can be configured to require PKCE or allow only a specific transform.

5.2.4 Optional JAR / request object

JWT-secured authorisation requests (JAR) (draft-ietf-oauth-jwsreq-30), also called request objects in OpenID Connect, are supported. The client should 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 is 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.

5.2.5 Optional PAR

The authorisation request parameters can be alternatively submitted directly to the Connect2id server, via a POST backend call to the pushed authorisation request endpoint (PAR), 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.

Note, the Connect2id server may be configured to require PAR for all authorisation requests.

5.2.6 Optional JARM

To receive a JWT-secured authorisation response (JARM) (JARM draft 02) that is signed with the default JWS RS256 algorithm set the response_mode parameter to jwt.

  • response_mode The preferred authorisation response mode, if set to jwt shorthand or the more specific query.jwt, fragment.jwt or form_post.jwt the response parameters will be included in a JWT.

If the client is explicitly registered for a JWS algorithm for JARM all authorisation responses to it will be sent in a JWT, regardless of how the response_mode is set.

6. Authorisation / authentication response

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

All responses will include the iss parameter, set to the issuer URL of the Connect2id server, as specified in draft-ietf-oauth-iss-auth-resp-00.

Note, if the Connect2id server finds the client_id or redirect_uri to be invalid an error will be displayed to the end-user and no response will be sent back to the client.

6.1 Success

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

6.1.1 Code flow

For clients using the code flow (response_type=code) the server will return the following parameters, encoded in the URL query string unless an alternative response mode was chosen.

Parameters:

  • iss The configured issuer URL of the OpenID provider / OAuth 2.0 authorisation server.

  • code The OAuth 2.0 authorisation code. Required to obtain the ID token and / or access token from the token endpoint.

  • [ state ] The echoed 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?
 iss=https%3A%2F%2Fc2id.com
 &code=SplxlOBeZQQYbYS6WxSbIA
 &state=af0ifjsldkj

6.1.2 Implicit flow

For clients using the implicit flow (response_type=token, id_token or token id_token) the the server will return the following parameters, encoded in the URI fragment unless an alternative response mode was chosen.

Parameters:

  • iss The configured issuer URL of the OpenID provider / OAuth 2.0 authorisation server.

  • 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 ID token if OpenID authentication was requested.

  • [ state ] The echoed 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#
 iss=https%3A%2F%2Fc2id.com
 &access_token=SlAV32hkKG
 &token_type=bearer
 &expires_in=3600
 &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
 &state=af0ifjsldkj

6.1.3 Hybrid flow

For clients using the hybrid OpenID Connect flow (a combination of code and implicit, which is rarely used) the server will return the following parameters, encoded in the URI fragment unless an alternative response mode was chosen.

Parameters:

  • iss The configured issuer URL of the OpenID provider / OAuth 2.0 authorisation server.

  • 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 ID token.

  • code The OAuth 2.0 authorisation code. Required to obtain the ID token and token from the token endpoint.

  • [ state ] The echoed 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#
 iss=https%3A%2F%2Fc2id.com
 &code=SplxlOBeZQQYbYS6WxSbIA
 &access_token=SlAV32hkKG
 &token_type=bearer
 &expires_in=3600
 &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
 &state=af0ifjsldkj

6.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 pass the following parameters to the redirect_uri.

For the code flow the parameter will be encoded in the URL query string, for the implicit and hybrid flows in the URL fragment, unless an alternative response mode was chosen.

  • iss The configured issuer URL of the OpenID provider / OAuth 2.0 authorisation server.

  • error The OAuth 2.0 error code (additional codes are specified in OpenID Connect, custom codes may also appear):

    • 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 echoed state value, if one was passed with the request. Clients must validate the value before proceeding.

Example error response:

https://client.example.org/cb?
 iss=https%3A%2F%2Fc2id.com
 &error=invalid_request
 &error_description=Unsupported%20response_type%20value
 &state=af0ifjsldkj

6.3 Alternative response modes

6.3.1 Form post

If the client requested the OAuth 2.0 form post response mode, by setting the response_mode=form_post authorisation request parameter, the response parameters will be POSTed at the client redirect_uri.

Example HTTP POST for an authorisation success:

POST /cb HTTP/1.1
Host: client.example.org
Content-Type: application/x-www-form-urlencoded

iss=https%3A%2F%2Fc2id.com
&code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj

Example HTTP POST for an authorisation error:

POST /cb HTTP/1.1
Host: client.example.org
Content-Type: application/x-www-form-urlencoded

iss=https%3A%2F%2Fc2id.com
&error=invalid_request
&error_description=Unsupported%20response_type%20value
&state=af0ifjsldkj

6.3.2 JARM

If the client requested a JWT-secured authorisation response (JARM), by setting the response_mode=jwt authorisation request parameter, or if the client was registered for JARM, the response parameters will be put into a signed JWT which can additionally be encrypted.

The JWT will be delivered to the redirect_uri in the following parameter, encoded in the URL query string, the URL fragment or POSTed, depending on the flow (response_type) or there being given a more specific response mode, like response_mode=form_post.jwt.

  • response The JWT authorisation response. The JWT will be signed with the RS256 JWS algorithm using an RSA signing key from the Connect2id server JWK set, unless the client was registered for another algorithm. If the client was also registered for a JWE algorithm and method the signed JWT will be additionally encrypted.

    The JWT will contain the following claims which must be validated:

    • iss The configured issuer URL of the OpenID provider / OAuth 2.0 authorisation server.
    • aud Set to the client_id.
    • exp The JWT expiration time.

Example JWT-secured authorisation response encoded to the URL query string:

https://client.example.org/cb?
 response=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FjY291b...