Session Documentation
Include some client documentation for how to work with a Session object. This is generally high level with this expectation that a developer could take the concepts found here and determine more from the module documentation. Change-Id: I5e44c1029ce160cb2798cfb8a535aa9f3311799a
This commit is contained in:
Jamie Lennox
@@ -12,6 +12,7 @@ Contents:
|
||||
:maxdepth: 1
|
||||
|
||||
man/keystone
|
||||
using-sessions
|
||||
using-api-v2
|
||||
using-api-v3
|
||||
|
||||
|
||||
198
doc/source/using-sessions.rst
Normal file
198
doc/source/using-sessions.rst
Normal file
@@ -0,0 +1,198 @@
|
||||
==============
|
||||
Using Sessions
|
||||
==============
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The :py:class:`keystoneclient.session.Session` class was introduced into
|
||||
keystoneclient 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 from keystoneclient::
|
||||
|
||||
>>> from keystoneclient.auth.identity import v3
|
||||
>>> from keystoneclient import session
|
||||
>>> from keystoneclient.v3 import client
|
||||
|
||||
>>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v2.0',
|
||||
... username='myuser',
|
||||
... password='mypassword',
|
||||
... project_id='proj')
|
||||
>>> sess = session.Session(auth=auth,
|
||||
... verify='/path/to/ca.cert')
|
||||
>>> ks = client.Client(session=sess)
|
||||
>>> users = ks.users.list()
|
||||
|
||||
As clients adopt this means of operating they will be created in a similar
|
||||
fashion by passing the Session object to the client's constructor.
|
||||
|
||||
|
||||
Migrating keystoneclient to use a Session
|
||||
-----------------------------------------
|
||||
|
||||
By using a session with a keystonclient Client we define that you have opted in
|
||||
to new behaviour defined by the session. For example authentication is now
|
||||
on-demand rather than on creation. To allow this change in behaviour there are
|
||||
a number of functions that have changed behaviour or are no longer available.
|
||||
|
||||
For example the
|
||||
:py:meth:`keystoneclient.httpclient.HTTPClient.authenticate` command used
|
||||
to be able to always re-authenticate the current client and fetch a new token.
|
||||
As this is now controlled by the Session and not the client this has changed,
|
||||
however the function will still exist to provide compatibility with older
|
||||
clients.
|
||||
|
||||
Likewise certain parameters such as ``user_id`` and ``auth_token`` that used to
|
||||
be available on the client object post authentication will remain
|
||||
uninitialized.
|
||||
|
||||
When converting an application to use a session object with keystoneclient you
|
||||
should be aware of the possibility of changes to authentication and
|
||||
authentication parameters and make sure to test your code thoroughly. It should
|
||||
have no impact on the typical CRUD interaction with the client.
|
||||
|
||||
|
||||
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('/v3/users',
|
||||
endpoint_filter={'service_type': 'identity',
|
||||
'interface': 'public',
|
||||
'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.
|
||||
|
||||
The session object determines the URL matching the filter 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
|
||||
:py:class:`keystoneclient.auth.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.
|
||||
Reference in New Issue
Block a user