Keystone tokens¶
Tokens are used to authenticate and authorize your interactions with the various OpenStack APIs. Tokens come in many flavors, representing various authorization scopes and sources of identity. There are also several different “token providers”, each with their own user experience, performance, and deployment characteristics.
Authorization scopes¶
Tokens are used to relay information about your user’s role assignments. It’s not uncommon for a user to have multiple role assignments, sometimes spanning projects, domains, or the entire system. These are referred to as authorization scopes, where a token has a single scope of operation. For example, a token scoped to a project can’t be reused to do something else in a different project.
Each level of authorization scope is useful for certain types of operations in certain OpenStack services, and are not interchangeable.
Unscoped tokens¶
An unscoped token contains neither a service catalog, any roles, a project scope, nor a domain scope. Their primary use case is simply to prove your identity to keystone at a later time (usually to generate scoped tokens), without repeatedly presenting your original credentials.
The following conditions must be met to receive an unscoped token:
- You must not specify an authorization scope in your authentication request
(for example, on the command line with arguments such as
--os-project-nameor--os-domain-id), - Your identity must not have a “default project” associated with it that you also have role assignments, and thus authorization, upon.
Project-scoped tokens¶
Project-scoped tokens express your authorization to operate in a specific tenancy of the cloud and are useful to authenticate yourself when working with most other services.
They contain a service catalog, a set of roles, and details of the project upon which you have authorization.
Domain-scoped tokens¶
Domain-scoped tokens have limited use cases in OpenStack. They express your authorization to operate a domain-level, above that of the user and projects contained therein (typically as a domain-level administrator). Depending on Keystone’s configuration, they are useful for working with a single domain in Keystone.
They contain a limited service catalog (only those services which do not explicitly require per-project endpoints), a set of roles, and details of the project upon which you have authorization.
They can also be used to work with domain-level concerns in other services, such as to configure domain-wide quotas that apply to all users or projects in a specific domain.
System-scoped tokens¶
There are APIs across OpenStack that fit nicely within the concept of a project or domain, but there are also APIs that affect the entire deployment system (e.g. modifying endpoints, service management, or listing information about hypervisors). These operations require the use of a system-scoped token, which represents the role assignments a user has to operate on the deployment as a whole.
Token providers¶
The token type issued by keystone is configurable through the
/etc/keystone/keystone.conf file. Currently, there are two supported
token types, UUID and fernet.
UUID tokens¶
UUID was the first token type supported but was deprecated in Pike. UUID tokens are 32 bytes in length and must be persisted in a back end. Clients must pass their UUID token to the Identity service in order to validate it.
As mentioned above, UUID tokens must be persisted. By default, keystone persists UUID tokens using a SQL backend. An unfortunate side-effect is that the size of the database will grow over time regardless of the token’s expiration time. Expired UUID tokens can be pruned from the backend using keystone’s command line utility:
$ keystone-manage token_flush
We recommend invoking this command periodically using cron.
Note
It is not required to run this command at all if using Fernet tokens. Fernet tokens are not persisted and do not contribute to database bloat.
Fernet tokens¶
The fernet token format was introduced in the OpenStack Kilo release and now
is the default token provider in Keystone. Unlike the other token types
mentioned in this document, fernet tokens do not need to be persisted in a back
end. AES256 encryption is used to protect the information stored in the
token and integrity is verified with a SHA256 HMAC signature. Only the
Identity service should have access to the keys used to encrypt and decrypt
fernet tokens. Like UUID tokens, fernet tokens must be passed back to the
Identity service in order to validate them. For more information on the fernet
token type, see the Fernet - Frequently Asked Questions.
Summary
| Feature | Status | Fernet tokens | UUID tokens |
|---|---|---|---|
| Create unscoped token | mandatory | ✔ |
✔ |
| Create system-scoped token | mandatory | ✔ |
✔ |
| Create project-scoped token | mandatory | ✔ |
✔ |
| Create domain-scoped token | optional | ✔ |
✔ |
| Create trust-scoped token | optional | ✔ |
✔ |
| Create a token given an OAuth access token | optional | ✔ |
✔ |
| Create a token with a bind attribute | optional | ✖ |
✔ |
| Revoke a token | optional | ✔ |
✔ |
| Online validation | mandatory | ✔ |
✔ |
| Offline validation | optional | ✖ |
✖ |
| Non-persistent | optional | ✔ |
✖ |
Details
- Create unscoped token
Status: mandatory. All token providers must be capable of issuing tokens without an explicit scope of authorization.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> token issue
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- Create system-scoped token
Status: mandatory. All token providers must be capable of issuing system-scoped tokens.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-system token issue
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- Create project-scoped token
Status: mandatory. All token providers must be capable of issuing project-scoped tokens.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> --os-project-name=<project> --os-project-domain-name=<domain> token issue
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- Create domain-scoped token
Status: optional. Domain-scoped tokens are not required for all use cases, and for some use cases, projects can be used instead.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> --os-domain-name=<domain> token issue
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- Create trust-scoped token
Status: optional. Tokens scoped to a trust convey only the user impersonation and project-based authorization attributes included in the delegation.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> --os-trust-id=<trust> token issue
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- Create a token given an OAuth access token
Status: optional. OAuth access tokens can be exchanged for keystone tokens.
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- UUID tokens:
- Create a token with a bind attribute
Status: optional. Tokens can express a binding to an additional authentication method, such as kerberos or x509.
drivers:
- UUID tokens:
complete - Fernet tokens:
missing
- UUID tokens:
- Revoke a token
Status: optional. Tokens may be individually revoked, such as when a user logs out of Horizon. Under certain circumstances, it’s acceptable for more than just a single token may be revoked as a result of this operation (such as when the revoked token was previously used to create additional tokens).
CLI commands:
openstack token revoke
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- Online validation
Status: mandatory. Keystone must be able to validate the tokens that it issues when presented with a token that it previously issued.
drivers:
- UUID tokens:
complete - Fernet tokens:
complete
- UUID tokens:
- Offline validation
Status: optional. Services using Keystone for authentication may want to validate tokens themselves, rather than calling back to keystone, in order to improve performance and scalability.
drivers:
- UUID tokens:
missing - Fernet tokens:
missing
- UUID tokens:
- Non-persistent
Status: optional. If a token format does not require persistence (such as to a SQL backend), then there is no scalability limit to the number of tokens that keystone can issue at once, and there is no need to perform clean up operations such as `keystone-manage token_flush`.
drivers:
- UUID tokens:
missing - Fernet tokens:
complete
- UUID tokens:
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.