194 lines
7.8 KiB
ReStructuredText
194 lines
7.8 KiB
ReStructuredText
==============
|
|
Using Sessions
|
|
==============
|
|
|
|
Introduction
|
|
============
|
|
|
|
The :py:class:`keystoneauth1.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 <http://docs.python-requests.org>`_
|
|
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
|
|
:class:`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.
|