Token-Based Authentication

Content Gateway allows for the use of an optional token-based authentication in addition to HTTP Basic authentication. Token-based authentication works by performing a one-time HTTP Basic authentication request within the Management API or to a special URI path in the Storage API to receive a token. This token is used on subsequent requests as proof of the user's credentials.

Tokens have the following characteristics:

• They are always owned by the creating user except for tokens created by token administrators.

• They expire at a fixed time after creation; default is 24 hours if not specified.

• They may contain an optional S3 secret access key for use with the S3 protocol.

• They may contain optional metadata matching the prefix pattern: x-custom-meta-*

• The owner can list and delete active tokens.

• The token administrators can list and delete any user's active tokens.

Application developers may prefer to make use of the Management API to create tenant tokens for storage domains belonging to a tenant. Storage domain tokens are created with the special URI defined by the tokenPath IDSYS attribute.

The following is an example excerpt from a root IDSYS configuration file defining the token settings. Both the cookieName and tokenPath parameters must be defined to enable token-based authentication.

Tokens are delivered using the standard HTTP cookie mechanism. The cookieName parameter is the cookie's name and the value is the token. The token value is guaranteed to be universally unique and impossible to guess. The tokenPath parameter defines the URI path within the storage domain with which a user requests a token and then performs listing and delete operations on active tokens. The tokenAdmin is the user name of the token administrator able to create, list, and delete tokens on behalf of other users.

The token administrator is recommended to be a fully qualified user name to avoid ambiguity in a situation where a storage domain may inherit the IDSYS from the tenant or root scope.

See "Qualification of User/Group Names" in the https://perifery.atlassian.net/wiki/spaces/public/pages/2443816826.

Gateway stores all tokens within the administrative domain as automatically expiring objects using the object lifepoint feature. The expiration time of an authentication token can be specified when the token is created. A default expiration time is assigned based on the tokenTTLHours parameter in the [gateway] section of the gateway.cfg file if the time is not specified. The request proceeds as an anonymous user subject to all normal access control policies if an expired token is presented to Gateway. The Set-Cookie header of the response instructs the HTTP client to delete the expired token cookie.

POST a blank document to either of the following to create a new authentication token:

• the storage domain and token path, or

• the Management API path /_admin/manage/tenants/{tenantName}/tokens/

Use HTTP Basic authentication to authenticate the request. Requests to the tokenPath URI are processed independently from the storage protocol handling and these instructions work with both SCSP and S3 front-end protocols and to the Management API.