swiftclient¶

OpenStack Swift Python client binding.

swiftclient.authv1¶

Authentication plugin for keystoneauth to support v1 endpoints.

Way back in the long-long ago, there was no Keystone. Swift used an auth mechanism now known as “v1”, which used only HTTP headers. Auth requests and responses would look something like:

> GET /auth/v1.0 HTTP/1.1
> Host: <swift server>
> X-Auth-User: <tenant>:<user>
> X-Auth-Key: <password>
>
< HTTP/1.1 200 OK
< X-Storage-Url: http://<swift server>/v1/<tenant account>
< X-Auth-Token: <token>
< X-Storage-Token: <token>
<

This plugin provides a way for Keystone sessions (and clients that use them, like python-openstackclient) to communicate with old auth endpoints that still use this mechanism, such as tempauth, swauth, or https://identity.api.rackspacecloud.com/v1.0

class swiftclient.authv1.AccessInfoV1(auth_url, storage_url, account, username, auth_token, token_life)¶

An object for encapsulating a raw v1 auth token.

classmethod from_state(data)¶

Deserialize the given state.

Returns: a new AccessInfoV1 object with the given state

get_state()¶: Serialize the current state.

will_expire_soon(stale_duration)¶

Determines if expiration is about to occur.

Returns: true if expiration is within the given duration

class swiftclient.authv1.PasswordLoader¶

Option handling for the v1password plugin.

property available¶

Return if the plugin is available for loading.

If a plugin is missing dependencies or for some other reason should not be available to the current system it should override this property and return False to exclude itself from the plugin list.

Return type: bool

create_plugin(**kwargs)¶

Create a plugin from the options available for the loader.

Given the options that were specified by the loader create an appropriate plugin. You can override this function in your loader.

This used to be specified by providing the plugin_class property and this is still supported, however specifying a property didn’t let you choose a plugin type based upon the options that were presented.

Override this function if you wish to return different plugins based on the options presented, otherwise you can simply provide the plugin_class property.

Added 2.9

get_options()¶

Return the list of parameters associated with the auth plugin.

This list may be used to generate CLI or config arguments.

load_from_options(**kwargs)¶

Create a plugin from the arguments retrieved from get_options.

A client can override this function to do argument validation or to handle differences between the registered options and what is required to create the plugin.

load_from_options_getter(getter, **kwargs)¶

Load a plugin from getter function that returns appropriate values.

To handle cases other than the provided CONF and CLI loading you can specify a custom loader function that will be queried for the option value. The getter is a function that takes a keystoneauth1.loading.Opt and returns a value to load with.

Parameters: getter (callable) – A function that returns a value for the given opt.
Returns: An authentication Plugin.
Return type: keystoneauth1.plugin.BaseAuthPlugin

plugin_class¶: alias of swiftclient.authv1.PasswordPlugin

class swiftclient.authv1.PasswordPlugin(auth_url, username, password, project_name=None, reauthenticate=True)¶

A plugin for authenticating with a username and password.

Subclassing from BaseIdentityPlugin gets us a few niceties, like handling token invalidation and locking during authentication.

Parameters

auth_url (string) – Identity v1 endpoint for authorization.
username (string) – Username for authentication.
password (string) – Password for authentication.
project_name (string) – Swift account to use after authentication. We use ‘project_name’ to be consistent with other auth plugins.
reauthenticate (string) – Whether to allow re-authentication.

access_class¶: alias of swiftclient.authv1.AccessInfoV1

get_access(session, **kwargs)¶

Fetch or return a current AccessInfo object.

If a valid AccessInfo is present then it is returned otherwise a new one will be fetched.

Parameters: session (keystoneauth1.session.Session) – A session object that can be used for communication.
Raises: keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.
Returns: Valid AccessInfo
Return type: keystoneauth1.access.AccessInfo

get_all_version_data(session, interface='public', region_name=None, service_type=None, **kwargs)¶

Get version data for all services in the catalog.

Parameters

session (keystoneauth1.session.Session) – A session object that can be used for communication.
interface – Type of endpoint to get version data for. Can be a single value or a list of values. A value of None indicates that all interfaces should be queried. (optional, defaults to public)
region_name (string) – Region of endpoints to get version data for. A valueof None indicates that all regions should be queried. (optional, defaults to None)
service_type (string) – Limit the version data to a single service. (optional, defaults to None)

Returns

A dictionary keyed by region_name with values containing dictionaries keyed by interface with values being a list of VersionData.

get_api_major_version(session, service_type=None, interface=None, region_name=None, service_name=None, version=None, allow=None, allow_version_hack=True, skip_discovery=False, discover_versions=False, min_version=None, max_version=None, **kwargs)¶

Return the major API version for a service.

If a valid token is not present then a new one will be fetched using the session and kwargs.

version, min_version and max_version can all be given either as a string or a tuple.

Valid interface types: public or publicURL,: internal or internalURL, admin or ‘adminURL`

Parameters

session (keystoneauth1.session.Session) – A session object that can be used for communication.
service_type (string) – The type of service to lookup the endpoint for. This plugin will return None (failure) if service_type is not provided.
interface – Type of endpoint. Can be a single value or a list of values. If it’s a list of values, they will be looked for in order of preference. Can also be keystoneauth1.plugin.AUTH_INTERFACE to indicate that the auth_url should be used instead of the value in the catalog. (optional, defaults to public)
region_name (string) – The region the endpoint should exist in. (optional)
service_name (string) – The name of the service in the catalog. (optional)
version – The minimum version number required for this endpoint. (optional)
allow (dict) – Extra filters to pass when discovering API versions. (optional)
allow_version_hack (bool) – Allow keystoneauth to hack up catalog URLS to support older schemes. (optional, default True)
skip_discovery (bool) – Whether to skip version discovery even if a version has been given. This is useful if endpoint_override or similar has been given and grabbing additional information about the endpoint is not useful.
discover_versions (bool) – Whether to get version metadata from the version discovery document even if it’s not neccessary to fulfill the major version request. Defaults to False because get_endpoint doesn’t need metadata. (optional, defaults to False)
min_version – The minimum version that is acceptable. Mutually exclusive with version. If min_version is given with no max_version it is as if max version is ‘latest’. (optional)
max_version – The maximum version that is acceptable. Mutually exclusive with version. If min_version is given with no max_version it is as if max version is ‘latest’. (optional)

Raises

keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns

The major version of the API of the service discovered.

Return type

tuple or None

Note

Implementation notes follow. Users should not need to wrap their head around these implementation notes. get_api_major_version should do what is expected with the least possible cost while still consistently returning a value if possible.

There are many cases when major version can be satisfied without actually calling the discovery endpoint (like when the version is in the url). If the user has a cloud with the versioned endpoint https://volume.example.com/v3 in the catalog for the block-storage service and they do:

client = adapter.Adapter(
    session, service_type='block-storage', min_version=2,
    max_version=3)
volume_version = client.get_api_major_version()

The version actually be returned with no api calls other than getting the token. For that reason, get_api_major_version() first calls get_endpoint_data() with discover_versions=False.

If their catalog has an unversioned endpoint https://volume.example.com for the block-storage service and they do this:

client = adapter.Adapter(session, service_type='block-storage')

client is now set up to “use whatever is in the catalog”. Since the url doesn’t have a version, get_endpoint_data() with discover_versions=False will result in api_version=None. (No version was requested so it didn’t need to do the round trip)

In order to find out what version the endpoint actually is, we must make a round trip. Therefore, if api_version is None after the first call, get_api_major_version() will make a second call to get_endpoint_data() with discover_versions=True.

get_auth_ref(session, **kwargs)¶

Obtain a token from a v1 endpoint.

This function should not be called independently and is expected to be invoked via the do_authenticate function.

This function will be invoked if the AcessInfo object cached by the plugin is not valid. Thus plugins should always fetch a new AccessInfo when invoked. If you are looking to just retrieve the current auth data then you should use get_access.

Parameters: session – A session object that can be used for communication.
Returns: Token access information.

get_auth_state()¶

Retrieve the current authentication state for the plugin.

Returns: raw python data (which can be JSON serialized) that can be moved into another plugin (of the same type) to have the same authenticated state.

get_cache_id()¶

Fetch an identifier that uniquely identifies the auth options.

The returned identifier need not be decomposable or otherwise provide any way to recreate the plugin.

This string MUST change if any of the parameters that are used to uniquely identity this plugin change. It should not change upon a reauthentication of the plugin.

Returns: A unique string for the set of options
Return type: str or None if this is unsupported or unavailable.

get_cache_id_elements()¶: Get the elements for this auth plugin that make it unique.

get_connection_params(session, **kwargs)¶

Return any additional connection parameters required for the plugin.

Parameters: session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.
Returns: Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.
Return type: dict

get_discovery(*args, **kwargs)¶

Return the discovery object for a URL.

Check the session and the plugin cache to see if we have already performed discovery on the URL and if so return it, otherwise create a new discovery object, cache it and return it.

This function is expected to be used by subclasses and should not be needed by users.

Parameters

session (keystoneauth1.session.Session) – A session object to discover with.
url (str) – The url to lookup.
authenticated (bool) – Include a token in the discovery call. (optional) Defaults to None (use a token if a plugin is installed).

Raises

keystoneauth1.exceptions.discovery.DiscoveryFailure – if for some reason the lookup fails.
keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns

A discovery object with the results of looking up that URL.

get_endpoint(session, interface='public', **kwargs)¶: Return an endpoint for the client.

get_endpoint_data(session, service_type=None, interface=None, region_name=None, service_name=None, allow=None, allow_version_hack=True, discover_versions=True, skip_discovery=False, min_version=None, max_version=None, endpoint_override=None, **kwargs)¶

Return a valid endpoint data for a service.

If a valid token is not present then a new one will be fetched using the session and kwargs.

version, min_version and max_version can all be given either as a string or a tuple.

Valid interface types: public or publicURL,: internal or internalURL, admin or ‘adminURL`

Parameters

session (keystoneauth1.session.Session) – A session object that can be used for communication.
service_type (string) – The type of service to lookup the endpoint for. This plugin will return None (failure) if service_type is not provided.
interface – Type of endpoint. Can be a single value or a list of values. If it’s a list of values, they will be looked for in order of preference. Can also be keystoneauth1.plugin.AUTH_INTERFACE to indicate that the auth_url should be used instead of the value in the catalog. (optional, defaults to public)
region_name (string) – The region the endpoint should exist in. (optional)
service_name (string) – The name of the service in the catalog. (optional)
allow (dict) – Extra filters to pass when discovering API versions. (optional)
allow_version_hack (bool) – Allow keystoneauth to hack up catalog URLS to support older schemes. (optional, default True)
discover_versions (bool) – Whether to get version metadata from the version discovery document even if it’s not neccessary to fulfill the major version request. (optional, defaults to True)
skip_discovery (bool) – Whether to skip version discovery even if a version has been given. This is useful if endpoint_override or similar has been given and grabbing additional information about the endpoint is not useful.
min_version – The minimum version that is acceptable. Mutually exclusive with version. If min_version is given with no max_version it is as if max version is ‘latest’. (optional)
max_version – The maximum version that is acceptable. Mutually exclusive with version. If min_version is given with no max_version it is as if max version is ‘latest’. (optional)
endpoint_override (str) – URL to use instead of looking in the catalog. Catalog lookup will be skipped, but version discovery will be run. Sets allow_version_hack to False (optional)
kwargs – Ignored.

Raises

keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns

Valid EndpointData or None if not available.

Return type

keystoneauth1.discover.EndpointData or None

get_headers(session, **kwargs)¶

Fetch authentication headers for message.

This is a more generalized replacement of the older get_token to allow plugins to specify different or additional authentication headers to the OpenStack standard ‘X-Auth-Token’ header.

How the authentication headers are obtained is up to the plugin. If the headers are still valid they may be re-used, retrieved from cache or the plugin may invoke an authentication request against a server.

The default implementation of get_headers calls the get_token method to enable older style plugins to continue functioning unchanged. Subclasses should feel free to completely override this function to provide the headers that they want.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved and that authorization was a failure. Adding no authentication data can be achieved by returning an empty dictionary.

Parameters: session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.
Returns: Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.
Return type: dict

get_project_id(session, **kwargs)¶

Return the project id that we are authenticated to.

Wherever possible the project id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated project id.

Parameters: session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.
Returns: A project identifier or None if one is not available.
Return type: str

get_sp_auth_url(*args, **kwargs)¶

Return auth_url from the Service Provider object.

This url is used for obtaining unscoped federated token from remote cloud.

Parameters: sp_id (string) – ID of the Service Provider to be queried.
Returns: A Service Provider auth_url or None if one is not available.
Return type: str

get_sp_url(*args, **kwargs)¶

Return sp_url from the Service Provider object.

This url is used for passing SAML2 assertion to the remote cloud.

Parameters: sp_id (str) – ID of the Service Provider to be queried.
Returns: A Service Provider sp_url or None if one is not available.
Return type: str

get_token(session, **kwargs)¶

Return a valid auth token.

If a valid token is not present then a new one will be fetched.

Parameters: session (keystoneauth1.session.Session) – A session object that can be used for communication.
Raises: keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.
Returns: A valid token.
Return type: string

get_user_id(session, **kwargs)¶

Return a unique user identifier of the plugin.

Wherever possible the user id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated user id.

Parameters: session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.
Returns: A user identifier or None if one is not available.
Return type: str

invalidate()¶

Invalidate the current authentication data.

This should result in fetching a new token on next call.

A plugin may be invalidated if an Unauthorized HTTP response is returned to indicate that the token may have been revoked or is otherwise now invalid.

Returns: True if there was something that the plugin did to invalidate. This means that it makes sense to try again. If nothing happens returns False to indicate give up.
Return type: bool

set_auth_state(data)¶

Install existing authentication state for a plugin.

Take the output of get_auth_state and install that authentication state into the current authentication plugin.

swiftclient

swiftclient¶

swiftclient.authv1¶

swiftclient.client¶

swiftclient.service¶

swiftclient.exceptions¶

swiftclient.multithreading¶

swiftclient.utils¶

python-swiftclient 3.13.2.dev2

Page Contents