Skip to content

Toro Cloud Dev Center


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 six grant types described in the OAuth 2.0 protocol, Martini supports resource access using password and refresh token grant types.

More information...

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 one 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=TOROMartini&client_secret=TOROMartini'

...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, Martini 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=TOROMartini&client_secret=TOROMartini'

New tokens

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. A custom client can be specified using the application properties oauth.client-id and oauth.client-secret. By default, their values are TOROMartini; hence the value of client_id and client_secret