1. Token concepts
  2. Generating tokens using TOKENGEN
  3. Inspecting tokens using TOKENDUMP

Token Management

Warp 10™ entry points are based on bearer token authentication. Tokens are protected by a cryptographic envelope which ensures their integrity and authenticity. They are never stored in the Warp 10™ instance.

Tokens are created using the TOKENGEN function and their internals can be viewed using TOKENDUMP.

Token concepts

Token type

There are two basic types of tokens, write tokens for pushing data and read tokens for reading data.

Application name

Applications provide a logical isolation of your data.

Producer

The producer has the responsibility of writing data on the platform for an application. Generally it is the application manager.

Each producer is identified by a UUID.

Owner

The owner owns the data. This concept is useful for building data privacy systems and enabling third party applications to access data.

In many cases, owner and producer are identical.

Each owner is identified by a UUID.

TTL (time to live) or expiry timestamp

Every token has an expiration date after which it is no longer valid. This allows to create short-lived tokens for performing specific manipulations, or also long-lived tokens to embed into devices.

Generating tokens using TOKENGEN

Since Warp 10™ 1.2.20, a new TokenGen command exists which uses the WarpScript™ TOKENGEN function from io.warp10.script.ext.token.TokenWarpScriptExtension.

If no token.secret is defined in the configuration, the TOKENGEN function only useable via the TokenGen command.

The TOKENGEN function expects a map as input.

The TokenGen command will execute WarpScript™ code from in.mc2 and output the stack as JSON to out.json:

$ java -cp warp-full-<revision name>.jar io.warp10.worf.TokenGen /path/to/secret.conf in.mc2 out.json

secret.conf is either the Warp 10™ configuration file or the secrets configuration file for Warp 10™ in release 2.1.0+.

Example of in.mc2

{
  'id' 'nameoftoken'  // for bookkeeping purposes
  'type' 'READ'       // or 'WRITE'
  'application' 'app' // Name of applications for this token
  'owner' 'UUID'      // UUID of the data owner for WRITE tokens or the billed user for READ tokens
  'issuance' NOW 1 ms /    // Time of token issuance (in milliseconds since the Unix Epoch)
  'expiry' NOW 30 d + 1 ms / // Time of token expiry (in milliseconds since the Unix Epoch)
  'ttl' 300 d 1 ms /        // Time To Live of the token, use if not using 'expiry' (in milliseconds)
  'labels' {}         // Map of token labels
  'attributes' {}     // Map of token attributes
  // The following are only for READ tokens.
  // If omitted, the token is then considered a WildCard token.
  'owners' [ /* List of UUIDs */ ]
  'producers' [ /* List of UUIDs */ ]
  'applications' [ /* List of application names or regexps (if more than one) */ ]
} TOKENGEN

Example of out.json

{
  "id" : "nameoftoken",   // Value of the ‘id’ field from the TOKENGEN parameter map
  "token" : "..." ,       // Encoded token
  "ident" : "hhhhhhhhhhhhhhhh" // TokenIdent, for use in Token Revocation List
}

TokenGen can use - to specify stdin / stdout as input/output

$ cat in.mc2 | java -cp warp-full-<revision name>.jar io.warp10.worf.TokenGen /path/to/warp10.conf - -

Token generation is idempotent, an identical inut map will always produce the same token.

As a result, if you wish to be able to revoke a token easily we strongly advise that you keep track of the .mc2 files which you used for generating the tokens but use explicit timestamps for the issuance and expiry fields. Therefore re-running TokenGen on one of those files will regenerate an exactly identical token and token ident.

Inspecting tokens using TOKENDUMP

The TOKENDUMP function allows you to view the content of an existing token. The function will produce an output map with the following elements:

{
  "ident": "hhhhhh" // TokenIdent of the token, for use in Token Revocation Lists
  "token": "...."   // The original token passed as parameter
  "params": { .... } // A map in the same format as the input map of TOKENGEN
}

The map in the params field can be used as is as input for TOKENGEN.

The input .mc2 file for TokenGen can contain calls to TOKENDUMP.