Using the Embedded Web Browser Authorization Flow

From TeamServer ER/Studio
Jump to: navigation, search

Go Up to Obtaining Authorization to Use the API

The Embedded Web Browser Authorization Flow allows client applications to have an embedded web browser control (web view).

This authorization flow consists of the following steps:

  1. Obtain an authorization code:
    1. Your client application opens ER/Studio Team Server in an embedded web browser, using an URL with a set of query parameters that indicate the type of access that your client application requires, as well as a callback URL.
    2. ER/Studio Team Server handles the user authentication and consent. If the user agrees, ER/Studio Team Server performs a request against the callback URL that your client application provided as a query parameter in the URL (in the previous step). This request includes a query parameter with an authorization code.
  2. Exchange the authorization code for an access token:
    1. Your client application, after it receives the authorization code, performs a request against ER/Studio Team Server, providing the authorization code.
    2. ER/Studio Team Server responds with an access token.

You obtain a refresh token as well as an access token. You can use that refresh token to obtain a new access token when your current access token expires.

Obtaining an Authorization Code

You application must open in an embedded web browser an URL that points to the target ER/Studio Team Server installation. In this URL, you must include query parameters indicating the type of API access that your client application requires. ER/Studio Team Server authenticates the user, informs the user of the access request, and allows the user to choose whether to grant or not your client application the requested access permissions.

The URL that you must open is http://teamserver.example.com/api/oauth/authorize . You must append the following query parameters to this URL:

Item Example Description

response_type

code

The type of response that ER/Studio Team Server must return in the request to your callback URL.

Provide the value code here to request that ER/Studio Team Server returns an authorization code in the request to your callback URL.

client_id

6a2a39ba-9688-493d-b348-187468f599ae

The ID of your client application, as registered in the target ER/Studio Team Server installation.

redirect_uri

http://myapp.example.com/oauthcallback

The callback URL of your client application. The value of this parameter must exactly match one of the values used when registering the app. You may also choose urn:ietf:wg:oauth:2.0:oob or an http://localhost port. This will determine how the authorization code is returned to you.

scope
(optional)

read+write

Space-delimited list of access scopes. Possible values are:

  • read
  • write
  • read+write

The default value is read+write .

state
(optional)

Custom string

Custom string that you want your client application to receive in the request to your callback URL.

You may use this parameter for anything you want. For example, you can use it to redirect users to the correct resource in your site.

The following is an example URL:

http://teamserver.example.com/api/oauth/authorize?response_type=code&client_id=6a2a39ba-9688-493d-b348-187468f599ae&redirect_uri=http://myapp.example.com/oauthcallback

After your user logs into ER/Studio Team Server and grants your client application access to the API, ER/Studio Team Server redirects the embedded web browser to your callback URL, providing a code query parameter. For example:

http://myapp.example.com/oauthcallback?code=6U4MUI

Store that code.

Exchanging an Authorization Code for an Access Token

Once you have an authorization code, you must perform a request against http://teamserver.example.com/api/oauth/token . You must append the following query parameters to this URL:

Item Example Description

code

6fGVc2

The authorization code that your client application previously obtains.

client_id

6a2a39ba-9688-493d-b348-187468f599ae

The ID of your client application, as registered in the target ER/Studio Team Server installation.

client_secret

a28e0ca4-27cb-4361-bf97-3b26c612d66a

The secret of your client application, as registered in the target ER/Studio Team Server installation.

grant_type

authorization_code

The type of your access token request.

Provide the value authorization_code here, as your request to ER/Studio Team Server is for an access token in exchange for your authorization code.

redirect_uri

http://myapp.example.com/oauthcallback

The callback URL of your client application.

The following is an example URL:

http://teamserver.example.com/api/oauth/token?code=6fGVc2&client_id=6a2a39ba-9688-493d-b348-187468f599ae&client_secret=a28e0ca4-27cb-4361-bf97-3b26c612d66a&grant_type=authorization_code&redirect_uri=http://myapp.example.com/oauthcallback

ER/Studio Team Server responds in JSON format. The server response includes the following information:

{
    // Token to include in every API request to get access.
    "access_token": "d4ac0c07-0013-4939-b9ee-0112fdbb7d64",
    
    // Type of token. This is always "bearer".
    "token_type": "bearer",
    
    // Token that you can use to get a brand-new access token without further user interaction.
    "refresh_token": "bcd5a78c-9f0a-4ba6-9baa-5872e5acf7bb",
    
    // Number of seconds before the access token expires. Default value is 86400 (7 days).
    "expires_in": 86399,
    
    // Granted scope.
    "scope": "read write"
}

You can now start using the ER/Studio Team Server API, including the provided access token in every API request.

See Also