Move docs from key_terms to architecture

there is a lot of overlap between the two docs, let's have a
single doc instead.

also clean up the references to modules as they have bitrotted.

Change-Id: I05d30fa51052b875b1de94c4152036b1d0768793

doc/source/architecture.rst

@@ -14,6 +14,7 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+=====================
 Keystone Architecture
 =====================
 
@@ -21,9 +22,8 @@ Much of the design is precipitated from the expectation that the auth backends
 for most deployments will actually be shims in front of existing user systems.
 
 
-------------
+Services
-The Services
+========
-------------
 
 Keystone is organized as a group of internal services exposed on one or many
 endpoints. Many of these services are used in a combined fashion by the
@@ -35,8 +35,8 @@ token with the Token service.
 Identity
 --------
 
-The Identity service provides auth credential validation and data about users
+The Identity service provides auth credential validation and data about `users`
-and groups.
+and `groups`.
 
 In the basic case all this data is managed by the service, allowing the service
 to manage all the CRUD associated with the data.
@@ -45,24 +45,77 @@ In other cases, data is managed from an authoritative backend service. An
 example of this would be when backending on LDAP. The LDAP backend utilizes
 the LDAP server as the source for user and group data.
 
+Users
+^^^^^
+
+``Users`` represent an individual API consumer. A user itself must be owned by
+a specific domain, and hence all user names are **not** globally unique, but
+only unique to their domain.
+
+Groups
+^^^^^^
+
+``Groups`` are a container representing a collection of users. A group itself
+must be owned by a specific domain, and hence all group names are **not**
+globally unique, but only unique to their domain.
 
 Resource
 --------
 
-The Resource service provides data about projects and domains.
+The Resource service provides data about `projects` and `domains`.
 
-Like the Identity service, this data may either be managed directly by the
+Projects (Tenants)
-service or be pulled from a custom authoritative backend service.
+^^^^^^^^^^^^^^^^^^
+
+``Projects`` (known as ``Tenants`` in v2.0) represent the base unit of
+``ownership`` in OpenStack, in that all resources in OpenStack should be owned
+by a specific project.
+A project itself must be owned by a specific domain, and hence all project
+names are **not** globally unique, but unique to their domain.
+If the domain for a project is not specified, then it is added to the default
+domain.
+
+Domains
+^^^^^^^
+
+``Domains`` are a high-level container for projects, users and groups. Each is
+owned by exactly one domain. Each domain defines a namespace where an
+API-visible name attribute exists. keystone provides a default domain, aptly
+named 'Default'.
+
+In the Identity v3 API, the uniqueness of attributes is as follows:
+
+- Domain Name. Globally unique across all domains.
+
+- Role Name. Globally unique across all domains.
+
+- User Name. Unique within the owning domain.
+
+- Project Name. Unique within the owning domain.
+
+- Group Name. Unique within the owning domain.
+
+Due to their container architecture, domains may be used as a way to delegate
+management of OpenStack resources. A user in a domain may still access
+resources in another domain, if an appropriate assignment is granted.
 
 
 Assignment
 ----------
 
-The Assignment service provides data about roles and role assignments to the
+The Assignment service provides data about `roles` and `role assignments`.
-entities managed by the Identity and Resource services.  Again, like these two
-services, this data may either be managed directly by the Assignment service
-or be pulled from a custom authoritative backend service.
 
+Roles
+^^^^^
+
+``Roles`` dictate the level of authorization the end user can obtain. Roles
+can be granted at either the domain or project level. Role can be assigned to
+the individual user or at the group level. Role names are globally unique.
+
+Role Assignments
+^^^^^^^^^^^^^^^^
+
+A 3-tuple that has a ``Role``, a ``Resource`` and an ``Identity``.
 
 Token
 -----
@@ -84,9 +137,8 @@ The Policy service provides a rule-based authorization engine and the
 associated rule management interface.
 
 
-------------------------
 Application Construction
-------------------------
+========================
 
 Keystone is an HTTP front-end to several services. Like other OpenStack
 applications, this is done using python WSGI interfaces and applications are
@@ -96,8 +148,8 @@ of pipelines of WSGI middleware, such as:
 .. code-block:: ini
 
     [pipeline:api_v3]
-    pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth
+    pipeline = healthcheck cors sizelimit http_proxy_to_wsgi osprofiler url_normalize request_id build_auth_context token_auth json_body ec2_extension_v3 s3_extension service_v3
-    json_body ec2_extension_v3 s3_extension service_v3
+
 
 These in turn use a subclass of :mod:`keystone.common.wsgi.ComposingRouter` to
 link URLs to controllers (a subclass of
@@ -109,6 +161,7 @@ on the keystone configuration.
 * Assignment
 
  * :mod:`keystone.assignment.controllers.GrantAssignmentV3`
+ * :mod:`keystone.assignment.controllers.ImpliedRolesV3`
  * :mod:`keystone.assignment.controllers.ProjectAssignmentV3`
  * :mod:`keystone.assignment.controllers.TenantAssignment`
  * :mod:`keystone.assignment.controllers.Role`
@@ -122,10 +175,26 @@ on the keystone configuration.
 
 * Catalog
 
+ * :mod:`keystone.catalog.controllers.EndpointFilterV3Controller`
+ * :mod:`keystone.catalog.controllers.EndpointGroupV3Controller`
  * :mod:`keystone.catalog.controllers.EndpointV3`
+ * :mod:`keystone.catalog.controllers.ProjectEndpointGroupV3Controller`
  * :mod:`keystone.catalog.controllers.RegionV3`
  * :mod:`keystone.catalog.controllers.ServiceV3`
 
+* Credentials
+
+ * :mod:`keystone.contrib.ec2.controllers.Ec2ControllerV3`
+ * :mod:`keystone.credential.controllers.CredentialV3`
+
+* Federation
+
+ * :mod:`keystone.federation.controllers.IdentityProvider`
+ * :mod:`keystone.federation.controllers.FederationProtocol`
+ * :mod:`keystone.federation.controllers.MappingController`
+ * :mod:`keystone.federation.controllers.ServiceProvider`
+ * :mod:`keystone.federation.controllers.SAMLMetadataV3`
+
 * Identity
 
  * :mod:`keystone.identity.controllers.GroupV3`
@@ -138,19 +207,22 @@ on the keystone configuration.
 * Resource
 
  * :mod:`keystone.resource.controllers.DomainV3`
+ * :mod:`keystone.resource.controllers.DomainConfigV3`
  * :mod:`keystone.resource.controllers.ProjectV3`
 
-* Token
+* Revoke
 
- * :mod:`keystone.token.controllers.Auth`
+ * :mod:`keystone.revoke.controllers.RevokeController`
 
+* Trust
+
+ * :mod:`keystone.trust.controllers.TrustV3`
 
 .. _Paste: http://pythonpaste.org/
 
 
-----------------
 Service Backends
-----------------
+================
 
 Each of the services can be configured to use a backend to allow keystone to
 fit a variety of environments and needs. The backend for each service is
@@ -162,21 +234,23 @@ for any implementations, identifying the expected service implementations. The
 abstract base classes are stored in the service's backends directory as
 ``base.py``. The corresponding drivers for the services are:
 
-* :mod:`keystone.assignment.backends.base.AssignmentDriver`
+* :mod:`keystone.assignment.backends.base.AssignmentDriverBase`
-* :mod:`keystone.assignment.backends.base.RoleDriver`
+* :mod:`keystone.assignment.role_backends.base.RoleDriverBase`
-* :mod:`keystone.catalog.backends.base.CatalogDriver`
+* :mod:`keystone.auth.plugins.base.AuthMethodHandler`
-* :mod:`keystone.credential.backends.base.CredentialDriver`
+* :mod:`keystone.catalog.backends.base.CatalogDriverBase`
-* :mod:`keystone.endpoint_policy.backends.base.EndpointPolicyDriver`
+* :mod:`keystone.credential.backends.base.CredentialDriverBase`
-* :mod:`keystone.federation.backends.base.FederationDriver`
+* :mod:`keystone.endpoint_policy.backends.base.EndpointPolicyDriverBase`
-* :mod:`keystone.identity.backends.base.IdentityDriver`
+* :mod:`keystone.federation.backends.base.FederationDriverBase`
-* :mod:`keystone.identity.backends.base.MappingDriver`
+* :mod:`keystone.identity.backends.base.IdentityDriverBase`
-* :mod:`keystone.oauth1.backends.base.Oauth1Driver`
+* :mod:`keystone.identity.mapping_backends.base.MappingDriverBase`
-* :mod:`keystone.policy.backends.base.PolicyDriver`
+* :mod:`keystone.identity.shadow_backends.base.ShadowUsersDriverBase`
-* :mod:`keystone.resource.backends.base.DomainConfigDriver`
+* :mod:`keystone.oauth1.backends.base.Oauth1DriverBase`
-* :mod:`keystone.resource.backends.base.ResourceDriver`
+* :mod:`keystone.policy.backends.base.PolicyDriverBase`
-* :mod:`keystone.revoke.backends.base.RevokeDriver`
+* :mod:`keystone.resource.backends.base.ResourceDriverBase`
+* :mod:`keystone.resource.config_backends.base.DomainConfigDriverBase`
+* :mod:`keystone.revoke.backends.base.RevokeDriverBase`
 * :mod:`keystone.token.providers.base.Provider`
-* :mod:`keystone.trust.backends.base.TrustDriver`
+* :mod:`keystone.trust.backends.base.TrustDriverBase`
 
 If you implement a backend driver for one of the keystone services, you're
 expected to subclass from these classes.
@@ -190,7 +264,9 @@ project, a catalog backend that simply expands pre-configured templates to
 provide catalog data.
 
 Example paste.deploy config (uses $ instead of % to avoid ConfigParser's
-interpolation)::
+interpolation)
+
+.. code-block:: ini
 
     [DEFAULT]
     catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v2.0
@@ -199,9 +275,8 @@ interpolation)::
     catalog.RegionOne.identity.name = 'Identity Service'
 
 
-----------
 Data Model
-----------
+==========
 
 Keystone was designed from the ground up to be amenable to multiple styles of
 backends and as such many of the methods and data types will happily accept
@@ -223,9 +298,8 @@ and groups to projects and domains; the actual backend implementations take
 varying levels of advantage of that functionality.
 
 
-----------------
 Approach to CRUD
-----------------
+================
 
 While it is expected that any "real" deployment at a large company will manage
 their users and groups in their existing user systems, a variety of CRUD
@@ -237,9 +311,8 @@ backends for services that don't support the CRUD operations will raise a
 :mod:`keystone.exception.NotImplemented`.
 
 
-----------------------------------
 Approach to Authorization (Policy)
-----------------------------------
+==================================
 
 Various components in the system require that different actions are allowed
 based on whether the user is authorized to perform that action.
@@ -299,3 +372,116 @@ to which capabilities are allowed for that role. For example:
 
 In the backend this would look up the policy for 'action:nova:add_network' and
 then do what is effectively a 'Simple Match' style match against the credentials.
+
+Approach to Authentication
+==========================
+
+Keystone provides several authentication plugins that inherit from
+:mod:`keystone.auth.plugins.base`. The following is a list of available plugins.
+
+* :mod:`keystone.auth.plugins.external.Base`
+* :mod:`keystone.auth.plugins.mapped.Mapped`
+* :mod:`keystone.auth.plugins.oauth1.OAuth`
+* :mod:`keystone.auth.plugins.password.Password`
+* :mod:`keystone.auth.plugins.token.Token`
+* :mod:`keystone.auth.plugins.totp.TOTP`
+
+In the most basic plugin ``password``, two pieces of information are required
+to authenticate with keystone, a bit of ``Resource`` information and a bit of
+``Identity``.
+
+Take the following call POST data for instance:
+
+.. code-block:: javascript
+
+    {
+        "auth": {
+            "identity": {
+                "methods": [
+                    "password"
+                ],
+                "password": {
+                    "user": {
+                        "id": "0ca8f6",
+                        "password": "secretsecret"
+                    }
+                }
+            },
+            "scope": {
+                "project": {
+                    "id": "263fd9"
+                }
+            }
+        }
+    }
+
+The user (ID of 0ca8f6) is attempting to retrieve a token that is scoped to
+project (ID of 263fd9).
+
+To perform the same call with names instead of IDs, we now need to supply
+information about the domain. This is because usernames are only unique within
+a given domain, but user IDs are supposed to be unique across the deployment.
+Thus, the auth request looks like the following:
+
+.. code-block:: javascript
+
+    {
+        "auth": {
+            "identity": {
+                "methods": [
+                    "password"
+                ],
+                "password": {
+                    "user": {
+                        "domain": {
+                            "name": "acme"
+                        }
+                        "name": "userA",
+                        "password": "secretsecret"
+                    }
+                }
+            },
+            "scope": {
+                "project": {
+                    "domain": {
+                        "id": "1789d1"
+                    },
+                    "name": "project-x"
+                }
+            }
+        }
+    }
+
+For both the user and the project portion, we must supply either a domain ID
+or a domain name, in order to properly determine the correct user and project.
+
+Alternatively, if we wanted to represent this as environment variables for a
+command line, it would be:
+
+.. code-block:: bash
+
+    $ export OS_PROJECT_DOMAIN_ID=1789d1
+    $ export OS_USER_DOMAIN_NAME=acme
+    $ export OS_USERNAME=userA
+    $ export OS_PASSWORD=secretsecret
+    $ export OS_PROJECT_NAME=project-x
+
+Note that the project the user it attempting to access must be in the same
+domain as the user.
+
+What is Scope?
+--------------
+
+Scope is an overloaded term.
+
+In reference to authenticating, as seen above, scope refers to the portion
+of the POST data that dictates what ``Resource`` (project or domain) the user
+wants to access.
+
+In reference to tokens, scope refers to the effectiveness of a token,
+i.e.: a `project-scoped` token is only useful on the project it was initially
+granted for. A `domain-scoped` token may be used to perform domain-related
+function.
+
+In reference to users, groups, and projects, scope often refers to the domain
+that the entity is owned by. i.e.: a user in domain X is scoped to domain X.

doc/source/index.rst

@@ -53,9 +53,9 @@ Getting Started
     upgrading
     performance
     apache-httpd
+    architecture
     policy_mapping
     extensions
-    key_terms
     community
 
 Configuration
@@ -90,7 +90,6 @@ Developers Documentation
    devref/development.environment
    developing
    developing_drivers
-   architecture
    api_change_tutorial
    middlewarearchitecture
    http-api

doc/source/key_terms.rst

@@ -1,185 +0,0 @@
-=========
-Key Terms
-=========
-
-This document describes the different resource types that are available in
-OpenStack's Identity Service.
-
-Identity
-========
-
-The Identity portion of keystone includes ``Users`` and ``Groups``, and may be
-backed by SQL or more commonly LDAP.
-
-Users
------
-
-``Users`` represent an individual API consumer. A user itself must be owned by
-a specific domain, and hence all user names are **not** globally unique, but
-only unique to their domain.
-
-Groups
-------
-
-``Groups`` are a container representing a collection of users. A group itself
-must be owned by a specific domain, and hence all group names are **not**
-globally unique, but only unique to their domain.
-
-Resources
-=========
-
-The Resources portion of keystone includes ``Projects`` and ``Domains``, and
-are commonly stored in an SQL backend.
-
-Projects (Tenants)
-------------------
-
-``Projects`` (known as Tenants in v2.0) represent the base unit of
-``ownership`` in OpenStack, in that all resources in OpenStack should be owned
-by a specific project.
-A project itself must be owned by a specific domain, and hence all project
-names are **not** globally unique, but unique to their domain.
-If the domain for a project is not specified, then it is added to the default
-domain.
-
-Domains
--------
-
-``Domains`` are a high-level container for projects, users and groups. Each is
-owned by exactly one domain. Each domain defines a namespace where an
-API-visible name attribute exists. keystone provides a default domain, aptly
-named 'Default'.
-
-In the Identity v3 API, the uniqueness of attributes is as follows:
-
-- Domain Name. Globally unique across all domains.
-
-- Role Name. Globally unique across all domains.
-
-- User Name. Unique within the owning domain.
-
-- Project Name. Unique within the owning domain.
-
-- Group Name. Unique within the owning domain.
-
-Due to their container architecture, domains may be used as a way to delegate
-management of OpenStack resources. A user in a domain may still access
-resources in another domain, if an appropriate assignment is granted.
-
-
-Assignment
-==========
-
-Roles
------
-
-``Roles`` dictate the level of authorization the end user can obtain. Roles
-can be granted at either the domain or project level. Role can be assigned to
-the individual user or at the group level. Role names are globally unique.
-
-Role Assignments
-----------------
-
-A 3-tuple that has a ``Role``, a ``Resource`` and an ``Identity``.
-
-What's needed to Authenticate?
-==============================
-
-Two pieces of information are required to authenticate with keystone, a
-bit of ``Resource`` information and a bit of ``Identity``.
-
-Take the following call POST data for instance:
-
-.. code-block:: javascript
-
-    {
-        "auth": {
-            "identity": {
-                "methods": [
-                    "password"
-                ],
-                "password": {
-                    "user": {
-                        "id": "0ca8f6",
-                        "password": "secretsecret"
-                    }
-                }
-            },
-            "scope": {
-                "project": {
-                    "id": "263fd9"
-                }
-            }
-        }
-    }
-
-The user (ID of 0ca8f6) is attempting to retrieve a token that is scoped to
-project (ID of 263fd9).
-
-To perform the same call with names instead of IDs, we now need to supply
-information about the domain. This is because usernames are only unique within
-a given domain, but user IDs are supposed to be unique across the deployment.
-Thus, the auth request looks like the following:
-
-.. code-block:: javascript
-
-    {
-        "auth": {
-            "identity": {
-                "methods": [
-                    "password"
-                ],
-                "password": {
-                    "user": {
-                        "domain": {
-                            "name": "acme"
-                        }
-                        "name": "userA",
-                        "password": "secretsecret"
-                    }
-                }
-            },
-            "scope": {
-                "project": {
-                    "domain": {
-                        "id": "1789d1"
-                    },
-                    "name": "project-x"
-                }
-            }
-        }
-    }
-
-For both the user and the project portion, we must supply either a domain ID
-or a domain name, in order to properly determine the correct user and project.
-
-Alternatively, if we wanted to represent this as environment variables for a
-command line, it would be:
-
-.. code-block:: bash
-
-    $ export OS_PROJECT_DOMAIN_ID=1789d1
-    $ export OS_USER_DOMAIN_NAME=acme
-    $ export OS_USERNAME=userA
-    $ export OS_PASSWORD=secretsecret
-    $ export OS_PROJECT_NAME=project-x
-
-Note that the project the user it attempting to access must be in the same
-domain as the user.
-
-What is Scope?
-==============
-
-Scope is an overloaded term.
-
-In reference to authenticating, as seen above, scope refers to the portion
-of the POST data that dictates what ``Resource`` (project or domain) the user
-wants to access.
-
-In reference to tokens, scope refers to the effectiveness of a token,
-i.e.: a `project-scoped` token is only useful on the project it was initially
-granted for. A `domain-scoped` token may be used to perform domain-related
-function.
-
-In reference to users, groups, and projects, scope often refers to the domain
-that the entity is owned by. i.e.: a user in domain X is scoped to domain X.