Authorization Code

Reference to the Standard

See Authorization code flow specification for more info.

See Proof Key for Code Exchange by OAuth Public Clients for more info.

Prerequisites

Client.

The authorization code grant type is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (using redirection) from the authorization server.

Client service_ID

An ID of the service associated with the client in Hub.

Client service_secret

The secret of the service associated with the client in Hub.

scope

A space separated list of IDs of the registered in Hub services associated with the resource servers. For example, if the client wants to access issues in YouTrack it should find out the ID of YouTrack service in Hub. The client can access more then one resource server with a single access token.

redirect_URI of the client

An URI at the client application that can handle response from authorization server.

code_verifier

A high-entropy cryptographic random string that uses the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

The client creates a code verifier for each OAuth 2.0 Authorization Request.

It is recommended that the output of a suitable random number generator be used to create a 32-octet sequence. The octet sequence is then base64url-encoded to produce a 43-octet URL safe string to use as the code verifier. For details, see Section 4.1 of RFS7636.

code_challenge

A code challenge is derived by client from the code verifier using either plain or S256 transformations:

• plain:

  code_challenge = code_verifier

• S256:

  code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

For details, see Section 4.2 of RFS7636.

code_challenge_method

This parameter defines the type of transformation used to create the code_challenge: either plain or S256.

For details, see Section 4.2 of RFS7636.

Hub URL

An URL of Hub server.

State

An identifier of current application state. For example, it can be a key for a local storage object that contains information about current user location in the client service.

request_credentials

A parameter that controls if login form should be shown to a user. Following values are valid:

• skip — use this option, if the client service generally allows anonymous access. It works as following:

  • if the user is already logged in to Hub, then authorize her to the client service,

  • if the user is not logged in to Hub and guest account is not banned, then authorize guest to the client service,

  • if the user is not logged in to Hub and guest account is banned then navigate to login form.

• silent — same as skip, but will return back anyway. If guest account is banned, then this option returns to the client service with an authentication error.

• required — logs out user and shows login form. Use this option as a response to log out in the client service.

• default — use this option if the client service does not allow anonymous access. It works as following:

  • if the user is already logged in to Hub, then authorize her to the client service,

  • if the user is not logged in to Hub, then navigate her to login form.

access_type

Indicates whether the application requires access to Hub when the user is not online. Allowed values: online (used by default) and offline. If the application requires refreshing access tokens when the user is not online, use the offline value. In this case Hub issues a refresh token for the application the first time it exchanges an authorization code for a user. Refer to the Refresh Token page for more information.

Sending User to the Authorization Server (Hub)

To start authentication code should send to browser redirect response to the URL in the following format:

In this request:

• code_challenge - required, when using PKCE extension

• code_challenge_method - optional, defaults to "plain" if not present in the request.

Example:

To instruct Hub to issue the refresh token, add the access_type=offline parameter to your request:

Handling Redirect Back from the Authorization Server (Hub)

If the resource owner grants the access request, the Hub issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:

code

The authorization code generated by the authorization server. The authorization code will expire shortly after it is issued to mitigate the risk of leaks. The client must not use the authorization code more than once. If an authorization code is used more than once, Hub will deny the request. The authorization code is bound to the client identifier and redirection URI.

state

The exact value received from the client in the authorization request.

For example, the authorization server (Hub) redirects the user-agent by sending the following HTTP response:

The client must ignore unrecognized response parameters.

Handling Error Redirect Back from Hub

If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, Hub informs the client by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:

error

A single ASCII [USASCII] error code from the following:

• 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 authorized to request an authorization code using this method.

• access_denied - The resource owner or Hub denied the request.

• unsupported_response_type Hub does not support obtaining an authorization code using this method.

• invalid_scope The requested scope is invalid, unknown, or malformed.

• server_error The Hub server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)

• temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.)

error_description

Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred.

error_uri

A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

state

Required if a "state" parameter was present in the client authorization request. The exact value received from the client.

Exchanging Code for an Access Token

After the client receives the code it can exchange it for an access token.

The client makes a request to the Hub token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

In this request:

• code_verifier - required, when using PKCE extension.

• client_id - required, when using PKCE extension for Public Clients (untrusted services) and when Auth Header is omitted.

Example:

Handling Access Token Response

If the access token request is valid and authorized, Hub issues an access token. If the request client authentication failed or is invalid, the Hub server returns an error response.

Example of a successful response: