OAuth2 Authentication¶

1. Redirecting users to the authorization URL¶

To start, create a “Log In” link which redirects the user to the following URL on your Review Board server:

https://reviewboard.example.com/oauth2/authorize/?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}

There are several values to fill in in the query string for this URL:

• client_id is the Client ID from your registered application.
• redirect_uri is the URI you want the user to be redirected to after a successful authentication. This must be listed in the Redirect URIs field of your registered application.
• scope is an optional, space-delimited list of scopes that your application is requesting access to. If omitted, the application will request access to the entire Review Board API.
• state is an optional value which your application can use to verify consistency between the request and the callback at the redirect URI.

When this URL is loaded by the client’s browser, the user will be asked to log in (if needed), and then asked if they want to authorize the application. Upon doing so, they’ll be redirect back to your specified redirect URI.

2. Getting the authorization callback¶

Once the user authorizes your application, they will be redirected back to your application’s redirect URI. For example, if you had set the redirect URI as https://myapp.example.com/oauth2/cb, the user would be redirected to:

https://myapp.example.com/oauth2/cb?code={authorization code}

The authorization code is a 30-character string which will be used to get an access token.

3. Getting an access token¶

The access token is what is actually used to authenticate to Review Board. Once you have an authorization code, it can be used to request an access token. This is done via a POST operation to the token URL:

POST https://reviewboard.example.com/oauth2/token/

This POST should include the authorization code returned in step 2 and the grant type in the body:

code={authorization code}&grant_type=authorization_code&

This will return a JSON blob containing the access token, the expiration of that access token, and a refresh token:

{
    "access_token": "sometoken",
    "refresh_token": "new authorization code for refreshing",
    "expires_in": 3600,
    "scope": "...",
    "token_type": "Bearer"
}

4. Making use of the Review Board API¶

Once you have an access token, you can use it to authenticate to the Web API by passing it in the HTTP Authorization header.

5. Refresh the access token¶

Access tokens have an expiration date. When your access token was first returned, the payload also included a refresh_token field. This can be used with the token endpoint originally used in step 3 to get a new access token.