Warp 10 uses cryptographic tokens to manage authentication and authorization, learn everything about this advanced mechanism in this comprehensive article.
The Warp 10 platform was built with security in mind right from its inception. The original use case the solution was addressing dealt with data from sensors worn by athletes, these data were both sensitive and valuable. Their sensitive nature dictated very strict security mechanisms, and their valuable aspect required flexibility, so third party applications could access those data upon their owner accepting the sharing.
This leads to security being handled by tokens, which are encrypted data structures bearing various pieces of information. There are read and write tokens. This post aims at describing their capabilities.
General concepts
There are three important notions at the core of the token system used in Warp 10, producers, owners and applications. Producers and owners are UUIDs, applications can be any character string.
Producers
The data pushed to a Warp 10 instance is produced by an entity that is identified as the producer of the data. A UUID of a producer is attached to each Geo Time Series as the value of a special label .producer. This label is automatically populated from the information present in the token, and in most situations, it does not appear in the labels of the retrieved data. This means that if two producers (identified by two different tokens) push data to a GTS class{label=value} the data will really end up in two different GTS as the .producer label values will differ.
Owners
The second notion of importance is that of data owner. The owner is the entity on behalf of which a producer pushed some data. An owner UUID is attached to every GTS as the value of the special label .owner. As for the producer, this label is rarely shown and is set automatically based on the information of the token. Data pushed for different owners will end up in different GTS.
Applications
The last important notion related to tokens is that of application. Applications are logical grouping of Geo Time Series belonging to a common context. Each GTS has an associated application, which is specified in the .app label populated from the token information. Contrary to the .producer and .owner labels, the .app label appears in the data retrieved from the Warp 10 data store.
The notion of application is also used for accounting purposes by keeping track of metrics of how data is consumed by each application, a consumer application being the application associated with a read token.
Write Tokens
As their name tells, write tokens are used to write data to a Warp 10 instance. A write token contains a certain number of properties, which are described below
producer
This is the UUID of the producer, which will be added as the value of label .producer of every Geo Time Series updated by the token.
owner
The UUID of the owner, which will be added as the value of label .owner of every GTS updated by the token.
application
The name of the application, which will appear in the .app label of the GTS updated by the token.
issuance and expiry timestamps
These two timestamps (in ms since the Unix Epoch) indicate when the token was issued and until when it is valid. Attempting to use a token past its expiry token will lead to an invalid token error.
labels
This map determines extraneous labels which will be added to the GTS updated with the token. The values present in this map will override any user-specified label. Note that neither .producer, .owner nor .app labels can be set this way.
attributes
Token attributes are special values that are interpreted in a certain way by Warp 10. The attributes element is a map from attribute name to attribute value. Some attributes need only be present regardless of the associated value, some others have a meaning attached to their value.
This is a list of the token attributes supported in version 2.4.0 of Warp 10.
| Attribute name | Token type | Description |
|---|---|---|
.noupdate | WRITE | If present, the token cannot be used for pushing data, i.e. no access to the /update endpoint. |
.nodelete | WRITE | If present, the token cannot be used for deleting data, i.e. no access to the /delete endpoint. |
.nometa | WRITE | If present the token cannot be used for modifying metadata, i.e. no access to the /meta endpoint. |
.maxsize | WRITE | Maximum size (in bytes) of STRING values. For the distributed version of Warp 10, this value cannot be greater than half of the value configured in ingress.kafka.data.maxsize minus 64. |
.maxfuture | WRITE | Maximum time in the future (in ms relative to the current time) that a timestamp for a GTS datapoint can represent. |
.maxpast | WRITE | Maximum time in the past (in ms relative to the current time) that a timestamp for a GTS datapoint can represent. |
.ignoor | WRITE | If set to t or true, any datapoint with a timestamp outside of the window defined by .maxfuture and .maxpast will be silently ignored. |
.ttl | WRITE | For the distributed version of Warp 10, this is the TTL to use for the datapoints (as the ttl of their HBase cells), in milliseconds. Note that you cannot extend the TTL set on the column family. |
.dpts | WRITE | For the distributed version of Warp 10, if this attribute is set to t or true, then the timestamp of the datapoint will be used as the timestamp of the HBase cell (converted to ms, and maxed with 0). |
Read Tokens
The companions to write tokens are naturally read tokens, they have similar properties and some of their own.
owner
This is the UUID of the entity which uses the read token, it is used for some metrics linked to accounting.
application
This is the name of the application using the read token, here again, it is used for some metrics linked to accounting.
issuance and expiry timestamps
Those properties are identical than for the write tokens.
producers
This is a list of producer UUIDs that will be used as selection criteria for the .producer label. If this list is empty, then no criterion will be applied to the .producer label.
owners
This is a list of owner UUIDs that will be used as selection criteria for the .owner label. If this list is empty, then no criterion will be applied.
applications
This is a list of application names which will be used as selection criteria for the .app label. Again, if this list is empty, then no criterion will be applied.
labels
This is an optional map of extra criteria on labels. Each key is a label name, each value is either an exact match (if it starts by = or not by a ~) or a regular expression (if it starts with ~). Those criteria will be enforced when fetching data, regardless of other criteria on the same labels that may have been set.
attributes
This is a set of attributes associated with the token. At the time of writing, no attributes have any meaning for read tokens.
Generating and revoking tokens
Tokens, either read or write, can be generated in several ways, via the command line tool Worf, in WarpScript using TOKENGEN, via the token file or via the GUI available as a commercial add-on to Warp 10.
Once emitted, tokens are normally valid until their expiry timestamp is reached. Nevertheless, it may sometimes be necessary to prematurely expire a token, this can be done via the use of a token revocation list.
Takeaways
As we have seen, the token mechanism used in Warp 10 is a very flexible system for managing authentication and credentials.
Creating tokens is easy and free, so we encourage you to emit as many tokens as you like to fit your needs. It is a good practice to generate a token per application needing to access the data, even if the same set of credentials is already present in a token, this way you will be able to revoke the tokens for each application independently.
For any questions about Tokens (or anything else) feel free to contact our team: contact@senx.io or on Twitter.
Read more
Warp 10 for IoT: GDPR compliant before GDPR even existed
May 2021: Warp 10 releases 2.8.0 and 2.8.1
Warp 10 and the Ethereum blockchain
Co-Founder & Chief Technology Officer