Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

OAuth 2.0

OAuth 2.0 is an authorization protocol that enables applications to acquire limited access for an HTTP resource. This allows a resource owner (user) to share protected content from a resource server without sharing credentials, through various use cases known as Grant Types. Out of the 6 grant types described in the OAuth 2.0 protocol, TORO Integrate supports resource access using password and refresh token grant types.

Info

This document will not discuss the whole protocol in detail. For more information about OAuth 2.0, see oauth.net and RFC 6749.

Acquiring Access Tokens

To gain access to a protected resource, a client needs to validate its identity by acquiring an access token. Access tokens are short-lived tokens - they're valid for at most 1 hour, after which a re-authentication or a refresh is required.

Password

For password based authorization flow, client applications initially makes an access token request using a valid username and password. Assuming you have a user configured, you can initiate1 a request to the token endpoint:

1
2
3
4
5
curl -X POST \
  http://localhost:8080/oauth/token \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=demo&password=s3cr3t&client_id=esb'

...produces:

1
2
3
4
5
6
7
8
9
{
    "access_token": "d07326a0-2b6a-4530-9a60-24cd1e3bff0a",
    "token_type": "bearer",
    "refresh_token": "d9bf6d4b-2fc5-4ec4-a435-c02e82310b73",
    "expires_in": 3589,
    "scope": "read",
    "token_issued_counter": 4,
    "last_token_issued_date": "Monday, March 26, 2018 4:34:52 PM PHT"
}

Refresh Token

To minimize the required username and password request from the client, TORO integrate supports refresh tokens. Refresh tokens live longer than access tokens - at most 12 hours. Like the password grant type, you can initialize a request to the token endpoint to acquire a new access token:

1
2
3
4
5
curl -X POST \
  http://0.0.0.0:8080/oauth/token \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&refresh_token=d9bf6d4b-2fc5-4ec4-a435-c02e82310b73&client_id=esb'

Note

Despite the denotational meaning of refresh, the server actually issues a new access token every time a refresh request is made.

Using either grant type, We can then use the access_token from this response to access otherwise protected resource from the server, by attaching it as Authorization header, prefixed with Bearer:

1
2
3
4
curl -X GET \
  http://localhost:8080/api/some/protected/resource \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer d07326a0-2b6a-4530-9a60-24cd1e3bff0'

  1. As of version 3, TORO Integrate does not yet support registration of custom clients, hence the hard-coded value of client_id to esb