YouTrack Standalone 2017.2 Help

Implicit

Reference to the Standard

Implicit Grant Flow Specification

Prerequisites

Client is public. Typically, a JavaScript code in a browser.

  1. Client service ID — an id of the YouTrack service registered in the built-in Hub service. To get the service ID of YouTrack, open the Administration menu > Hub Integration page, and copy the YouTrack Service ID:

    oauthYTServiceId

  2. Scope — the ID of the YouTrack service. As the scope you can use the symbolic name of the YouTrack service in the built-in Hub: "YouTrack".

  3. Client redirect URI — an URI at the client application that can handle response from Hub.

  4. Hub URL — an URL of the built-in Hub service.

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

  6. Request credentials mode — parameter that controls if the login form should be shown to a user. The following values are valid:
    • skip — use this option, if the client service generally allows anonymous access. It works as following:
      • If a user is already logged in to Hub, then authorize the user to the client service.

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

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

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

    • required — logs out a 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 a user is already logged in to Hub, then authorize the user to the client service,

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

Sending User to Authorization Server (Hub)

To start authentication code should redirect browser to:

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

Example:

https://hub.company.com/api/rest/oauth2/auth?response_type=token&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

Handling Authorization Server (Hub) Response

Client service should be able to handle responses from Hub at the URL passed as redirect_uri. Response parameters are passed after a hash sign in the URL. Thus these parameters are not sent to the server and cannot be intercepted by a malefactor.

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

access_token
The access token issued by the authorization server.
token_type

The type of the token issued by Hub. Value is case insensitive.

expires_in
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
Optional, if identical to the scope requested by the client; otherwise, required. The scope of the access token in Hub is the service_id.
state
Required if the "state" parameter was present in the client authorization request. The exact value received from the client.

The authorization server (Hub) will not issue a refresh token.

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

HTTP/1.1 302 Found Location: http://myservice.company.com/authorized#access_token=1443459450185.0-0-0-0-0.98071167-004c-4ddf-ba37-5d4599fdf319.0-0-0-0-0%3B1.MCwCFC%2FYWvLjHdzOdpLleDLITJn4Mz9rAhRklCoZ2dlMkh2aCd1K5QQ89ibsxg%3D%3D&token_type=Bearer&expires_in=3600&scope=0-0-0-0-0%2098071167-004c-4ddf-ba37-5d4599fdf319&state=9b8fdea0-fc3a-410c-9577-5dee1ae028da

Handling Error Redirect Back from Hub

If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the Hub server will inform the resource owner of the error and will not automatically redirect the user-agent to the invalid redirection URI.

If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the client by adding the following parameters to the fragment 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.

For example, Hub redirects the user-agent by sending the following HTTP response:

HTTP/1.1 302 Found Location: https://myservice.company.com/cb#error=access_denied&state=xyz
Last modified: 7 March 2019