OAUTH2 Fantastico Tokens

In Fantastico, authorization codes and access tokens are opaque values for all humans (encrypted). They contain information into them used for easily invalidating them and expiring them. In addition, they do not require a persistent store and allows endpoint authorization without storage calls (increased performance and response time).

Authorization code structure

Authorization codes are opaque values for humans with the following structure (encrypted):

{
   "scopes": ["simple_menus.create", "simple_menus.update", "simple_menus.delete"],
   "userid": 1,
   "state": "unique generated value",
   "creation_time": "1380137542",
   "expiration_time": "1380137651"
}

Each authorization code from Fantastico OAUTH2 implementation contains the following fields:

  1. scopes
    • A JSON list of scopes for which this token was generated. (this will be transmitted to the access token)
  2. user id
    • user unique identifier (possibly email address) which can be used to obtain additional information about the user.
  3. state
    • A key uniquely generated and hard to guess.
    • It is used to protect against Cross Site Request Forgery (CSRF).
  4. creation_time
    • The timestamp when this token was generated.
  5. expiration_time
    • The timestamp when this token expires (must be a really short period - 1min).

Access token structure

{
   "code": "<authorization code used for obtaining the token>",
   "scopes": ["simple_menus.create", "simple_menus.update", "simple_menus.delete"],
   "user": {
      "id": 1,
      "email: "john.doe@gmail.com",
      "first_name": "John",
      "last_name": "Doe"
   },
   "state": "unique generated value",
   "creation_time": "1380137651",
   "expiration_time": "1380163800"
}

Each access token from Fantastico OAUTH2 implementation contains the following fields:

  1. code
    • The authorization code used for obtaining this access token. It only applies for authorization code grant type.
  2. scopes
    • A JSON list of scopes for which this token was generated. (used for endpoint authorization).
  3. user id
    • User unique identifier (used for obtaining additional information about an user).
  4. user email address
    • User email address (as stored in his profile).
  5. user first name
    • Might be used in certain secure components.
  6. user last name
    • Might be used in certain secure components.
  7. state
    • A key uniquely generated and hard to guess.
    • It is used to protect against Cross Site Request Forgery (CSRF).
  8. creation_time
    • A timestamp indicating the date when this token was generated.
  9. expiration_time
    • A timestamp indicating the date when this token is going to expire.

Obtaining access tokens

In order to obtain an access token which can be used for calling Fantastico APIs requires the following:

  1. Obtain an authorization code

    GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2fantasticoproject%2Ecom%2Fcb&scopes=simple_menus.create%20simple_menus.update%20simple_menus.delete HTTP/1.1
    Host: oauth2.fantasticoproject.com
  2. client.fantasticoproject.com/cb?code=<unique one time only code>&state=<unique generated state>

    • Automatically obtain an access token starting from the given autorization code.

      POST /token HTTP/1.1
      Host: client.fantasticoproject.com
      Content-Type: application/json
      
      {
          "grant_type": "authorization_code",
          "code": <unique one time only code>,
          "redirect_uri": "https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb",
          "state": "unique generated value"
      }
      
  3. provide access token for client usage

    {
       "access_token": "<encrypted token containing all specified information",
       "token_type": "bearer",
       "expires_in": 900
    }