The authentication system documentation — Swift 2.31.2.dev8 (2023)

general description

Swift supports a number of authentication schemes that share the following common characteristics:

  • The authentication/authorization part can be an external system or a subsystem running on Swift as a WSGI middleware

  • Swift user passes an auth token with each request

  • Swift validates each token against the external authentication system or authentication subsystem and caches the result

  • The token does not change from one request to another, but it does expire

The token can be passed to Swift using the X-Auth-Token header or the X-Storage-Token header. They both have the same format: just a simple string representing the token. Some authentication systems use UUID tokens, some use an MD5 hash of something unique, some use "something else", but the main point is that the token is a string that can be returned as such to the authentication system for validation.

Swift calls the authentication system and provides the authentication token to validate. For a valid token, the authentication system responds with a total expiration time in seconds from now. To avoid the overhead of validating the same token over and over again, Swift will cache the token for a configurable amount of time, but no longer than the expiration time.

The Swift project includes two authentication systems:

  • TempAuth

  • Keystone authentication

It is also possible to write your own authentication system as described inOr to extend.


TempAuth is primarily used in the Swift functional test environment and can be used in other test environments (such asSAIO (Fast all in one)). It is not recommended to use TempAuth on a production system. However, TempAuth is fully functional and can be used as a template for developing your own authentication system.

TempAuth has the concept of admin and non-admin users in an account. Admin users can do everything within the account. Non-administrator users can perform read-only operations. However, some privileged metadata, such as X-Container-Sync-Key, is not accessible to non-administrators.

Users with special group.reseller_adminYou can work on any account. See an example of useswift.common.middleware.tempauth.If a request is from a reseller, the authentication system sets environmentreseller_request to True. This can be used by other middleware.

Other users can perform operations on an account or container through ACLs. TempAuth supports two types of ACLs:

  • ACL per container based on that of the containerX-Container-ReadInX-Container-Writemetadata to viewContainer-ACLFor more information.

  • ACLs per account based on accountsControl access to account Xmetadata. For more information, seeACL for accounts.

TempAuth now allows tokenless OPTIONS requests.

The TempAuth middleware is responsible for generating its own tokens. A user makes a request with their username and password, and TempAuth responds with a token. This token is then used to make subsequent requests against the user's account, containers, and objects.

Keystone authentication

Swift can authenticate against OpenStackPiedra angular. In this environment, Keystone takes care of generating and validating tokens. HeKeystone authenticationThe middleware is responsible for implementing the authentication system in Swift as described here.

OfKeystone authenticationThe middleware supports container-based ACLs on the container.X-Container-ReadInX-Container-Writemetadata For more information, seeContainer-ACL.

Account-level ACL is not supported for Keystone authentication.

to make use of itkeystone authenticationmiddlewareauth_tokenintermediate vanKeystoneMiddlewaremust be set.

OfauthorizeThe middleware performs authentication token validation and retrieves the authentication information of the actual user. It can be found atKeystoneMiddlewaredistribution.

OfKeystone authenticationThe middleware performs authorization and assigns Keystone roles to Swift ACLs.

Configure Swift to use Keystone

Configure Swift to usePiedra angularit is relatively simple. The first step is to make sure you have theauth_tokenmiddleware installed. Can be placed in or via the python pathKeystoneMiddlewarepackage.

First you need to make sure you have a service endpoint of typeobject storagein Keystone that points to the swift proxy. For example, if you have this in you/etc/keystone/default_catalog.templates = Swift Servicecatalog.RegionOne.object_store.publicURL = http://swiftproxy:8080/v1/AUTH_$(tenant_id)scatalog.RegionOne.object_store.adminURL = http://swiftproxy:8080/v1/ AUTH_$(tenant_id)scatalog.RegionOne.object_store.adminURL = http://swiftproxy. RegionOne.object_store.internalURL = http://swiftproxy:8080/v1/AUTH_$(tenant_id)s

In the swift proxy, you want to customize the main pipe and add auth_token and keystoneauth to/etc/swift/servidorproxy.confsimilar

[conduit:Señor]conduit = [....] authorize keystone authentication attorney-record attorney-server

add the configuration for the authorized middleware:

[filter:authorize]Place.filter_factory = key middleware.auth_token:filter_factorywww_authenticate_uri = http://hostkeystone:5000/auth_url = http://hostkeystone:5000/auth_plug-in = Passwordproject_domain_id = role modeluser_domain_id = role modelProject's name = I'm usingUsername = quicklyPassword = Passwordcrypt = quickly.cryptinclude_service_catalog = Valsdelay_auth_decision = WHERE

The actual values ​​for these variables should be set based on your situation, but briefly:

  • www_authenticate_uriit must point to a Keystone service where users can receive tokens. This value is used inWWW-AuthenticationThe header that auth_token sends with each deny response.

  • auth_urlmeans the Keystone Management Service. The middleware uses this information to query Keystone about the validity of the authentication tokens. You do not need to add a Keystone API version number to this URI.

  • The authentication credentials (project_domain_id,user_domain_id,Username,Project's name,Password) is used to get an admin token. This token is used to authorize user tokens in the background. These credentials must match the Keystone credentials for the Swift service. The example values ​​shown here assume a user named "swift" with an administrator role in a project named "service", both in the Keystone domain with an ID of "default". I meanKeystoneMiddleware documentationfor other examples.

  • cryptadjusted tohidden.snelle. This means that the middleware extracts Swift's cache from the request context.

  • include_service_catalogdefault toWHEREif not set. This means that upon validation of a token, the services directory is retrieved and stored in theService Directory Xin the head. Why fast?Service Directory Xheader, there is no point in retrieving the services directory. We recommend that you setinclude_service_catalogDisgustingVals.


The autoconfiguration variabledelay_auth_decisionshould be setWHERE. The default isVals, but this cuts off public access,static website,FormulierPost,URL temporaland authentication requests (usingDiscovery).

and finally you can add the keystoneauth configuration. Here's a simple setup:

[filter:keystone authentication]to use = No:quickly#keystoneauthoperator_roles = Administration, fast operator

Use an appropriate list of roles in operator_roles. For example, in some systems, paper_tapa_ofTapais used to indicate that the user can work on the project's resources.

OpenStack service using complex tokens

Some OpenStack services like Cinder and Glance can use a "service account". In this mode, you set up a separate account where the service stores the project data it manages. This account is not used directly by the end user. Instead, all access is through the service.

To access the "service" account, the service must present two tokens: one from the end user and one from the service user itself. The account can only be accessed if both tokens are present. This section describes how to set configuration options to correctly manage access to "normal" and "service" accounts.

In this example, end users use theAUT_prefix of the account names, while the services ofI'M USING_prefix:

[filter:keystone authentication]to use = No:quickly#keystoneauthreseller_prefix = A.P.Th, I'M USINGoperator_roles = Administration, fast operatorSERVICE_service_roles = I'm using

The actual values ​​of these variables should be set as follows, depending on your situation:

  • The first entry in the reseller_prefix list must match the Keystone endpoint (see/etc/keystone/default_catalog.templateson). usually that's allA.P.Th.

  • The second entry in the reseller_prefix list is the prefix used by OpenStack services. You must set this value (I'M USINGin the example) with what the other OpenStack services use.

  • Set the operator_roles option to contain a role or roles that end users play in the projects they use.

  • Set the value of SERVICE_service_roles to a role or roles that only the OpenStack service user has. Do not use a role assigned to "normal" end users. In this example, the paperI'm usingis used The service user is assigned this role to asingleproject only. You do not need to make the service user a member of all projects.

This setup works like this:

  • The end user presents a user token to an OpenStack service. The service then makes a swift request to the account with theI'M USINGprefix.

  • The service returns the original user token with the request. It also adds its own service token.

  • Swift validates both tokens. After validation, the user token returns theAdministrationoffast operatorroll). After validation, the service token gives youI'm usingrole.

  • Swift interprets the above configuration as follows:

    • Does the user token provide one of the roles listed in operator_roles?

    • The service token has theI'm usingrole described bySERVICE_service_rolesoptions

  • If both conditions are met, the request is accepted. Otherwise, Swift rejects the request.

In the example above, all services share the same account. You can separate each service into its own account. For example, the following provides a dedicated account for each of the Glance and Cinder services. In addition, you mustsearch_serviceIncinder_serviceto users of eligible services:

[filter:keystone authentication]to use = No:quickly#keystoneauthreseller_prefix = A.P.Th, IMAGE, SOUND VOLUMEoperator_roles = Administration, fast operatorIMAGE_service_roles = search_serviceVOLUME_service_roles = cinder_service

Access control using keystoneauth

By default, the only users who can perform operations (eg, create a container) in an account are those with a Keystone role for the corresponding Keystone project that corresponds to one of the roles specified inoperator_rolesselection.

Users using one of theoperator_rolesyou can set container ACLs to allow other users to read and/or write objects in specific containers, usingX-Container-ReadInX-Container-Writeheaders In addition to the ACL formats describedhere, keystoneauth supports ACLs in the form:


Whereandere_project_idis the UUID of a Keystone project andother_user_idis the UUID of a Keystone user. This allows the other user to access a container, as long as their token is within the scope of the other project. Bothandere_project_idInother_user_idcan be replaced by the wildcard*that adapts to each project or user.

Use Keystone UUIDs instead of names in ACL containers.


For backward compatibility, keystoneauth grants standard container ACLs expressed asother_project_name:other_user_name(i.e. use Keystone names instead of UUIDs) in the special case where both the other project and the other user are in the default Keystone domain and the accessed project is also in the default domain.

For more information, seeKeystone authentication

Users with the Keystone role set torole_administrator_reseller(reseller admindefault) can work on any account. The authentication system sets the reseller_request context to True if a request originates from a user with this role. This can be used by other middleware.

Keystoneauth Troubleshooting Tips

Some common errors can cause API requests to fail when initially deploying Keystone with Swift:

  • Incorrect configuration of the Swift endpoint in the Keystone service.

    By default, Keystoneauth expects the account portion of a URL to be of the formAUT_. sometimes thatAUT_The prefix is ​​ignored when configuring Swift endpoints in Keystone, as described ininstallation instructions. This can be easily diagnosed by inspecting the proxy log for a failed request URL and verifying that the URLAUT_prefix (or whatever reseller prefix is ​​configured for keystoneauth):

    GOOD:attorney-server: 07/September/2016/sixteen/06/58 HEAD /v1/AUTH_cfb8d9d45212408b90bc0776117aec9e HTTP/1.0 204 ...PLACE:attorney-server: 07/September/2016/sixteen/07/35 HEAD /v1/cfb8d9d45212408b90bc0776117aec9e HTTP/1.0 403 ...
  • incorrect configurationauthorizemiddleware options in Swiftproxy server.

    OfauthorizeThe middleware communicates with the Keystone service to validate presented tokens against client requests. To do thisauthorizemust authenticate to Keystone using the credentials configured in the[filter:authentication]Part of/etc/swift/servidorproxy.conf. Errors can occur in these credentialsauthorizeit does not validate tokens and can be revealed in proxy logs with a message like:

    attorney-server: ID card server refused authorization


    More detailed log messages can be viewed fromauthorizeselectionlog level = debugging.

    OfauthorizeThe configuration options can be tested by trying to use them to communicate directly with Keystone using alotcommand line. For example, given theauthorizeConfiguration example shown inConfigure Swift to use Keystone, the following command should return a list of services:

    lot --operating system-ID card-API-version=3 --operating system-authorize-URL=http://hostkeystone:5000/\--operating system-Username=quickly --operating system-user-sector-ID card=role model\--operating system-work-name=I'm using --operating system-work-sector-ID card=role model\--operating system-Password=Password list projection object-store

    Yes thislotthe command failed, there must be a problemauthorizesetting.

Or to extend

TempAuth is written as a wsgi middleware, so implementing your own authentication is as easy as writing a new wsgi middleware and connecting to the proxy.

To seeAuthentication server and middlewarefor detailed information on expanding the authentication system.


Top Articles
Latest Posts
Article information

Author: Mr. See Jast

Last Updated: 06/16/2023

Views: 5483

Rating: 4.4 / 5 (55 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Mr. See Jast

Birthday: 1999-07-30

Address: 8409 Megan Mountain, New Mathew, MT 44997-8193

Phone: +5023589614038

Job: Chief Executive

Hobby: Leather crafting, Flag Football, Candle making, Flying, Poi, Gunsmithing, Swimming

Introduction: My name is Mr. See Jast, I am a open, jolly, gorgeous, courageous, inexpensive, friendly, homely person who loves writing and wants to share my knowledge and understanding with you.