# keystonemiddleware.auth_token package

## Module contents

Token-based Authentication Middleware.

This WSGI component:

- Verifies that incoming client requests have valid tokens by validating tokens with the auth service.

- Rejects unauthenticated requests unless the auth_token middleware is in `delay_auth_decision` mode, which means the final decision is delegated to the downstream WSGI component (usually the OpenStack service).

- Collects and forwards identity information based on a valid token such as user name, domain, project, etc.

Refer to: https://docs.openstack.org/keystonemiddleware/latest/middlewarearchitecture.html

### Headers

The auth_token middleware uses headers sent in by the client on the request and sets headers and environment variables for the downstream WSGI component.

#### Coming in from initial call from client or customer

HTTP_X_AUTH_TOKEN

  The client token being passed in.

HTTP_X_SERVICE_TOKEN

  A service token being passed in.

#### Used for communication between components

WWW-Authenticate

  HTTP header returned to a user indicating which endpoint to use to retrieve a new token.

#### What auth_token adds to the request for use by the OpenStack service

When using composite authentication (a user and service token are present) additional service headers relating to the service user will be added. They take the same form as the standard headers but add `_SERVICE_`. These headers will not exist in the environment if no service token is present.

HTTP_X_IDENTITY_STATUS, HTTP_X_SERVICE_IDENTITY_STATUS

  Will be set to either `Confirmed` or `Invalid`.

  The underlying service will only see a value of ‘Invalid’ if the middleware is configured to run in `delay_auth_decision` mode. As with all such headers, `HTTP_X_SERVICE_IDENTITY_STATUS` will only exist in the environment if a service token is presented. This is different than `HTTP_X_IDENTITY_STATUS` which is always set even if no user token is presented. This allows the underlying service to determine if a denial should use `401 Unauthenticated` or `403 Forbidden`.

HTTP_OPENSTACK_SYSTEM_SCOPE

  A string relaying system information about the token’s scope. This attribute is only present if the token is system-scoped. The string `all` means the token is scoped to the entire deployment system.

HTTP_X_DOMAIN_ID, HTTP_X_SERVICE_DOMAIN_ID

  Identity service managed unique identifier, string. Only present if this is a domain-scoped token.

HTTP_X_DOMAIN_NAME, HTTP_X_SERVICE_DOMAIN_NAME

  Unique domain name, string. Only present if this is a domain-scoped token.

HTTP_X_PROJECT_ID, HTTP_X_SERVICE_PROJECT_ID

  Identity service managed unique identifier, string. Only present if this is a project-scoped token.

HTTP_X_PROJECT_NAME, HTTP_X_SERVICE_PROJECT_NAME

  Project name, unique within owning domain, string. Only present if this is a project-scoped token.

HTTP_X_PROJECT_DOMAIN_ID, HTTP_X_SERVICE_PROJECT_DOMAIN_ID

  Identity service managed unique identifier of owning domain of project, string. Only present if this is a project-scoped v3 token. If this variable is set, this indicates that the PROJECT_NAME can only be assumed to be unique within this domain.

HTTP_X_PROJECT_DOMAIN_NAME, HTTP_X_SERVICE_PROJECT_DOMAIN_NAME

  Name of owning domain of project, string. Only present if this is a project-scoped v3 token. If this variable is set, this indicates that the PROJECT_NAME can only be assumed to be unique within this domain.

HTTP_X_USER_ID, HTTP_X_SERVICE_USER_ID

  Identity-service managed unique identifier, string.

HTTP_X_USER_NAME, HTTP_X_SERVICE_USER_NAME

  User identifier, unique within owning domain, string.

HTTP_X_USER_DOMAIN_ID, HTTP_X_SERVICE_USER_DOMAIN_ID

  Identity service managed unique identifier of owning domain of user, string. If this variable is set, this indicates that the USER_NAME can only be assumed to be unique within this domain.

HTTP_X_USER_DOMAIN_NAME, HTTP_X_SERVICE_USER_DOMAIN_NAME

  Name of owning domain of user, string. If this variable is set, this indicates that the USER_NAME can only be assumed to be unique within this domain.

HTTP_X_ROLES, HTTP_X_SERVICE_ROLES

  Comma delimited list of case-sensitive role names.

HTTP_X_IS_ADMIN_PROJECT

  The string value ‘True’ or ‘False’ representing whether the user’s token is scoped to the admin project. As historically there was no admin project this will default to True for tokens without this information to be backwards with existing policy files.

HTTP_X_SERVICE_CATALOG

  service catalog (optional, JSON string).

  For compatibility reasons this catalog will always be in the V2 catalog format even if it is a v3 token.

  Note

  This is an exception in that it contains ‘SERVICE’ but relates to a user token, not a service token. The existing user’s catalog can be very large; it was decided not to present a catalog relating to the service token to avoid using more HTTP header space.

HTTP_X_TENANT_ID

  Deprecated in favor of HTTP_X_PROJECT_ID.

  Identity service managed unique identifier, string. For v3 tokens, this will be set to the same value as HTTP_X_PROJECT_ID.

HTTP_X_TENANT_NAME

  Deprecated in favor of HTTP_X_PROJECT_NAME.

  Project identifier, unique within owning domain, string. For v3 tokens, this will be set to the same value as HTTP_X_PROJECT_NAME.

HTTP_X_TENANT

  Deprecated in favor of HTTP_X_TENANT_ID and HTTP_X_TENANT_NAME.

  Identity server-assigned unique identifier, string. For v3 tokens, this will be set to the same value as HTTP_X_PROJECT_ID.

HTTP_X_USER

  Deprecated in favor of HTTP_X_USER_ID and HTTP_X_USER_NAME.

  User name, unique within owning domain, string.

HTTP_X_ROLE

  Deprecated in favor of HTTP_X_ROLES.

  Will contain the same values as HTTP_X_ROLES.

#### Environment Variables

These variables are set in the request environment for use by the downstream WSGI component.

keystone.token_info

  Information about the token discovered in the process of validation. This may include extended information returned by the token validation call, as well as basic information about the project and user.

keystone.token_auth

  A keystoneauth1 auth plugin that may be used with a `keystoneauth1.session.Session`. This plugin will load the authentication data provided to auth_token middleware.

### Configuration

auth_token middleware configuration can be in the main application’s configuration file, e.g. in `nova.conf`:

    [keystone_authtoken]
    auth_plugin = password
    auth_url = http://keystone:5000/
    username = nova
    user_domain_id = default
    password = whyarewestillusingpasswords
    project_name = service
    project_domain_id = default

Configuration can also be in the `api-paste.ini` file with the same options, but this is discouraged.

### Swift

When deploy auth_token middleware with Swift, user may elect to use Swift memcache instead of the local auth_token memcache. Swift memcache is passed in from the request environment and it’s identified by the `swift.cache` key. However it could be different, depending on deployment. To use Swift memcache, you must set the `cache` option to the environment key where the Swift cache object is stored.

class keystonemiddleware.auth_token.AuthProtocol(app, conf)

  Bases: `BaseAuthProtocol`

  Middleware that handles authenticating client calls.

  fetch_token(token, allow_expired=False)

    Retrieve a token from either a PKI bundle or the identity server.

    Parameters:

      token (str) – token id

    Raises:

      exc.InvalidToken – if token is rejected

  process_request(request)

    Process request.

    Evaluate the headers in a request and attempt to authenticate the request. If authenticated then additional headers are added to the request for use by applications. If not authenticated the request will be rejected or marked unauthenticated depending on configuration.

  process_response(response)

    Process Response.

    Add `WWW-Authenticate` headers to requests that failed with `401 Unauthenticated` so users know where to authenticate for future requests.

class keystonemiddleware.auth_token.BaseAuthProtocol(app, log=<KeywordArgumentAdapter keystonemiddleware.auth_token (WARNING)>, enforce_token_bind='permissive', service_token_roles=None, service_token_roles_required=False, service_type=None)

  Bases: `object`

  A base class for AuthProtocol token checking implementations.

  Parameters:

    - app (Callable) – The next application to call after middleware.

    - log (logging.Logger) – The logging object to use for output. By default it will use a logger in the keystonemiddleware.auth_token namespace.

    - enforce_token_bind (str) – The style of token binding enforcement to perform.

  fetch_token(token, **kwargs)

    Fetch the token data based on the value in the header.

    Retrieve the data associated with the token value that was in the header. This can be from PKI, contacting the identity server or whatever is required.

    Parameters:

      - token (str) – The token present in the request header.

      - kwargs (dict) – Additional keyword arguments may be passed through here to support new features. If an implementation is not aware of how to use these arguments it should ignore them.

    Raises:

      exc.InvalidToken – if token is invalid.

    Returns:

      The token data

    Return type:

      dict

  process_request(request)

    Process request.

    If this method returns a value then that value will be used as the response. The next application down the stack will not be executed and process_response will not be called.

    Otherwise, the next application down the stack will be executed and process_response will be called with the generated response.

    By default this method does not return a value.

    Parameters:

      request (_request.AuthTokenRequest) – Incoming request

  process_response(response)

    Do whatever you’d like to the response.

    By default the response is returned unmodified.

    Parameters:

      response (._request._AuthTokenResponse) – Response object

  validate_allowed_request(request, token)

keystonemiddleware.auth_token.app_factory(global_conf, **local_conf)

keystonemiddleware.auth_token.filter_factory(global_conf, **local_conf)

  Return a WSGI filter app for use with paste.deploy.

keystonemiddleware.auth_token.list_opts()

  Return a list of oslo_config options available in auth_token middleware.

  The returned list includes all oslo_config options which may be registered at runtime by the project.

  Each element of the list is a tuple. The first element is the name of the group under which the list of elements in the second element will be registered. A group name of None corresponds to the [DEFAULT] group in config files.

  NOTE: This function is no longer used for oslo_config sample generation. Some services rely on this function for listing ALL (including deprecated) options and registering them into their own config objects which we do not want for sample config files.

  See: `keystonemiddleware.auth_token._opts.list_opts()` for sample config files.

  Returns:

    a list of (group_name, opts) tuples

this page last updated: 2026-01-20 19:16:52

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug