moved notes from README.rst into docs/architecture.rst

2 files changed, 179 insertions, 63 deletions

diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 21d9b895..b308a9e5 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -20,82 +20,184 @@ Keystone Architecture
 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.
 
-.........JOEEDIT..........
-Keystone has two major components: Authentication and a Service Catalog.
+------------
+The Services
+------------
 
-Authentication
---------------
+Keystone is organized as a group of services exposed on one or many endpoints.
+Many of these services are used in a combined fashion by the frontend, for
+example an authenticate call will validate user/tenant credentials with the
+Identity service and, upon success, create and return a token with the Token
+service.
 
-In providing a token-based authentication service for OpenStack, keystone
-has several major concepts:
 
-Tenant
-    A grouping used in OpenStack to contain relevant OpenStack services. A
-    tenant maps to a Nova "project-id", and in object storage, a tenant can
-    have multiple containers. Depending on the installation, a tenant can
-    represent a customer, account, organization, or project.
+Identity
+--------
 
-User
-    Represents an individual within OpenStack for the purposes of
-    authenticating them to OpenStack services. Users have credentials, and may
-    be assigned to one or more tenants. When authenticated, a token is
-    provided that is specific to a single tenant.
+The Identity service provides auth credential validation and data about Users,
+Tenants and Roles, as well as any associated metadata.
+
+In the basic case all this data is managed by the service, allowing the service
+to manage all the CRUD associated with the data.
+
+In other cases, this data is pulled, by varying degrees, from an authoritative
+backend service. An example of this would be when backending on LDAP. See
+`LDAP Backend` below for more details.
 
-Credentials
-    Password or other information that uniquely identifies a User to Keystone
-    for the purposes of providing a token.
 
 Token
-    A token is an arbitrary bit of text that is used to share authentication
-    with other OpenStack services so that Keystone can provide a central
-    location for authenticating users for access to OpenStack services. A
-    token may be "scoped" or "unscoped". A scoped token represents a user
-    authenticated to a Tenant, where an unscoped token represents just the
-    user.
-
-    Tokens are valid for a limited amount of time and may be revoked at any
-    time.
-
-Role
-    A role is a set of permissions to access and use specific operations for
-    a given user when applied to a tenant. Roles are logical groupings of
-    those permissions to enable common permissions to be easily grouped and
-    bound to users associated with a given tenant.
-
-Service Catalog
----------------
+-----
+
+The Token service validates and manages Tokens used for authenticating requests
+once a user/tenant's credentials have already been verified.
+
+
+Catalog
+-------
+
+The Catalog service provides an endpoint registry used for endpoint discovery.
+
+
+Policy
+------
+
+The Policy service provides a rule-based authorization engine and the
+associated rule management interface.
+
+----------
+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
+more data than they know what to do with and pass them on to a backend.
+
+There are a few main data types:
+
+ * **User**: has account credentials, is associated with one or more tenants
+ * **Tenant**: unit of ownership in openstack, contains one or more users
+ * **Role**: a first-class piece of metadata associated with many user-tenant pairs.
+ * **Token**: identifying credential associated with a user or user and tenant
+ * **Extras**: bucket of key-value metadata associated with a user-tenant pair.
+ * **Rule**: describes a set of requirements for performing an action.
+
+While the general data model allows a many-to-many relationship between Users
+and Tenants and a many-to-one relationship between Extras and User-Tenant pairs,
+the actual backend implementations take varying levels of advantage of that
+functionality.
+
+
+KVS Backend
+-----------
+
+A simple backend interface meant to be further backended on anything that can
+support primary key lookups, the most trivial implementation being an in-memory
+dict.
+
+Supports all features of the general data model.
+
+
+PAM Backend
+-----------
+
+Extra simple backend that uses the current system's PAM service to authenticate,
+providing a one-to-one relationship between Users and Tenants with the `root`
+User also having the 'admin' role.
+
+
+Templated Backend
+-----------------
+
+Largely designed for a common use case around service catalogs in the Keystone
+project, a Catalog backend that simply expands pre-configured templates to
+provide catalog data.
 
-Keystone also provides a list of REST API endpoints as a definitive list for
-an OpenStack installation. Key concepts include:
+Example paste.deploy config (uses $ instead of % to avoid ConfigParser's
+interpolation)::
 
-Service
-    An OpenStack service such as nova, swift, glance, or keystone. A service
-    may have one of more endpoints through which users can interact with
-    OpenStack services and resources.
+  [DEFAULT]
+  catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v2.0
+  catalog.RegionOne.identity.adminURL = http://localhost:$(public_port)s/v2.0
+  catalog.RegionOne.identity.internalURL = http://localhost:$(public_port)s/v2.0
+  catalog.RegionOne.identity.name = 'Identity Service'
+
+
+----------------
+Approach to CRUD
+----------------
+
+While it is expected that any "real" deployment at a large company will manage
+their users, tenants and other metadata in their existing user systems, a
+variety of CRUD operations are provided for the sake of development and testing.
+
+CRUD is treated as an extension or additional feature to the core feature set in
+that it is not required that a backend support it.
+
+
+----------------------------------
+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.
+
+For the purposes of Keystone Light there are only a couple levels of
+authorization being checked for:
+
+ * Require that the performing user is considered an admin.
+ * Require that the performing user matches the user being referenced.
+
+Other systems wishing to use the policy engine will require additional styles
+of checks and will possibly write completely custom backends. Backends included
+in Keystone Light are:
+
+
+Trivial True
+------------
+
+Allows all actions.
+
+
+Simple Match
+------------
+
+Given a list of matches to check for, simply verify that the credentials
+contain the matches. For example::
+
+  credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}
+
+  # An admin only call:
+  policy_api.can_haz(('is_admin:1',), credentials)
+
+  # An admin or owner call:
+  policy_api.can_haz(('is_admin:1', 'user_id:foo'),
+                     credentials)
+
+  # A netadmin call:
+  policy_api.can_haz(('roles:nova:netadmin',),
+                     credentials)
+
+
+Credentials are generally built from the user metadata in the 'extras' part
+of the Identity API. So, adding a 'role' to the user just means adding the role
+to the user metadata.
+
+
+Capability RBAC
+---------------
 
-Endpoint
-    A network accessible address (typically a URL) that represents the API
-    interface to an OpenStack service. Endpoints may also be grouped into
-    templates which represent a group of consumable OpenStack services
-    available across regions.
+(Not yet implemented.)
 
-Template
-    A collection of endpoints representing a set of consumable OpenStack
-    service endpoints.
+Another approach to authorization can be action-based, with a mapping of roles
+to which capabilities are allowed for that role. For example::
 
-Components of Keystone
-----------------------
+  credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}
 
-Keystone includes a command-line interface which interacts with the Keystone
-API for administrating keystone and related services.
+  # add a policy
+  policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',))
 
-* keystone - runs both keystone-admin and keystone-service
-* keystone-admin - the administrative API for manipulating keystone
-* keystone-service - the user oriented API for authentication
-* keystone-manage - the command line interface to manipulate keystone
+  policy_api.can_haz(('action:nova:add_network',), credentials)
 
-Keystone also includes WSGI middelware to provide authentication support
-for Nova and Swift.
 
-Keystone uses a built-in SQLite datastore - and may use an external LDAP
-service to authenticate users instead of using stored credentials.
+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 creds.
diff --git a/docs/source/developing.rst b/docs/source/developing.rst
index b19fec24..48ba2873 100644
--- a/docs/source/developing.rst
+++ b/docs/source/developing.rst
@@ -107,3 +107,17 @@ or the `OpenStack Integration Testing Project`_.
 .. _devstack: http://devstack.org/
 .. _OpenStack Continuous Integration Project: https://github.com/openstack/openstack-ci
 .. _OpenStack Integration Testing Project: https://github.com/openstack/tempest
+
+Building the Documentation
+==========================
+
+The documentation is all generated with Sphinx from within the docs directory.
+To generate the full set of HTML documentation:
+
+    cd docs
+    make autodoc
+    make html
+    make man
+
+the results are in the docs/build/html and docs/build/man directories
+respectively.