Introduction to encrypted authenticated tokens

The Identity service supports tokens of
different types and formats to enable a user to authenticate against
a specific Rackspace Technology Cloud service.

• The token type specifies whether the user is provisioned
  or federated.
• The token format specifies the composition of the token itself.

Identity has switched the authentication token format
from UUID to Authenticated Encryption (AE). Rackspace engineers
have implemented the new token format on the Identity system back
end, and the change has minimal impact on Rackspace customers. The main
difference is that the authentication token value
returned by the Identity service has a different pattern and length than
the UUID token values issued previously.

Note: Make sure that you follow Best practices for handling authentication
tokens (located further down in this article),
especially if you use SDK or CLI tools to interact with the Rackspace
Cloud.

This article explains the two different token formats and provides best
practices for working with authentication tokens in general.

What is an AE token?

Using Authenticated Encryption generates an AE token.
Authenticated encryption specifies a way to secure a message so that
others cannot fake it, change it, or read it.

Authenticated encryption generates non-persistent tokens for
user authentication. An AE token contains all the necessary data to
determine whether a given token is valid instead of pointing to this
data. AE tokens have all the encrypted metadata within the token
itself. Because AE tokens contain all the relevant data, there is no
need to store the tokens in persistent storage. When the server receives
the token, it can parse the token metadata to determine if it's valid.

Because of encryption, the size of an AE-formatted token varies. The
Identity service limits the size of AE-formatted tokens
to 250 bytes.

The following example shows a token object from the authentication
response with an AE token ID.

"token": {
      "id": "ABCDEF7RbnU-LLWJ1J8PeHRGMz2Cf3rPUG_a25hQRWTcL7tH231H7ubr6y1EkRi_curq6PqJV-pCiIADZrwFtCexcy9MVO3eckgGWqDqnxvXaUMF7XA_reFwwp3pNu_7p9uXofGmiueccwrA",
      "expires": "2015-08-20T23:51:19.055Z",
       "tenant": {
       "id": "123456",
       "name": "123456"
         }

What is a UUID token?

Authentication tokens that use the UUID token format
are persistent tokens. When a user authenticates successfully, the
Identity service generates a 32 character UUID token
value and stores it in a persistent storage unit on the back end. The service
also saves metadata about that token such as expiration timestamp, who the
token is issued to, and so on. Then, the service returns the token value to
the user, who can include it in subsequent requests to Rackspace Cloud
services to confirm identity.

When the user submits a request with the token, the Identity service
validates the token value against the data stored in the
persistent storage to confirm that the user is authorized to perform the
operation. When a UUID token expires, the user must re-authenticate.
Then, the Identity service issues a new token and also deletes the
expired token from the persistent back-end storage unit.

The following example shows a token object from the authentication
response with a UUID token id.

"token": {
      "id": "b726839ca0fd4d9ead8edbb73f123456",
      "expires": "2015-08-20T23:48:50.793Z",
      "tenant": {
      "id": "123456",
      "name": "123456"
         }

What is the difference between UUID and AE tokens?

UUID and AE tokens differ in their persistence, length, and storage.

• UUID tokens are persistent. AE tokens are non-persistent. With a
  UUID token, you receive a token when you authenticate. That token
  persists in back-end storage for 24-hours and the system returns the
  same value each time you authenticate until the token expires. With AE
  tokens, the value is non-persistent, which means that the value is
  not stored on the backend, and the Identity service generates and
  returns a new token value each time the user authenticates.
• UUID tokens are 32 characters in length. AE tokens vary in size, but
  for the Identity service, they have a 250-byte limit.
  2With the implementation of AE tokens, you will notice
  that the token value returned when you authenticate is significantly
  longer than the value returned when the Identity service issued
  UUID tokens.
• The system stores the UUID tokens in the Identity service back-end
  with the metadata for authentication. AE tokens provide the required
  authentication metadata within the encrypted token value. The
  Identity service does not store the AE token value in the
  back-end system.

Best practices for handling authentication tokens

Following are some best practices for handling authentication tokens.

• When you authenticate to the Identity service, be
  sure to cache the returned token value.

  The Identity service validates the authentication
  token in every API request before attempting to complete
  the operation. To optimize your API operations and reduce system
  load, store the authentication token in a secure cache or database
  so that applications can use the stored value instead of requiring
  the application to issue an authentication request before each
  API operation. You can reuse the cached token value as long as it
  remains valid.

  Note: For an example of caching credentials with an SDK,
  see Caching credentials in
  the php-opencloud documentation.

• Design applications to reauthenticate after receiving
  a 401 Unauthorized{.code} response from a service endpoint or to
  check the token expiration and reauthenticate before the token
  expires.

• To simplify authentication, credential, and token management, use
  an OpenStack command-line client application.

For more information, read the Manage authentication tokens section
in the Identity API 2.0 Guide.

Use the Feedback tab to make any comments or ask questions. You can also start a conversation with us.