Authorization Code - Help

Reference to the Standard

See Authorization code flow specification for more info.

Prerequisites

Client is a web application.

A web application is a confidential client running on a web server. Resource owners access the client via an HTML user interface rendered in a user-agent on the device used by the resource owner. The client credentials as well as any access token issued to the client are stored on the web server and are not exposed to or accessible by the resource owner.

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.

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 asskip, 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:

            ${Hub Service URL}/api/rest/oauth2/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}&access_type={online|offline}
        

.

Example:

            https://hub.company.com/api/rest/oauth2/auth?response_type=code&state=9b8fdea0-fc3a-410c-9577-5dee1ae028da&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized&request_credentials=skip&client_id=98071167-004c-4ddf-ba37-5d4599fdf319&scope=0-0-0-0-0%2098071167-004c-4ddf-ba37-5d4599fdf319
        

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

            ${Hub Service URL}/api/rest/oauth2/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}&access_type=offline
        

.

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:

            HTTP/1.1 302 Found
            Location: https://myservice.company.com/authorized?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
        

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:

            POST /api/rest/oauth2/token
            Host: ${Hub Service URL}
            Accept: application/json
            Authorization: Basic ${base64(${Client service ID} + ":" + ${Client service secret})}
            Content-Type: application/x-www-form-urlencoded

            grant_type=authorization_code&code=${Code received on a previous step}&redirect_uri=${Client redirect URI}
        

Example:

            POST /api/rest/oauth2/token
            Host: hub.company.com
            Accept: application/json
            Authorization: Basic OTgwNzExNjctMDA0Yy00ZGRmLWJhMzctNWQ0NTk5ZmRmMzE5OmVBVXlLZ1ZmaFNiVg0K
            Content-Type: application/x-www-form-urlencoded

            grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized
        

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:

            HTTP/1.1 200 OK
            Content-Type: application/json;charset=UTF-8

            {
            "access_token":"1443459450185.0-0-0-0-0.98071167-004c-4ddf-ba37-5d4599fdf319.0-0-0-0-0%3B1.MCwCFC%2FYWvLjHdzOdpLleDLITJn4Mz9rAhRklCoZ2dlMkh2aCd1K5QQ89ibsxg%3D%3D
            "expires_in":3600,
            }
        