Client Credentials

Reference to the Standard

Specification for the Client Credentials Flow (RFC6749)

Prerequisites

Client knows its own credentials and accesses resources on behalf of itself.

The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the Hub server.

The client credentials grant type must only be used by confidential clients.

The client must be a trusted service registered in Hub.

Access Token Fetch

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

grant_type: Required. Value must be set to "client_credentials".
scope: Optional. 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.

The request must contain the "Authorization" header in the following format:

Authorization: Basic base64(service_id + “:” + service_secret)

For example, the client makes the following HTTP request using transport-layer security:

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

        grant_type=client_credentials
    

The authorization server must authenticate the client.

Access Token Response

Successful response

If the access token request is valid and authorized, Hub will issue an access token as described below. Please note that a refresh token is not included.

The authorization server issues an access token and optional refresh token, and constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code:

access_token: Required. The access token issued by Hub.
token_type: Required. The type of the token issued. Value is case insensitive.
expires_in: Recommended. The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
scope: Required. A space-separated list of IDs of the services registered in Hub and 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.

The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JavaScript Object Notation (JSON) structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.

Hub includes the HTTP "Cache-Control" response header field with a value of "no-store" in any response containing tokens, credentials, or other sensitive information, as well as the "Pragma" response header field with a value of "no-cache".

An example of successful response:

            HTTP/1.1 200 OK
            Content-Type: application/json;charset=UTF-8
            Cache-Control: no-store
            Pragma: no-cache

            {
            "access_token":"2YotnFZFEjr1zCsicMWpAA",
            "token_type":"example",
            "expires_in":3600,
            "example_parameter":"example_value"
            }
        

Handling Error response

If the request failed client authentication or is invalid, Hub responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the response:

error

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

invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). Hub may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the Hub server will respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.
invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
unauthorized_client - The authenticated client is not authorized to use this authorization grant type.
unsupported_grant_type - The authorization grant type is not supported by Hub.
invalid_scope - The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

error_description

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

error_uri

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

The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.

For example:

            HTTP/1.1 400 Bad Request
            Content-Type: application/json;charset=UTF-8
            Cache-Control: no-store
            Pragma: no-cache

            {
            "error":"invalid_request"
            }
        

Last modified: 17 February 2020