Basics

  • Onedata tokens serve as proofs of authorization that can be used across the system.

  • They are crucial for secure interactions within the system.

  • Tokens are only generated in Onezone and can only be verified by Onezone.

  • Tokens are passed around the system in a serialized form — an alphanumeric string.

Implementation

Onedata tokens are based on Google's macaroons and utilize their fundamental concept of caveats — contextual confinements.

centered

Each token can have any number of caveats (including none). Caveats limit the context in which a token is valid.

Further confining the macaroon — adding caveats

centered

Thanks to cryptographic signatures, caveats cannot be removed from a token. However, they can be added to any token by any party that possesses the token.

Named and temporary tokens

Temporary tokens are short-lived and not persistent, while named tokens are linked to the user's account and retrievable.

Temporary tokens Named tokens
no identification in the system must have a unique name
not persisted persisted

cannot be retrieved
you must store the token upon creation

 linked to subject's account

shared secret
the secret can be regenerated, which invalidates all subject's temporary tokens

 individual secret

cannot be deleted individually
see shared secret above

can be deleted
the token immediately becomes invalid

non-revocable individually
see shared secret above

revocable
revocation can be undone at will

must have limited lifespan
max permitted lifespan is configurable by the Onezone admin

 can have infinite lifespan
no accounting, cannot be listed can be listed in REST API or viewed in WEB GUI
useful for automated software / middleware / scripting require more management but ensure full control

Types of tokens in Onedata

centered

For more details, consult the documentation.

Token caveats in Onedata 1/5

Name Description JSON Example

time

 Limits token validity to a specified time using an absolute timestamp in seconds. 
{
    "type": "time",
    "validUntil": 1571147494
}

ip

 Limits the allowed client IPs to a certain whitelist. 
{
    "type": "ip",
    "whitelist": [
        "189.34.15.0/24",
        "127.0.0.0/8",
        "167.73.12.17"
    ]
}

asn

 Restricts token usage to specific ASNs (Autonomous System Numbers). 
{
    "type": "asn",
    "whitelist": [
        631, 632, 1671
    ]
}

Token caveats in Onedata 2/5

Name Description JSON Example

geo.country

 Restricts token usage to the specific countries. 
{
    "type": "geo.country",
    "filter": "blacklist",
    "list": [
      "PL", "UK", "DE", "NL"
    ]
}

geo.region

 Restricts token usage to the specific geographical region. 
{
    "type": "geo.region",
    "filter": "whitelist",
    "list": [
        "Africa",
        "Antarctica",
        "Asia",
        "EU",
        "Europe",
        "NorthAmerica",
        "Oceania",
        "SouthAmerica"
    ]
}

Token caveats in Onedata 3/5

Name Description JSON Example

service

 Limits the services that can process the token. 
{
    "type": "service",
    "whitelist": [
        "ozw-onezone",
        "ozp-onezone",
        "opw-*",
        "opp-01c4455bef059353c9dfb35ba93a24f3"
    ]
}

consumer

 Restricts token usage to the specific consumers identified with identity tokens. 
{
    "type": "consumer",
    "whitelist": [
        "usr-d4f5876dbe7f1e7e8a511de6dd31144c",
        "grp-0921135ee61fe53a3df449365228e9b4",
        "prv-*"
    ]
}

Token caveats in Onedata 4/5

Name Description JSON Example

interface

Limits the available interfaces to a certain one — rest, oneclient or graphsync.

 
{
    "type": "interface",
    "interface": "rest"
}

api

 Limits the API operations. 
{
    "type": "api",
    "whitelist": [
        "ozw/all/user.*.*:*",
        "all/get/space.*.*:*"
    ]
}

Token caveats in Onedata 5/5

Name Description JSON Example

data.readonly

 Allows only read access to user files. 
{
  "type": "data.readonly"
}

data.path

 Limits the paths in which data can be accessed. 
{
    "type": "data.path",
    "whitelist": [
        "L2QxYjM4OGY3Yzc=",
        "LzhkZjFlYjkwYTcvZGlyL2ZpbGUudHh0Cg=="
    ]
}

data.objectid

 Limits the object IDs in which data can be accessed. 
{
    "type": "data.objectid",
    "whitelist": [
        "000000000055D4E4836803640004677569646D000000167",
        "39592D594E736C676D0000002B43592D347247454C535F6"
    ]
}

For more details, consult the documentation.

Caveats compatibility

The compatibility of caveats with access, identity and invite tokens:

Caveat Access tokens Identity tokens Invite tokens
time allowed allowed allowed
ip allowed allowed allowed
asn allowed allowed allowed
geo.country allowed allowed allowed
geo.region allowed allowed allowed
service allowed rejected rejected
consumer allowed allowed allowed
interface allowed allowed rejected
api allowed rejected rejected
data.readonly allowed rejected rejected
data.path allowed rejected rejected
data.objectid allowed rejected rejected

Data access caveats

Data access caveats carry additional, implicit restrictions. The presence of a data access caveat in a token exclusively designates it for accessing user files, restricting or limiting other APIs to the minimum necessary for handling data access requests. Such tokens can only be used in the Oneprovider service for REST/CDMI operations on files or mounting Oneclient.

The list of data access caveats:

  • interface, but only if equal to oneclient
  • data.readonly
  • data.path
  • data.objectid

The concept of data access caveats aims to enforce a high level of security when delegating a token meant for data access.

data.path and data.objectid caveats imply in which spaces the token can be used — other spaces are completely invisible and inaccessible to the token bearer.

Caveats' impact on services

Each caveat can have a big impact on the token usability in the system, depending on the type. Besides that, there are some other considerations of token caveat usage, summarized in the following tables.

  • allowed — the caveat is recognized and will be checked against the request context
  • rejected — the presence of this caveat will cause immediate token verification failure
  • restricted — the caveat is allowed only in certain circumstances

Onezone

Interface REST GraphSync1 (GUI) GraphSync1 (Oneprovider)
time allowed allowed allowed
ip allowed allowed allowed
asn allowed allowed allowed
geo.country allowed allowed allowed
geo.region allowed allowed allowed
service allowed allowed allowed
consumer allowed allowed allowed
interface2 "rest" "graphsync" restricted3
api allowed allowed allowed
data.readonly rejected rejected restricted3
data.path rejected rejected restricted3
data.objectid rejected rejected restricted3

1The GraphSync interface is used internally for communication between services and is not used directly by users. The information in the table is the same for the GraphSync interfaces of Oneprovider and Onepanel.

2Interface caveats should align with the request interface. One exception is the Oneprovider GraphSync channel, where Onezone accepts various user-delegated tokens, but additional caveats may impose restrictions.

3Oneprovider utilizes the GraphSync channel to retrieve user data from Onezone. Data access caveats in the token restrict operations; even if malicious, Oneprovider can't cause harm with such tokens.

Oneprovider

Interface Oneclient CDMI & REST1 (data access) REST2 (other operations)
time allowed allowed allowed
ip allowed allowed allowed
asn allowed allowed allowed
geo.country allowed allowed allowed
geo.region allowed allowed allowed
service allowed allowed allowed
consumer rejected3 allowed allowed
interface4 "oneclient" "rest" "rest"
api allowed allowed allowed
data.readonly allowed allowed rejected
data.path allowed allowed rejected
data.objectid allowed allowed rejected

1Data access operations cover the complete CDMI API and REST endpoints for file and directory management, including metadata, permissions, and ACLs. Access to these endpoints requires tokens with a data access caveat.

2 Additional REST operations encompass APIs for shares, spaces, views, replicas & transfers, QoS, monitoring, and datastore changes. These endpoints are restricted with tokens containing a data access caveat.

3Mounting Oneclient currently doesn't support consumer tokens, preventing verification of consumer caveats on this interface.

4 The interface caveat must align with the request interface, as indicated in the table.

Onepanel

Interface REST (Onezone panel) REST (Oneprovider panel)
time allowed allowed
ip allowed rejected1
asn allowed rejected1
geo.country allowed rejected1
geo.region allowed rejected1
service allowed allowed
consumer allowed allowed
interface rejected2 rejected2
api allowed allowed
data.readonly rejected rejected
data.path rejected rejected
data.objectid rejected rejected

1Only Onezone panel currently supports IP-related caveats (ASN, country, and region using a GEO IP database). Oneprovider panel is under implementation and, until completed, tokens with these caveats are promptly rejected.

2 Currently, the support for interface caveat in both Onepanels is under implementation. For that time, tokens with such caveats are immediately rejected.

General remarks

When creating a token for public use, consider the following:

  • include carefully chosen data access caveats,
  • in rare cases, use an api caveat to enable a very specific API operation,
  • use an interface caveat and specify the interface on which the token will be exclusively accepted,
  • consider using consumer caveats to limit the available consumers and service caveats to make the token usable only in chosen services.
  • make sure to create a named token to be able to revoke or delete it at any time.

When using or delegating tokens:

  • keep your tokens a secret, the only exceptions are passing an invite token for inviting purposes or delegating an access token properly limited by caveats,
  • it is strongly recommended to include a service caveat in all tokens that are used outside of Onezone service,
  • to use a Oneprovider panel service, the user must be a member of the cluster corresponding to the Oneprovider.

Next chapter:

Tokens (access, identity, invite) — practice

references

todo-docs change links to future docs