Token-Based Authentication

In addition to HTTP Basic authentication, Content Gateway allows for the use of an optional token-based 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 in order 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 user that creates them 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 their 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 in order to create tenant tokens for storage domains that belong 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 that defines the token settings. Both the cookieName and tokenPath parameters must be defined in order to enable token-based authentication.

{
"ldap" : { ...
	"cookieName": "token",
	"tokenPath": "/.TOKEN/",
	"tokenAdmin": "superuser@admindomain.example.com"
	}
}

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 their active tokens. The tokenAdmin is the user name of the token administrator who is able to create, list, and delete tokens on behalf of other users.

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

See "Qualification of User/Group Names" in the IDSYS Document Format.

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

To create a new authentication token, POST a blank document to either:

• your storage domain and token path, or
• the Management API path /_admin/manage/tenants/{tenantName}/tokens/

...using 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.