Understanding OpenStack Keystone: Scoped vs. Unscoped Tokens

OpenStack Keystone is the identity service used by OpenStack to manage users and provide authentication and authorization services. Within the Keystone context, tokens are a core component, acting as the bearer of the user’s authentication context. In this blog post, we’ll compare scoped and unscoped tokens and explore what can be done with each type.

Unscoped Tokens

An unscoped token is the first level of authentication token that a user receives upon providing their credentials (username and password) to Keystone. Think of it as a proof of identity without context. It doesn’t contain any information about the tenant (project), domain, or role of the user; it simply confirms that the user is who they say they are.

Uses of Unscoped Tokens:

• Basic Authentication: The primary use of an unscoped token is to allow a user to authenticate themselves to Keystone. It’s a way to say, “Keystone knows I am a valid user.”
• Fetching Scope: Once authenticated, users can use an unscoped token to request a scoped token. This step is critical because most of the OpenStack services require a scoped token to grant access to resources.
• Listing Accessible Tenants: Unscoped tokens can be used to list the projects or domains the user has access to, which is necessary to determine the scope they want to work within.

Scoped Tokens

A scoped token, in contrast, is like an unscoped token with additional context. It is obtained after the user has authenticated with an unscoped token and has specified the scope of their authorization. Scopes can be at the project level (project-scoped) or at the domain level (domain-scoped), and the token will carry information about the user’s roles and permissions within that scope.

Uses of Scoped Tokens:

• Access to OpenStack Services: Scoped tokens are necessary to interact with most OpenStack services, such as Nova for compute, Swift for object storage, and Neutron for networking. These services need to know the user’s roles within a specific project or domain to determine what resources the user can access and what actions they can perform.
• Role-Based Access Control (RBAC): Scoped tokens are essential for enforcing RBAC within OpenStack. The roles included in the token determine what operations the user is allowed to perform within the scope of a particular project or domain.
• Service Catalog: When a scoped token is generated, it also includes the service catalog, which is a list of all services and endpoints available to the user within the specified scope. This information is used to interact with different services within OpenStack.
• Auditing and Tracking: Scoped tokens allow the cloud administrators to audit actions and track usage per project or domain, as the scope of the token clearly defines the boundary within which the user operates.

Comparison: Scoped vs. Unscoped Tokens

• Authentication Level: Unscoped tokens represent only the authentication step, while scoped tokens represent both authentication and authorization.
• Information Content: Scoped tokens carry specific information about the project/domain and the user’s role within that scope. Unscoped tokens carry none of this contextual information.
• Service Interaction: Unscoped tokens cannot directly interact with most OpenStack services beyond Keystone, whereas scoped tokens are required to work with the full suite of OpenStack services.
• Security: Scoped tokens define a limited context in which a user can operate, which is better for security, as it restricts user operations to a particular scope.
• Lifetime: Typically, the lifetime of a scoped token is shorter than an unscoped token, reflecting its more sensitive nature, as it grants more privileges.

To interact with OpenStack’s Identity service (Keystone), you will typically use REST API calls. Below are examples of how you might request both unscoped and scoped tokens using the Keystone API. Note that the actual implementation might vary depending on the version of OpenStack you are using and your deployment’s configuration.

Getting an Unscoped Token

To get an unscoped token, you simply authenticate with your username and password, and you don’t specify a project or domain.

Here is an example of how to get an unscoped token using a REST API call:

curl -si -X POST http://keystone.example.com:5000/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
        "auth": {
          "identity": {
            "methods": ["password"],
            "password": {
              "user": {
                "name": "exampleuser",
                "domain": { "id": "default" },
                "password": "examplepass"
              }
            }
          }
        }
      }'

The response headers will contain an X-Subject-Token header, which is the unscoped token you can use to get a scoped token.

Getting a Scoped Token

To get a scoped token, you authenticate using your unscoped token and then request a token scoped to a specific project or domain.

Here is an example of how to get a project-scoped token using a REST API call:

curl -si -X POST http://keystone.example.com:5000/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_UNSCOPED_TOKEN" \
  -d '{
        "auth": {
          "identity": {
            "methods": ["token"],
            "token": {
              "id": "YOUR_UNSCOPED_TOKEN"
            }
          },
          "scope": {
            "project": {
              "name": "exampleproject",
              "domain": { "id": "default" }
            }
          }
        }
      }'

In this request, the X-Auth-Token header and the token.id field in the JSON body should be your unscoped token received from the previous call. The scope field in the JSON body determines that you want a project-scoped token for the project named exampleproject.

And here is an example for a domain-scoped token:

curl -si -X POST http://keystone.example.com:5000/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_UNSCOPED_TOKEN" \
  -d '{
        "auth": {
          "identity": {
            "methods": ["token"],
            "token": {
              "id": "YOUR_UNSCOPED_TOKEN"
            }
          },
          "scope": {
            "domain": {
              "id": "default"
            }
          }
        }
      }'

For the domain-scoped token, the request is almost the same, but the scope is defined with domain instead of project.

Important Considerations:

• Replace http://keystone.example.com:5000 with the actual URL of your Keystone service.
• Always use HTTPS in production to ensure security.
• Actual user credentials and project/domain IDs should replace the placeholders.
• The API calls above assume the usage of Keystone API v3, which is the current version as of my last update.
• The token you receive in response headers should be protected as it allows access to your OpenStack resources.

Remember, you’ll receive the scoped token in the response header’s X-Subject-Token, which you’ll then use for subsequent requests to other OpenStack services.

Conclusion

In the world of OpenStack Keystone, understanding the difference between scoped and unscoped tokens is crucial for navigating the authentication and authorization mechanisms. Unscoped tokens are the starting point, verifying a user’s identity, while scoped tokens are the key to performing actions within the cloud environment. By wisely managing these tokens, OpenStack ensures that users have the correct level of access, thus maintaining a secure and efficient cloud platform.

As the cloud continues to evolve, so too does the importance of mastering such concepts. Whether you’re a cloud administrator, a developer, or an end-user, understanding the nuances of Keystone tokens is instrumental in leveraging the full potential of OpenStack’s capabilities.