diff --git a/doc/source/users/guides/identity.rst b/doc/source/users/guides/identity.rst index 47bda51ed..1cd0c4422 100644 --- a/doc/source/users/guides/identity.rst +++ b/doc/source/users/guides/identity.rst @@ -5,4 +5,107 @@ Before working with the Identity service, you'll need to create a connection to your OpenStack cloud by following the :doc:`connect` user guide. This will provide you with the ``conn`` variable used in the examples below. -.. TODO(thowe): Implement this guide +The OpenStack Identity service is the default identity management system for +OpenStack. The Identity service authentication process confirms the identity +of a user and an incoming request by validating a set of credentials that the +user supplies. Initially, these credentials are a user name and password or a +user name and API key. When the Identity service validates user credentials, +it issues an authentication token that the user provides in subsequent +requests. An authentication token is an alpha-numeric text string that enables +access to OpenStack APIs and resources. A token may be revoked at any time and +is valid for a finite duration. + +List Users +---------- +A **user** is a digital representation of a person, system, or service that +uses OpenStack cloud services. The Identity service validates that incoming +requests are made by the user who claims to be making the call. Users have +a login and can access resources by using assigned tokens. Users can be +directly assigned to a particular project and behave as if they are contained +in that project. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_users + +Full example: `identity resource list`_ + +List Credentials +---------------- +**Credentials** are data that confirms the identity of the user. For example, +user name and password, user name and API key, or an authentication token that +the Identity service provides. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_credentials + +Full example: `identity resource list`_ + +List Projects +------------- +A **project** is a container that groups or isolates resources or identity +objects. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_projects + +Full example: `identity resource list`_ + +List Domains +------------ +A **domain** is an Identity service API v3 entity and represents a collection +of projects and users that defines administrative boundaries for the management +of Identity entities. Users can be granted the administrator role for a domain. +A domain administrator can create projects, users, and groups in a domain and +assign roles to users and groups in a domain. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_domains + +Full example: `identity resource list`_ + +List Groups +----------- +A **group** is an Identity service API v3 entity and represents a collection of +users that are owned by a domain. A group role granted to a domain or project +applies to all users in the group. Adding users to, or removing users from, a +group respectively grants, or revokes, their role and authentication to the +associated domain or project. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_groups + +Full example: `identity resource list`_ + +List Services +------------- +A **service** is an OpenStack service, such as Compute, Object Storage, or +Image service, that provides one or more endpoints through which users can +access resources and perform operations. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_services + +Full example: `identity resource list`_ + +List Endpoints +-------------- +An **endpoint** is a network-accessible address, usually a URL, through which +you can access a service. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_endpoints + +Full example: `identity resource list`_ + +List Regions +------------ +A **region** is an Identity service API v3 entity and represents a general +division in an OpenStack deployment. You can associate zero or more +sub-regions with a region to make a tree-like structured hierarchy. + +.. literalinclude:: ../examples/identity/list.py + :pyobject: list_regions + +Full example: `identity resource list`_ + +.. _identity resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/identity/list.py diff --git a/examples/connect.py b/examples/connect.py index b5714041d..03e5f93b6 100644 --- a/examples/connect.py +++ b/examples/connect.py @@ -38,6 +38,8 @@ class Opts(object): def __init__(self, cloud_name='test_cloud', debug=False): self.cloud = cloud_name self.debug = debug + # Use identity v3 API for examples. + self.identity_api_version = '3' def _get_resource_value(resource_key, default): diff --git a/examples/identity/__init__.py b/examples/identity/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/examples/identity/list.py b/examples/identity/list.py new file mode 100644 index 000000000..5f3a2c5af --- /dev/null +++ b/examples/identity/list.py @@ -0,0 +1,73 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +""" +List resources from the Identity service. + +For a full guide see TODO(etoews):link to docs on developer.openstack.org +""" + + +def list_users(conn): + print("List Users:") + + for user in conn.identity.users(): + print(user) + + +def list_credentials(conn): + print("List Credentials:") + + for credential in conn.identity.credentials(): + print(credential) + + +def list_projects(conn): + print("List Projects:") + + for project in conn.identity.projects(): + print(project) + + +def list_domains(conn): + print("List Domains:") + + for domain in conn.identity.domains(): + print(domain) + + +def list_groups(conn): + print("List Groups:") + + for group in conn.identity.groups(): + print(group) + + +def list_services(conn): + print("List Services:") + + for service in conn.identity.services(): + print(service) + + +def list_endpoints(conn): + print("List Endpoints:") + + for endpoint in conn.identity.endpoints(): + print(endpoint) + + +def list_regions(conn): + print("List Regions:") + + for region in conn.identity.regions(): + print(region) diff --git a/openstack/tests/examples/test_identity.py b/openstack/tests/examples/test_identity.py new file mode 100644 index 000000000..f55dbe53d --- /dev/null +++ b/openstack/tests/examples/test_identity.py @@ -0,0 +1,38 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import unittest + +from examples import connect +from examples.identity import list as identity_list + + +class TestIdentity(unittest.TestCase): + """Test the identity examples + + The purpose of these tests is to ensure the examples run without erring + out. + """ + + @classmethod + def setUpClass(cls): + cls.conn = connect.create_connection_from_config() + + def test_identity(self): + identity_list.list_users(self.conn) + identity_list.list_credentials(self.conn) + identity_list.list_projects(self.conn) + identity_list.list_domains(self.conn) + identity_list.list_groups(self.conn) + identity_list.list_services(self.conn) + identity_list.list_endpoints(self.conn) + identity_list.list_regions(self.conn)