diff --git a/doc/source/index.rst b/doc/source/index.rst index 5d270a0..e7af0ea 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,10 +1,10 @@ -Python bindings to the OpenStack Identity API (Keystone) -======================================================== +Common Authentication Library for OpenStack Clients +=================================================== -This is a client for OpenStack Identity API. There's a Python API for -:doc:`Identity API v3 ` and :doc:`v2 ` (the -:mod:`keystoneauth` modules), and a command-line script (installed as -:doc:`keystone `). +Keystoneauth provides a standard way to do authentication and service requests +within the OpenStack ecosystem. It is designed for use in conjunction with the +existing OpenStack clients and for simplifying the process of writing new +clients. Contents: @@ -12,21 +12,10 @@ Contents: :maxdepth: 1 man/keystone - using-api-v3 using-sessions authentication-plugins - using-api-v2 api/modules -Related Identity Projects -========================= - -In addition to creating the Python client library, the Keystone team also -provides `Identity Service`_, as well as `WSGI Middleware`_. - -.. _`Identity Service`: http://docs.openstack.org/developer/keystone/ -.. _`WSGI Middleware`: http://docs.openstack.org/developer/keystonemiddleware/ - Contributing ============ diff --git a/doc/source/using-api-v2.rst b/doc/source/using-api-v2.rst deleted file mode 100644 index 5fb2c1c..0000000 --- a/doc/source/using-api-v2.rst +++ /dev/null @@ -1,117 +0,0 @@ -======================= -Using the V2 Client API -======================= - -Introduction -============ - -The main concepts in the Identity v2 API are: - - * tenants - * users - * roles - * services - * endpoints - -The V2 client API lets you query and make changes through -managers. For example, to manipulate tenants, you interact with a -``keystoneauth.v2_0.tenants.TenantManager`` object. - -You obtain access to managers via attributes of the -``keystoneauth.v2_0.client.Client`` object. For example, the ``tenants`` -attribute of the ``Client`` class is a tenant manager:: - - >>> from keystoneauth.v2_0 import client - >>> keystone = client.Client(...) - >>> keystone.tenants.list() # List tenants - -You create a valid ``keystoneauth.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 -``keystoneauth.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 keystoneauth.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 keystoneauth.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 keystoneauth.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 keystoneauth.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 keystoneauth.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 keystoneauth.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/doc/source/using-api-v3.rst b/doc/source/using-api-v3.rst deleted file mode 100644 index a51cdb1..0000000 --- a/doc/source/using-api-v3.rst +++ /dev/null @@ -1,140 +0,0 @@ -======================= -Using the V3 Client API -======================= - -Introduction -============ - -The main concepts in the Identity v3 API are: - - * :py:mod:`~keystoneauth.v3.credentials` - * :py:mod:`~keystoneauth.v3.domains` - * :py:mod:`~keystoneauth.v3.endpoints` - * :py:mod:`~keystoneauth.v3.groups` - * :py:mod:`~keystoneauth.v3.policies` - * :py:mod:`~keystoneauth.v3.projects` - * :py:mod:`~keystoneauth.v3.regions` - * :py:mod:`~keystoneauth.v3.role_assignments` - * :py:mod:`~keystoneauth.v3.roles` - * :py:mod:`~keystoneauth.v3.services` - * :py:mod:`~keystoneauth.v3.tokens` - * :py:mod:`~keystoneauth.v3.users` - -The :py:mod:`keystoneauth.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:`keystoneauth.v3.projects.ProjectManager` object. - -You obtain access to managers through attributes of a -:py:class:`keystoneauth.v3.client.Client` object. For example, the -``projects`` attribute of a ``Client`` object is a projects manager:: - - >>> from keystoneauth.v3 import client - >>> keystone = client.Client(...) - >>> keystone.projects.list() # List projects - -While it is possible to instantiate a -:py:class:`keystoneauth.v3.client.Client` object (as done above for -clarity), the recommended approach is to use the discovery mechanism -provided by the :py:class:`keystoneauth.client.Client` class. The -appropriate class will be instantiated depending on the API versions -available:: - - >>> from keystoneauth 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 keystoneauth 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 keystoneauth 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:`keystoneauth.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 -``keystoneauth.exceptions.ClientException`` (see -:py:class:`keystoneauth.openstack.common.apiclient.exceptions.ClientException`) - -Authenticating Using Sessions -============================= - -Instantiate a :py:class:`keystoneauth.v3.client.Client` using a -:py:class:`~keystoneauth.session.Session` to provide the authentication -plugin, SSL/TLS certificates, and other data:: - - >>> from keystoneauth.auth.identity import v3 - >>> from keystoneauth import session - >>> from keystoneauth.v3 import client - >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3', - ... user_id='myuserid', - ... password='mypassword', - ... project_id='myprojectid') - >>> sess = session.Session(auth=auth) - >>> keystone = client.Client(session=sess) - -For more information on Sessions refer to: `Using Sessions`_. - -.. _`Using Sessions`: using-sessions.html - -Non-Session Authentication (deprecated) -======================================= - -The *deprecated* way to authenticate is to pass the username, the user's domain -name (which will default to 'Default' if it is not specified), and a -password:: - - >>> from keystoneauth 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) - -A :py:class:`~keystoneauth.session.Session` should be passed to the Client -instead. Using a Session you're not limited to authentication using a username -and password but can take advantage of other more secure authentication -methods. - -You may optionally specify a domain or project (along with its project -domain name), to obtain a scoped token:: - - >>> from keystoneauth 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)