Skip to content
Connect2id

Authorisation

1. Purpose

The OAuth 2.0 authorisation endpoint is where client applications send the end-user to:

  1. Get authenticated. This can be done by means of one or more credentials / factors, a session cookie, or a federated identity provider, such as a social login.

  2. Allow (or deny) issue of an access token with a certain scope and / or ID token. The user consent may be explicit (form) or implied (rule or policy).

The underlying end-user authentication and consent is handled by the Connect2id server authorisation session API to enable plugin of factors, logic and a UI tailored to the identity provider.

2. The authorisation endpoint URL

It is advertised in the authorization_endpoint 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:

OpenID Connect Federation 1.0 relying parties that use automatic registration can call the authorisation endpoint without a prior registration step.

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 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 request parameters encoded in the URL.

5.2 Request parameters

5.2.1 OpenID Connect

The OpenID authentication request parameters are specified 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 must be set to code. For clients using the implicit flow it must be set to id_token or token id_token. For clients using the hybrid flow set to code id_token or code id_token token.

  • client_id The OAuth 2.0 client identifier, obtained at registration. OpenID Connect Federation 1.0 relying parties using automatic registration must set it to their entity identifier URL.

  • 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, unless the client is a native application allowed to use a variable localhost port.

  • [ 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 Recommended 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 raise 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) (RFC 9101), 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 identifier.

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

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

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.

5.2.7 Optional prompt

This optional parameter lets the client control what prompts the end-user is presented with at the authorisation endpoint:

  • [ prompt ] Space delimited set of one or more values:

    • none Used to check if the end-user is currently authenticated with the Connect2id server and has existing consent for the requested scope. If these conditions are satisfied the Connect2id server will proceed directly to the client redirect_uri, without interaction with the end-user.

      A prompt=none in the authorisation request is typically used to silently refresh the current end-user session with the Connect2id server and obtain a new set of tokens (access and / or ID token, with optional refresh token).

      If the end-user has no active session the authorisation endpoint will return a login_required or interaction_required error, to indicate the request should be repeated in a regular manner.

      If the end-user has no existing consent the authorisation endpoint will return a consent_required or interaction_required error, to indicate the request should be repeated in a regular manner.

      If the end-user has no active session the authorisation endpoint will return a login_required error, to indicate the request should be repeated in a regular manner.

      Prompt none requires the client to include an ID token hint (id_token_hint) parameter, unless configured otherwise.

      The prompt none value must be used alone, i.e. not mixed with other prompt values.

    • login Will prompt the end-user to (re)authenticate, even if they have an existing session.

    • consent Will prompt the end-user to (re)consent, even if they have existing consent on record for the requested scope.

    • select_account Will present the end-user with an account selection dialog (if supported).

    • create A hint to present the end-user with a sign-up form.

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 RFC 9207.

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