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/developer/keystonemiddleware/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_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:35357/
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: keystonemiddleware.auth_token.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
kwargs_to_fetch_token = True
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=<oslo_log.log.KeywordArgumentAdapter object>, enforce_token_bind=’permissive’, service_token_roles=None, service_token_roles_required=False)

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
kwargs_to_fetch_token = False
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
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