Loading

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

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/*.conf in.mc2 out.json

/path/to/*.conf is the path to Warp 10™ configuration:

  • multiple configuration files for Warp 10™ in release 2.1.0+, for example /opt/warp10/etc/conf.d/*.conf.
  • single configuration file for Warp 10 before 2.1, for example /opt/warp10/etc/conf-standalone.conf.

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/etc/conf.d/* - -

Token generation is idempotent, an identical input 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, and fixed UUID for owner and producers. Therefore re-running TokenGen on one of those files will regenerate an exactly identical token and token ident.

Example

This WarpScript will generate a read and a write token for an application named kronos, with a generated UUID for owner and producer, valid until year 2101:

'kronos' 'applicationName' STORE
'2101-10-01T00:00:00.000000Z' TOTIMESTAMP 'expirydate' STORE

UUID 'owner' STORE

{
  'READ'
  {
    'id' 'tokenR'  // for bookkeeping purposes
    'type' 'READ'       // or 'WRITE'
    'application' $applicationName // Name of applications for this token
    'owner'  $owner     // UUID of the data owner for WRITE tokens or the billed user for READ tokens
    'issuance' NOW      // Time of token issuance
    'expiry' $expirydate // Time of token expiry
    'labels' {}         // Map of token labels
    'attributes' {}     // Map of token attributes
    // The following are only for READ tokens, can be omitted, the token is then considered a WildCard token.
    'owners' [  $owner ]
    'producers' [ $owner ]
    'applications' [ $applicationName ]  
  } TOKENGEN

  'WRITE'
  {
    'id' 'tokenW'  // for bookkeeping purposes
    'type' 'WRITE'       // or 'WRITE'
    'application' $applicationName // Name of applications for this token
    'owner'  $owner     // UUID of the data owner for WRITE tokens or the billed user for READ tokens
    'producer' $owner  //owner = producer to be able to delete data.
    'issuance' NOW      // Time of token issuance
    'expiry' $expirydate // Time of token expiry
    'labels' {}         // Map of token labels
    'attributes' {}     // Map of token attributes
  } TOKENGEN
}

Store it in kronosTokenGeneration.mc2, then call it:

java -cp /opt/warp10/bin/warp10-2.3.0.jar io.warp10.worf.TokenGen /opt/warp10/etc/conf.d/* kronosTokenGeneration.mc2 /tmp/tokenraw.json

The output is a json that can easily be used by another application or a script:

[
  {
    "READ": {
      "ident": "7f395eaf0107e53f", // TokenIdent, for use in Token Revocation List
      "id": "tokenR", // Value of the ‘id’ field from the TOKENGEN parameter map
      "token": "sfH97318z5c0....."
    },
    "WRITE": {
      "ident": "d258836b124221ee", // TokenIdent, for use in Token Revocation List
      "id": "tokenW", // Value of the ‘id’ field from the TOKENGEN parameter map
      "token": "44c58W72QD......."
    }
  }
]

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.

Example

This WarpScript will create a read token from an existing write token.

// write token
"FcEJbLXRNLX3_xTYl6ncIgLNc5oQEMCYiDzGT2xA7yBrIBx71gMRu0Et552hrVl04bwEHMOJgF3DRERnvhyTDHSI8mjhmBaGiO8yGS5Zl_3JSJs18ds02." 
'wt' STORE

$wt TOKENDUMP 'tokeninfo' STORE

// change the output of TOKENDUMP to add applications, owners, producers
$tokeninfo 'params' GET 'READ' 'type' PUT DROP 
$tokeninfo 'params' GET [ $tokeninfo 'params' GET 'application' GET  ] 'applications' PUT DROP
$tokeninfo 'params' GET [ $tokeninfo 'params' GET 'owner' GET  ] 'owners' PUT DROP 
$tokeninfo 'params' GET [ $tokeninfo 'params' GET 'producer' GET  ] 'producers' PUT DROP

// create the matching read token
$tokeninfo 'params' GET TOKENGEN