From 07a6d149193042769e6e77b06771d40b19c17f08 Mon Sep 17 00:00:00 2001 From: Morgan Fainberg Date: Thu, 19 Jun 2014 21:37:46 -0700 Subject: [PATCH] Correct Doc location and update for middleware only Correct the location of the documents and only publish middleware documentation. --- {docs => doc}/.gitignore | 0 {docs => doc}/Makefile | 4 +- {docs => doc}/ext/__init__.py | 0 {docs => doc}/ext/apidoc.py | 4 +- {docs => doc}/source/_templates/.placeholder | 0 {docs => doc}/source/_theme/layout.html | 0 {docs => doc}/source/_theme/theme.conf | 0 {docs => doc}/source/conf.py | 17 +- .../source/images/graphs_authComp.svg | 0 .../source/images/graphs_authCompDelegate.svg | 0 doc/source/index.rst | 34 +++ .../source/middlewarearchitecture.rst | 10 +- {docs => doc}/source/static/basic.css | 0 {docs => doc}/source/static/default.css | 0 {docs => doc}/source/static/header-line.gif | Bin {docs => doc}/source/static/header_bg.jpg | Bin {docs => doc}/source/static/jquery.tweet.js | 0 {docs => doc}/source/static/nature.css | 0 .../source/static/openstack_logo.png | Bin {docs => doc}/source/static/tweaks.css | 0 docs/source/index.rst | 42 ---- docs/source/man/keystone.rst | 150 ------------- docs/source/using-api-v2.rst | 117 ----------- docs/source/using-api-v3.rst | 113 ---------- docs/source/using-sessions.rst | 198 ------------------ 25 files changed, 50 insertions(+), 639 deletions(-) rename {docs => doc}/.gitignore (100%) rename {docs => doc}/Makefile (94%) rename {docs => doc}/ext/__init__.py (100%) rename {docs => doc}/ext/apidoc.py (92%) rename {docs => doc}/source/_templates/.placeholder (100%) rename {docs => doc}/source/_theme/layout.html (100%) rename {docs => doc}/source/_theme/theme.conf (100%) rename {docs => doc}/source/conf.py (94%) rename {docs => doc}/source/images/graphs_authComp.svg (100%) rename {docs => doc}/source/images/graphs_authCompDelegate.svg (100%) create mode 100644 doc/source/index.rst rename {docs => doc}/source/middlewarearchitecture.rst (97%) rename {docs => doc}/source/static/basic.css (100%) rename {docs => doc}/source/static/default.css (100%) rename {docs => doc}/source/static/header-line.gif (100%) rename {docs => doc}/source/static/header_bg.jpg (100%) rename {docs => doc}/source/static/jquery.tweet.js (100%) rename {docs => doc}/source/static/nature.css (100%) rename {docs => doc}/source/static/openstack_logo.png (100%) rename {docs => doc}/source/static/tweaks.css (100%) delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/man/keystone.rst delete mode 100644 docs/source/using-api-v2.rst delete mode 100644 docs/source/using-api-v3.rst delete mode 100644 docs/source/using-sessions.rst diff --git a/docs/.gitignore b/doc/.gitignore similarity index 100% rename from docs/.gitignore rename to doc/.gitignore diff --git a/docs/Makefile b/doc/Makefile similarity index 94% rename from docs/Makefile rename to doc/Makefile index 430e5a33..84f00bd5 100644 --- a/docs/Makefile +++ b/doc/Makefile @@ -62,9 +62,9 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/python-keystoneclient.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/keystonemiddleware.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/python-keystoneclient.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/keystonemiddleware.qhc" latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex diff --git a/docs/ext/__init__.py b/doc/ext/__init__.py similarity index 100% rename from docs/ext/__init__.py rename to doc/ext/__init__.py diff --git a/docs/ext/apidoc.py b/doc/ext/apidoc.py similarity index 92% rename from docs/ext/apidoc.py rename to doc/ext/apidoc.py index 60ad23e8..2575f422 100644 --- a/docs/ext/apidoc.py +++ b/doc/ext/apidoc.py @@ -35,10 +35,10 @@ def run_apidoc(app): run_already = True package_dir = path.abspath(path.join(app.srcdir, '..', '..', - 'keystoneclient')) + 'keystonemiddleware')) source_dir = path.join(app.srcdir, 'api') apidoc.main(['apidoc', package_dir, '-f', - '-H', 'keystoneclient Modules', + '-H', 'keystonemiddleware Modules', '-o', source_dir]) diff --git a/docs/source/_templates/.placeholder b/doc/source/_templates/.placeholder similarity index 100% rename from docs/source/_templates/.placeholder rename to doc/source/_templates/.placeholder diff --git a/docs/source/_theme/layout.html b/doc/source/_theme/layout.html similarity index 100% rename from docs/source/_theme/layout.html rename to doc/source/_theme/layout.html diff --git a/docs/source/_theme/theme.conf b/doc/source/_theme/theme.conf similarity index 100% rename from docs/source/_theme/theme.conf rename to doc/source/_theme/theme.conf diff --git a/docs/source/conf.py b/doc/source/conf.py similarity index 94% rename from docs/source/conf.py rename to doc/source/conf.py index e0e877ee..c6e3d5fa 100644 --- a/docs/source/conf.py +++ b/doc/source/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# python-keystoneclient documentation build configuration file, created by +# keystonemiddleware documentation build configuration file, created by # sphinx-quickstart on Sun Dec 6 14:19:25 2009. # # This file is execfile()d with the current directory set to its containing @@ -64,13 +64,13 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'python-keystoneclient' +project = 'keystonemiddleware' copyright = 'OpenStack Contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -version_info = pbr.version.VersionInfo('python-keystoneclient') +version_info = pbr.version.VersionInfo('keystonemiddleware') # The short X.Y version. version = version_info.version_string() # The full version, including alpha/beta/rc tags. @@ -117,10 +117,7 @@ pygments_style = 'sphinx' # Grouping the document tree for man pages. # List of tuples 'sourcefile', 'target', 'title', 'Authors name', 'manual' -man_pages = [ - ('man/keystone', 'keystone', 'Client for OpenStack Identity API', - ['OpenStack Contributors'], 1), -] +man_pages = [] # -- Options for HTML output -------------------------------------------------- @@ -195,7 +192,7 @@ html_last_updated_fmt = os.popen(git_cmd).read() #html_file_suffix = '' # Output file base name for HTML help builder. -htmlhelp_basename = 'python-keystoneclientdoc' +htmlhelp_basename = 'keystonemiddlewaredoc' # -- Options for LaTeX output ------------------------------------------------- @@ -210,8 +207,8 @@ htmlhelp_basename = 'python-keystoneclientdoc' # (source start file, target name, title, author, documentclass [howto/manual]) # . latex_documents = [ - ('index', 'python-keystoneclient.tex', - 'python-keystoneclient Documentation', + ('index', 'keystonmiddleware.tex', + 'keystonemiddleware Documentation', 'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', 'manual'), ] diff --git a/docs/source/images/graphs_authComp.svg b/doc/source/images/graphs_authComp.svg similarity index 100% rename from docs/source/images/graphs_authComp.svg rename to doc/source/images/graphs_authComp.svg diff --git a/docs/source/images/graphs_authCompDelegate.svg b/doc/source/images/graphs_authCompDelegate.svg similarity index 100% rename from docs/source/images/graphs_authCompDelegate.svg rename to doc/source/images/graphs_authCompDelegate.svg diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..4bf6098b --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,34 @@ +Python Middleware for OpenStack Identity API (Keystone) +======================================================= + +This is the middleware provided for integrating with the OpenStack +Identity API and handling authorization enforcement based upon the +data within the OpenStack Identity tokens. + +Contents: + +.. toctree:: + :maxdepth: 1 + + middlewarearchitecture + +Contributing +============ + +Code is hosted `on GitHub`_. Submit bugs to the Keystone project on +`Launchpad`_. Submit code to the ``openstack/keystonemiddleware`` project +using `Gerrit`_. + +.. _on GitHub: https://github.com/openstack/keystonemiddleware +.. _Launchpad: https://launchpad.net/keystonemiddleware +.. _Gerrit: http://wiki.openstack.org/GerritWorkflow + +Run tests with ``python setup.py test``. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/source/middlewarearchitecture.rst b/doc/source/middlewarearchitecture.rst similarity index 97% rename from docs/source/middlewarearchitecture.rst rename to doc/source/middlewarearchitecture.rst index 47ae5316..87124a3e 100644 --- a/docs/source/middlewarearchitecture.rst +++ b/doc/source/middlewarearchitecture.rst @@ -32,7 +32,7 @@ authentication middleware which acts as the internal API mechanism for OpenStack projects based on the WSGI standard. This documentation describes the implementation in -:class:`keystoneclient.middleware.auth_token` +:class:`keystonemiddleware.auth_token` Specification Overview ====================== @@ -120,7 +120,7 @@ a WSGI component. Example for the auth_token middleware:: pipeline = authtoken myService [filter:authtoken] - paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory + paste.filter_factory = keystonemiddleware.auth_token:filter_factory # Prefix to prepend at the beginning of the path (string # value) @@ -246,7 +246,7 @@ config file. For example in Nova, all middleware parameters can be removed from api-paste.ini:: [filter:authtoken] - paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory + paste.filter_factory = keystonemiddleware.auth_token:filter_factory and set in nova.conf:: @@ -414,10 +414,10 @@ unsuccessful. Extended the request with additional User Information ----------------------------------------------------- -:py:class:`keystoneclient.middleware.auth_token.AuthProtocol` extends the +:py:class:`keystonemiddleware.auth_token.AuthProtocol` extends the request with additional information if the user has been authenticated. See the "What we add to the request for use by the OpenStack service" section in -:py:mod:`keystoneclient.middleware.auth_token` for the list of fields set by +:py:mod:`keystonemiddleware.auth_token` for the list of fields set by the auth_token middleware. diff --git a/docs/source/static/basic.css b/doc/source/static/basic.css similarity index 100% rename from docs/source/static/basic.css rename to doc/source/static/basic.css diff --git a/docs/source/static/default.css b/doc/source/static/default.css similarity index 100% rename from docs/source/static/default.css rename to doc/source/static/default.css diff --git a/docs/source/static/header-line.gif b/doc/source/static/header-line.gif similarity index 100% rename from docs/source/static/header-line.gif rename to doc/source/static/header-line.gif diff --git a/docs/source/static/header_bg.jpg b/doc/source/static/header_bg.jpg similarity index 100% rename from docs/source/static/header_bg.jpg rename to doc/source/static/header_bg.jpg diff --git a/docs/source/static/jquery.tweet.js b/doc/source/static/jquery.tweet.js similarity index 100% rename from docs/source/static/jquery.tweet.js rename to doc/source/static/jquery.tweet.js diff --git a/docs/source/static/nature.css b/doc/source/static/nature.css similarity index 100% rename from docs/source/static/nature.css rename to doc/source/static/nature.css diff --git a/docs/source/static/openstack_logo.png b/doc/source/static/openstack_logo.png similarity index 100% rename from docs/source/static/openstack_logo.png rename to doc/source/static/openstack_logo.png diff --git a/docs/source/static/tweaks.css b/doc/source/static/tweaks.css similarity index 100% rename from docs/source/static/tweaks.css rename to doc/source/static/tweaks.css diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 53224629..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,42 +0,0 @@ -Python bindings to the OpenStack Identity API (Keystone) -======================================================== - -This is a client for OpenStack Identity API. There's a Python API for -:doc:`Identity API v3 ` and :doc:`v2 ` (the -:mod:`keystoneclient` modules), and a command-line script (installed as -:doc:`keystone `). - -Contents: - -.. toctree:: - :maxdepth: 1 - - man/keystone - using-sessions - using-api-v2 - using-api-v3 - - middlewarearchitecture - - api/modules - -Contributing -============ - -Code is hosted `on GitHub`_. Submit bugs to the Keystone project on -`Launchpad`_. Submit code to the ``openstack/python-keystoneclient`` project -using `Gerrit`_. - -.. _on GitHub: https://github.com/openstack/python-keystoneclient -.. _Launchpad: https://launchpad.net/python-keystoneclient -.. _Gerrit: http://wiki.openstack.org/GerritWorkflow - -Run tests with ``python setup.py test``. - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/source/man/keystone.rst b/docs/source/man/keystone.rst deleted file mode 100644 index d96d89f7..00000000 --- a/docs/source/man/keystone.rst +++ /dev/null @@ -1,150 +0,0 @@ -======================================== -:program:`keystone` command line utility -======================================== - -.. program:: keystone -.. highlight:: bash - -SYNOPSIS -======== - -:program:`keystone` [options] [command-options] - -:program:`keystone help` - -:program:`keystone help` - - -DESCRIPTION -=========== - -The :program:`keystone` command line utility interacts with services providing -OpenStack Identity API (e.g. Keystone). - -To communicate with the API, you will need to be authenticated - and the -:program:`keystone` provides multiple options for this. - -While bootstrapping keystone the authentication is accomplished with a -shared secret token and the location of the Identity API endpoint. The -shared secret token is configured in keystone.conf as "admin_token". - -You can specify those values on the command line with :option:`--os-token` -and :option:`--os-endpoint`, or set them in environment variables: - -.. envvar:: OS_SERVICE_TOKEN - - Your keystone administrative token - -.. envvar:: OS_SERVICE_ENDPOINT - - Your Identity API endpoint - -The command line options will override any environment variables set. - -If you already have accounts, you can use your OpenStack username and -password. You can do this with the :option:`--os-username`, -:option:`--os-password`. - -Keystone allows a user to be associated with one or more projects which are -historically called tenants. To specify the project for which you want to -authorize against, you may optionally specify a :option:`--os-tenant-id` or -:option:`--os-tenant-name`. - -Instead of using options, it is easier to just set them as environment -variables: - -.. envvar:: OS_USERNAME - - Your Keystone username. - -.. envvar:: OS_PASSWORD - - Your Keystone password. - -.. envvar:: OS_TENANT_NAME - - Name of Keystone project. - -.. envvar:: OS_TENANT_ID - - ID of Keystone Tenant. - -.. envvar:: OS_AUTH_URL - - The OpenStack API server URL. - -.. envvar:: OS_IDENTITY_API_VERSION - - The OpenStack Identity API version. - -.. envvar:: OS_CACERT - - The location for the CA truststore (PEM formatted) for this client. - -.. envvar:: OS_CERT - - The location for the keystore (PEM formatted) containing the public - key of this client. This keystore can also optionally contain the - private key of this client. - -.. envvar:: OS_KEY - - The location for the keystore (PEM formatted) containing the private - key of this client. This value can be empty if the private key is - included in the OS_CERT file. - -For example, in Bash you'd use:: - - export OS_USERNAME=yourname - export OS_PASSWORD=yadayadayada - export OS_TENANT_NAME=myproject - export OS_AUTH_URL=http(s)://example.com:5000/v2.0/ - export OS_IDENTITY_API_VERSION=2.0 - export OS_CACERT=/etc/keystone/yourca.pem - export OS_CERT=/etc/keystone/yourpublickey.pem - export OS_KEY=/etc/keystone/yourprivatekey.pem - - -OPTIONS -======= - -To get a list of available commands and options run:: - - keystone help - -To get usage and options of a command:: - - keystone help - - -EXAMPLES -======== - -Get information about endpoint-create command:: - - keystone help endpoint-create - -View endpoints of OpenStack services:: - - keystone catalog - -Create a 'service' project:: - - keystone tenant-create --name=service - -Create service user for nova:: - - keystone user-create --name=nova \ - --tenant_id= \ - --email=nova@nothing.com - -View roles:: - - keystone role-list - - -BUGS -==== - -Keystone client is hosted in Launchpad so you can view current bugs at -https://bugs.launchpad.net/python-keystoneclient/. diff --git a/docs/source/using-api-v2.rst b/docs/source/using-api-v2.rst deleted file mode 100644 index 9a31adda..00000000 --- a/docs/source/using-api-v2.rst +++ /dev/null @@ -1,117 +0,0 @@ -================= -The Client v2 API -================= - -Introduction -============ - -The main concepts in the Identity v2 API are: - - * tenants - * users - * roles - * services - * endpoints - -The client v2 API lets you query and make changes through -managers. For example, to manipulate tenants, you interact with a -``keystoneclient.v2_0.tenants.TenantManager`` object. - -You obtain access to managers through via attributes of the -``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` -attribute of the ``Client`` class is a tenant manager:: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> keystone.tenants.list() # List tenants - -You create a valid ``keystoneclient.v2_0.client.Client`` object by passing -authentication data to the constructor. Authentication and examples of common -tasks are provided below. - -You can generally expect that when the client needs to propagate an exception -it will raise an instance of subclass of -``keystoneclient.exceptions.ClientException`` - -Authenticating -============== - -There are two ways to authenticate against Keystone: - * against the admin endpoint with the admin token - * against the public endpoint with a username and password - -If you are an administrator, you can authenticate by connecting to the admin -endpoint and using the admin token (sometimes referred to as the service -token). The token is specified as the ``admin_token`` configuration option in -your keystone.conf config file, which is typically in /etc/keystone:: - - >>> from keystoneclient.v2_0 import client - >>> token = '012345SECRET99TOKEN012345' - >>> endpoint = 'http://192.168.206.130:35357/v2.0' - >>> keystone = client.Client(token=token, endpoint=endpoint) - -If you have a username and password, authentication is done against the -public endpoint. You must also specify a tenant that is associated with the -user:: - - >>> from keystoneclient.v2_0 import client - >>> username='adminUser' - >>> password='secreetword' - >>> tenant_name='openstackDemo' - >>> auth_url='http://192.168.206.130:5000/v2.0' - >>> keystone = client.Client(username=username, password=password, - ... tenant_name=tenant_name, auth_url=auth_url) - -Creating tenants -================ - -This example will create a tenant named *openStackDemo*:: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> keystone.tenants.create(tenant_name="openstackDemo", - ... description="Default Tenant", enabled=True) - - -Creating users -============== - -This example will create a user named *adminUser* with a password *secretword* -in the opoenstackDemo tenant. We first need to retrieve the tenant:: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> tenants = keystone.tenants.list() - >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0] - >>> my_user = keystone.users.create(name="adminUser", - ... password="secretword", - ... tenant_id=my_tenant.id) - -Creating roles and adding users -=============================== - -This example will create an admin role and add the *my_user* user to that -role, but only for the *my_tenant* tenant: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> role = keystone.roles.create('admin') - >>> my_tenant = ... - >>> my_user = ... - >>> keystone.roles.add_user_role(my_user, role, my_tenant) - -Creating services and endpoints -=============================== - -This example will create the service and corresponding endpoint for the -Compute service:: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> service = keystone.services.create(name="nova", service_type="compute", - ... description="Nova Compute Service") - >>> keystone.endpoints.create( - ... region="RegionOne", service_id=service.id, - ... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s", - ... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s", - ... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s") diff --git a/docs/source/using-api-v3.rst b/docs/source/using-api-v3.rst deleted file mode 100644 index 814f16f2..00000000 --- a/docs/source/using-api-v3.rst +++ /dev/null @@ -1,113 +0,0 @@ -================= -The Client v3 API -================= - -Introduction -============ - -The main concepts in the Identity v3 API are: - - * credentials - * domains - * endpoints - * groups - * policies - * projects - * role assignments - * roles - * services - * trusts - * users - -The :py:mod:`keystoneclient.v3.client` API lets you query and make changes -through ``managers``. For example, to manipulate a project (formerly -called tenant), you interact with a -:py:class:`keystoneclient.v3.projects.ProjectManager` object. - -You obtain access to managers through attributes of a -:py:class:`keystoneclient.v3.client.Client` object. For example, the -``projects`` attribute of a ``Client`` object is a projects manager:: - - >>> from keystoneclient.v3 import client - >>> keystone = client.Client(...) - >>> keystone.projects.list() # List projects - -While it is possible to instantiate a -:py:class:`keystoneclient.v3.client.Client` object (as done above for -clarity), the recommended approach is to use the discovery mechanism -provided by the :py:class:`keystoneclient.client.Client` class. The -appropriate class will be instantiated depending on the API versions -available:: - - >>> from keystoneclient import client - >>> keystone = - ... client.Client(auth_url='http://localhost:5000', ...) - >>> type(keystone) - - -One can force the use of a specific version of the API, either by -using the ``version`` keyword argument:: - - >>> from keystoneclient import client - >>> keystone = client.Client(auth_url='http://localhost:5000', - version=(2,), ...) - >>> type(keystone) - - >>> keystone = client.Client(auth_url='http://localhost:5000', - version=(3,), ...) - >>> type(keystone) - - -Or by specifying directly the specific API version authentication URL -as the auth_url keyword argument:: - - >>> from keystoneclient import client - >>> keystone = - ... client.Client(auth_url='http://localhost:5000/v2.0', ...) - >>> type(keystone) - - >>> keystone = - ... client.Client(auth_url='http://localhost:5000/v3', ...) - >>> type(keystone) - - -Upon successful authentication, a :py:class:`keystoneclient.v3.client.Client` -object is returned (when using the Identity v3 API). Authentication and -examples of common tasks are provided below. - -You can generally expect that when the client needs to propagate an -exception it will raise an instance of subclass of -``keystoneclient.exceptions.ClientException`` (see -:py:class:`keystoneclient.openstack.common.apiclient.exceptions.ClientException`) - -Authenticating -============== - -You can authenticate against Keystone using a username, a user domain -name (which will default to 'Default' if it is not specified) and a -password:: - - >>> from keystoneclient import client - >>> auth_url = 'http://localhost:5000' - >>> username = 'adminUser' - >>> user_domain_name = 'Default' - >>> password = 'secreetword' - >>> keystone = client.Client(auth_url=auth_url, version=(3,), - ... username=username, password=password, - ... user_domain_name=user_domain_name) - -You may optionally specify a domain or project (along with its project -domain name), to obtain a scoped token:: - - >>> from keystoneclient import client - >>> auth_url = 'http://localhost:5000' - >>> username = 'adminUser' - >>> user_domain_name = 'Default' - >>> project_name = 'demo' - >>> project_domain_name = 'Default' - >>> password = 'secreetword' - >>> keystone = client.Client(auth_url=auth_url, version=(3,), - ... username=username, password=password, - ... user_domain_name=user_domain_name, - ... project_name=project_name, - ... project_domain_name=project_domain_name) diff --git a/docs/source/using-sessions.rst b/docs/source/using-sessions.rst deleted file mode 100644 index 099dc701..00000000 --- a/docs/source/using-sessions.rst +++ /dev/null @@ -1,198 +0,0 @@ -============== -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 `_ -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.