Token Essentials

In addition to HTTP Basic authentication, Gateway allows configuring token-based authentication. Token-based authentication works in two steps:

Request a token, by using HTTP Basic authentication to perform a one-time authentication within the Management API or to a special URI path in the Storage API.
Submit this token on all subsequent requests as proof of the user's credentials.

Tokens have these characteristics:

Ownership: They are always owned by the user who created them, except for tokens created by the token administrator.
Expiration: They expire at a fixed time after creation; default is 24 hours.
S3 Key: They may contain an optional secret access key for use with the S3 protocol.
Deletion: Both the owner and the token administrator can list and delete the owner's active tokens.

See Token-Based Authentication.

Best Practice

Token behavior cannot be selectively restricted (such as to work for specific actions or in specific domains/buckets). Prevent sharing of tokens with untrusted users/clients, as with any credentials.
Fully qualify the names of any token administrators (such as caringoadmin@ or caringoadmin+acmetenant) defined in an IDSYS document to avoid ambiguity when multiple IDSYS are used.

Accessing Tokens

Tokens can be accessed under the gear icon, which appears in the title bar of all tenants and domains (not buckets):

Swarm Documentation > Setting Tokens > image2018-11-26_22-26-40.png

Creating Tokens

The default owner and expiration date can be overridden, as well as choosing to enable the S3 Secret Key when creating a token manually (for the current tenant or domain):

Swarm Documentation > Setting Tokens > image2016-7-12 11:24:16.png

Important

The S3 Secret Key for the token must be copied from the Success message before closing it: for security reasons, the S3 Secret Key is not displayed in the Content UI after this point.

Swarm Documentation > Setting Tokens > image2019-2-2_17-34-14.png

Best Practice

Delete the token and create a new one so security is not compromised if S3 Secret Key is lost.

See S3 Application Integration.

Managing Tokens

The UI lists all valid tokens, whether created here or programmatically, by the Management API. As soon as a token expires, it no longer appears in the listing and count of tokens.

Tokens are listed on the Tokens tab with a counter and a Filter Tokens field if any tokens exist for the particular tenant or domain, which allows searching for tokens matching the string within the Owner name or Description text. The S3 Secret Key is not displayed in the UI after creation for security reasons.

Double-click a token to view the properties and, optionally, delete it:

Swarm Documentation > Setting Tokens > Tokens_Tenant.png

Caution

Tokens cannot be restored if deleted through this interface.