keystoneauth/doc/source/using-sessions.rst

Using Sessions

Introduction

The :pykeystoneauth1.session.Session class was introduced into keystoneauth1 as an attempt to bring a unified interface to the various OpenStack clients that share common authentication and request parameters between a variety of services.

The model for using a Session and auth plugin as well as the general terms used have been heavily inspired by the requests library. However neither the Session class nor any of the authentication plugins rely directly on those concepts from the requests library so you should not expect a direct translation.

Features

• Common client authentication

  Authentication is handled by one of a variety of authentication plugins and then this authentication information is shared between all the services that use the same Session object.

• Security maintenance

  Security code is maintained in a single place and reused between all clients such that in the event of problems it can be fixed in a single location.

• Standard discovery mechanisms

  Clients are not expected to have any knowledge of an identity token or any other form of identification credential. Service and endpoint discovery are handled by the Session and plugins.

Sessions for Users

The Session object is the contact point to your OpenStack cloud services. It stores the authentication credentials and connection information required to communicate with OpenStack such that it can be reused to communicate with many services. When creating services this Session object is passed to the client so that it may use this information.

A Session will authenticate on demand. When a request that requires authentication passes through the Session the authentication plugin will be asked for a valid token. If a valid token is available it will be used otherwise the authentication plugin may attempt to contact the authentication service and fetch a new one.

An example using keystoneclient to wrap a session:

>>> from keystoneauth1.identity import v3
>>> from keystoneauth1 import session
>>> from keystoneclient.v3 import client

>>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3',
...                    username='myuser',
...                    password='mypassword',
...                    project_name='proj',
...                    user_domain_id='default',
...                    project_domain_id='default')
>>> sess = session.Session(auth=auth,
...                        verify='/path/to/ca.cert')
>>> ks = client.Client(session=sess)
>>> users = ks.users.list()

As other OpenStack client libraries adopt this means of operating they will be created in a similar fashion by passing the Session object to the client's constructor.

Sharing Authentication Plugins

A session can only contain one authentication plugin however there is nothing that specifically binds the authentication plugin to that session, a new Session can be created that reuses the existing authentication plugin:

>>> new_sess = session.Session(auth=sess.auth,
                               verify='/path/to/different-cas.cert')

In this case we cannot know which session object will be used when the plugin performs the authentication call so the command must be able to succeed with either.

Authentication plugins can also be provided on a per-request basis. This will be beneficial in a situation where a single session is juggling multiple authentication credentials:

>>> sess.get('https://my.keystone.com:5000/v3',
             auth=my_auth_plugin)

If an auth plugin is provided via parameter then it will override any auth plugin on the session.

Sessions for Client Developers

Sessions are intended to take away much of the hassle of dealing with authentication data and token formats. Clients should be able to specify filter parameters for selecting the endpoint and have the parsing of the catalog managed for them.

Authentication

When making a request with a session object you can simply pass the keyword parameter authenticated to indicate whether the argument should contain a token, by default a token is included if an authentication plugin is available:

>>> # In keystone this route is unprotected by default
>>> resp = sess.get('https://my.keystone.com:5000/v3',
                    authenticated=False)

Service Discovery

In OpenStack the URLs of available services are distributed to the user as a part of the token they receive called the Service Catalog. Clients are expected to use the URLs from the Service Catalog rather than have them provided.

In general a client does not need to know the full URL for the server that they are communicating with, simply that it should send a request to a path belonging to the correct service.

This is controlled by the endpoint_filter parameter to a request which contains all the information an authentication plugin requires to determine the correct URL to which to send a request. When using this mode only the path for the request needs to be specified:

>>> resp = session.get('/users',
                       endpoint_filter={'service_type': 'identity',
                                        'interface': 'admin',
                                        'region_name': 'myregion'})

endpoint_filter accepts a number of arguments with which it can determine an endpoint url:

• `service_type`: the type of service. For example identity, compute, volume or many other predefined identifiers.
• `interface`: the network exposure the interface has. This will be one of:
  • public: An endpoint that is available to the wider internet or network.
  • internal: An endpoint that is only accessible within the private network.
  • admin: An endpoint to be used for administrative tasks.
• `region_name`: the name of the region where the endpoint resides.

The endpoint filter is a simple key-value filter and can be provided with any number of arguments. It is then up to the auth plugin to correctly use the parameters it understands.

If you want to further limit your service discovery by allowing experimental APIs or disallowing deprecated APIs, you can use the allow parameter:

>>> resp = session.get('/<project-id>/volumes',
                       endpoint_filter={'service_type': 'volume',
                                        'interface': 'public',
                                        'version': 1},
                       allow={'allow_deprecated': False})

The discoverable types of endpoints that allow can recognize are:

• `allow_deprecated`: Allow deprecated version endpoints.
• `allow_experimental`: Allow experimental version endpoints.
• `allow_unknown`: Allow endpoints with an unrecognised status.

The session object determines the URL matching the filters and append to it the provided path and so create a valid request. If multiple URL matches are found then any one may be chosen.

While authentication plugins will endeavour to maintain a consistent set of arguments for an endpoint_filter the concept of an authentication plugin is purposefully generic and a specific mechanism may not know how to interpret certain arguments and ignore them. For example the keystoneauth1.token_endpoint.Token plugin (which is used when you want to always use a specific endpoint and token combination) will always return the same endpoint regardless of the parameters to endpoint_filter or a custom OpenStack authentication mechanism may not have the concept of multiple interface options and choose to ignore that parameter.

There is some expectation on the user that they understand the limitations of the authentication system they are using.