Keystone tokens¶
Tokens are used to authenticate and authorize your interactions with OpenStack APIs. Tokens come in many scopes, representing various authorization and sources of identity.
Authorization scopes¶
Tokens are used to relay information about your 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 (e.g., a project, domain, or the system). 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 does not contain a service catalog, roles, or authorization scope (e.g., project, domain, or system attributes within the token). 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-name
or--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¶
Projects are containers for resources, like volumes or instances. Project-scoped tokens express your authorization to operate in a specific tenancy of the cloud and are useful for things like spinning up compute resources or carving off block storage. They contain a service catalog, a set of roles, and information about the project.
Most end-users need role assignments on projects to consume resources in a deployment.
Domain-scoped tokens¶
Domains are namespaces for projects, users, and groups. A domain-scoped token expresses your authorization to operate on the contents of a domain or the domain itself.
While some OpenStack services are still adopting the domain concept, domains are fully supported in keystone. This means users with authorization on a domain have the ability to manage things within the domain. For example, a domain administrator can create new users and projects within that domain.
Domain-scoped tokens contain a service catalog, roles, and information about the domain.
People who need to manage users and projects typically need domain-level access.
System-scoped tokens¶
Some OpenStack APIs fit nicely within the concept of projects (e.g., creating an instance) or domains (e.g., creating a new user), but there are also APIs that affect the entire deployment system (e.g. modifying endpoints, service management, or listing information about hypervisors). These operations are typically reserved for operators and require system-scoped tokens, which represents the role assignments a user has to operate on the deployment as a whole. The term system refers to the deployment system, which is a collection of hardware (e.g., compute nodes) and services (e.g., nova, cinder, neutron, barbican, keystone) that provide Infrastructure-as-a-Service.
System-scoped tokens contain a service catalog, roles, and information about the system. System role assignments and system-scoped tokens are typically reserved for operators and cloud administrators.
Token providers¶
The token type issued by keystone is configurable through the
/etc/keystone/keystone.conf
file. Currently, there are two supported token
providers, fernet
and jws
.
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.
A deployment might consider using the fernet provider as opposed to JWS tokens if they are concerned about public expose of the payload used to build tokens.
JWS tokens¶
The JSON Web Signature (JWS) token format is a type of JSON Web Token (JWT) and
it was implemented in the Stein release. JWS tokens are signed, meaning the
information used to build the token ID is not opaque to users and can it can be
decoded by anyone. JWS tokens are ephemeral, or non-persistent, which means
they won’t bloat the database or require replication across nodes. Since the
JWS token provider uses asymmetric keys, the tokens are signed with private
keys and validated with public keys. The JWS token provider implementation
only supports the ES256
JSON Web Algorithm (JWA), which is an Elliptic
Curve Digital Signature Algorithm (ECDSA) using the P-256 curve and a SHA-256
hash algorithm.
A deployment might consider using JWS tokens as opposed to fernet tokens if there are security concerns about sharing symmetric encryption keys across hosts. Note that a major difference between the two providers is that JWS tokens are not opaque and can be decoded by anyone with the token ID. Fernet tokens are opaque in that the token ID is ciphertext. Despite the JWS token payload being readable by anyone, keystone reserves the right to make backwards incompatible changes to the token payload itself, which is not an API contract. We only recommend validating the token against keystone’s authentication API to inspect its associated metadata. We strongly discourage relying on decoded payloads for information about tokens.
More information about JWTs can be found in the specification.
Summary
Feature | Status | Fernet tokens | JWS 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 | ✔ |
✔ |
Revoke a token | optional | ✔ |
✔ |
Details
- Create unscoped token
Status: mandatory.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> token issue
Notes: All token providers must be capable of issuing tokens without an explicit scope of authorization.
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
- Create system-scoped token
Status: mandatory.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-system-scope all token issue
Notes: All token providers must be capable of issuing system-scoped tokens.
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
- Create project-scoped token
Status: mandatory.
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
Notes: All token providers must be capable of issuing project-scoped tokens.
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
- Create domain-scoped token
Status: optional.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> --os-domain-name=<domain> token issue
Notes: Domain-scoped tokens are not required for all use cases, and for some use cases, projects can be used instead.
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
- Create trust-scoped token
Status: optional.
CLI commands:
openstack --os-username=<username> --os-user-domain-name=<domain> --os-password=<password> --os-trust-id=<trust> token issue
Notes: Tokens scoped to a trust convey only the user impersonation and project-based authorization attributes included in the delegation.
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
- Create a token given an OAuth access token
Status: optional.
Notes: OAuth access tokens can be exchanged for keystone tokens.
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
- Fernet tokens:
- Revoke a token
Status: optional.
CLI commands:
openstack token revoke
Notes: 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).
Driver Support:
- Fernet tokens:
complete
- JWS tokens:
complete
Notes:
- This document is a continuous work in progress