moving in all the original docs from keystone

40 files changed, 5439 insertions, 0 deletions

diff --git a/docs/source/adminAPI_curl_examples.rst b/docs/source/adminAPI_curl_examples.rst
new file mode 100644
index 00000000..81f96c36
--- /dev/null
+++ b/docs/source/adminAPI_curl_examples.rst
@@ -0,0 +1,387 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+=============================
+Admin API Examples Using Curl
+=============================
+
+These examples assume a default port value of 35357, and depend on the
+``sampledata`` bundled with keystone.
+
+GET /
+=====
+
+Disover API version information, links to documentation (PDF, HTML, WADL),
+and supported media types::
+
+    $ curl http://0.0.0.0:35357
+
+or::
+
+    $ curl http://0.0.0.0:35357/v2.0/
+
+Returns::
+
+    {
+        "version":{
+            "id":"v2.0",
+            "status":"beta",
+            "updated":"2011-11-19T00:00:00Z",
+            "links":[
+                {
+                    "rel":"self",
+                    "href":"http://127.0.0.1:35357/v2.0/"
+                },
+                {
+                    "rel":"describedby",
+                    "type":"text/html",
+                    "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/content/"
+                },
+                {
+                    "rel":"describedby",
+                    "type":"application/pdf",
+                    "href":"http://docs.openstack.org/api/openstack-identity-service/2.0/identity-dev-guide-2.0.pdf"
+                },
+                {
+                    "rel":"describedby",
+                    "type":"application/vnd.sun.wadl+xml",
+                    "href":"http://127.0.0.1:35357/v2.0/identity-admin.wadl"
+                }
+            ],
+            "media-types":[
+                {
+                    "base":"application/xml",
+                    "type":"application/vnd.openstack.identity-v2.0+xml"
+                },
+                {
+                    "base":"application/json",
+                    "type":"application/vnd.openstack.identity-v2.0+json"
+                }
+            ]
+        }
+    }
+
+GET /extensions
+===============
+
+Discover the API extensions enabled at the endpoint::
+
+    $ curl http://0.0.0.0:35357/extensions
+
+Returns::
+
+    {
+        "extensions":{
+            "values":[]
+        }
+    }
+
+POST /tokens
+============
+
+Authenticate by exchanging credentials for an access token::
+
+    $ curl -d '{"auth":{"passwordCredentials":{"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens
+
+Returns::
+
+    {
+        "access":{
+            "token":{
+                "expires":"2012-02-05T00:00:00",
+                "id":"887665443383838",
+                "tenant":{
+                    "id":"1",
+                    "name":"customer-x"
+                }
+            },
+            "serviceCatalog":[
+                {
+                    "endpoints":[
+                    {
+                        "adminURL":"http://swift.admin-nets.local:8080/",
+                        "region":"RegionOne",
+                        "internalURL":"http://127.0.0.1:8080/v1/AUTH_1",
+                        "publicURL":"http://swift.publicinternets.com/v1/AUTH_1"
+                    }
+                    ],
+                    "type":"object-store",
+                    "name":"swift"
+                },
+                {
+                    "endpoints":[
+                    {
+                        "adminURL":"http://cdn.admin-nets.local/v1.1/1",
+                        "region":"RegionOne",
+                        "internalURL":"http://127.0.0.1:7777/v1.1/1",
+                        "publicURL":"http://cdn.publicinternets.com/v1.1/1"
+                    }
+                    ],
+                    "type":"object-store",
+                    "name":"cdn"
+                }
+            ],
+            "user":{
+                "id":"1",
+                "roles":[
+                    {
+                    "tenantId":"1",
+                    "id":"3",
+                    "name":"Member"
+                    }
+                ],
+                "name":"joeuser"
+            }
+        }
+    }
+
+.. note::
+
+    Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below.
+
+GET /tokens/{token_id}
+======================
+
+.. note::
+
+    This call refers to a token known to be valid, ``887665443383838`` in this case.
+
+Validate a token::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838
+
+If the token is valid, returns::
+
+    {
+        "access":{
+            "token":{
+                "expires":"2012-02-05T00:00:00",
+                "id":"887665443383838",
+                "tenant":{
+                    "id":"1",
+                    "name":"customer-x"
+                }
+            },
+            "user":{
+                "name":"joeuser",
+                "tenantName":"customer-x",
+                "id":"1",
+                "roles":[
+                    {
+                        "serviceId":"1",
+                        "id":"3",
+                        "name":"Member"
+                    }
+                ],
+                "tenantId":"1"
+            }
+        }
+    }
+
+HEAD /tokens/{token_id}
+=======================
+
+This is a high-performance variant of the GET call documented above, which
+by definition, returns no response body::
+
+    $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838
+
+... which returns ``200``, indicating the token is valid::
+
+    HTTP/1.1 200 OK
+    Content-Length: 0
+    Content-Type: None
+    Date: Tue, 08 Nov 2011 23:07:44 GMT
+
+GET /tokens/{token_id}/endpoints
+================================
+
+List all endpoints for a token::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints
+
+Returns::
+
+    {
+        "endpoints_links": [
+            {
+                "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'",
+                "rel": "next"
+            }
+        ],
+        "endpoints": [
+            {
+                "internalURL": "http://127.0.0.1:8080/v1/AUTH_1",
+                "name": "swift",
+                "adminURL": "http://swift.admin-nets.local:8080/",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "object-store",
+                "id": 1,
+                "publicURL": "http://swift.publicinternets.com/v1/AUTH_1"
+            },
+            {
+                "internalURL": "http://localhost:8774/v1.0",
+                "name": "nova_compat",
+                "adminURL": "http://127.0.0.1:8774/v1.0",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "compute",
+                "id": 2,
+                "publicURL": "http://nova.publicinternets.com/v1.0/"
+            },
+            {
+                "internalURL": "http://localhost:8774/v1.1",
+                "name": "nova",
+                "adminURL": "http://127.0.0.1:8774/v1.1",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "compute",
+                "id": 3,
+                "publicURL": "http://nova.publicinternets.com/v1.1/
+            },
+            {
+                "internalURL": "http://127.0.0.1:9292/v1.1/",
+                "name": "glance",
+                "adminURL": "http://nova.admin-nets.local/v1.1/",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "type": "image",
+                "id": 4,
+                "publicURL": "http://glance.publicinternets.com/v1.1/"
+            },
+            {
+                "internalURL": "http://127.0.0.1:7777/v1.1/1",
+                "name": "cdn",
+                "adminURL": "http://cdn.admin-nets.local/v1.1/1",
+                "region": "RegionOne",
+                "tenantId": 1,
+                "versionId": "1.1",
+                "versionList": "http://127.0.0.1:7777/",
+                "versionInfo": "http://127.0.0.1:7777/v1.1",
+                "type": "object-store",
+                "id": 5,
+                "publicURL": "http://cdn.publicinternets.com/v1.1/1"
+            }
+        ]
+    }
+
+GET /tenants
+============
+
+List all of the tenants in the system (requires an Admin ``X-Auth-Token``)::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants
+
+Returns::
+
+    {
+        "tenants_links": [],
+        "tenants": [
+            {
+                "enabled": false,
+                "description": "None",
+                "name": "project-y",
+                "id": "3"
+            },
+            {
+                "enabled": true,
+                "description": "None",
+                "name": "ANOTHER:TENANT",
+                "id": "2"
+            },
+            {
+                "enabled": true,
+                "description": "None",
+                "name": "customer-x",
+                "id": "1"
+            }
+        ]
+    }
+
+GET /tenants/{tenant_id}
+========================
+
+Retrieve information about a tenant, by tenant ID::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1
+
+Returns::
+
+    {
+        "tenant":{
+            "enabled":true,
+            "description":"None",
+            "name":"customer-x",
+            "id":"1"
+        }
+    }
+
+GET /tenants/{tenant_id}/users/{user_id}/roles
+==============================================
+
+List the roles a user has been granted on a tenant::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles
+
+Returns::
+
+    {
+        "roles_links":[],
+        "roles":[
+            {
+                "id":"3",
+                "name":"Member"
+            }
+        ]
+    }
+
+GET /users/{user_id}
+====================
+
+Retrieve information about a user, by user ID::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1
+
+Returns::
+
+    {
+        "user":{
+            "tenantId":"1",
+            "enabled":true,
+            "id":"1",
+            "name":"joeuser"
+        }
+    }
+
+GET /users/{user_id}/roles
+==========================
+
+Retrieve the roles granted to a user, given a user ID::
+
+    $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/4/roles
+
+Returns::
+
+    {
+        "roles_links":[],
+        "roles":[
+            {
+                "id":"2",
+                "name":"KeystoneServiceAdmin"
+            }
+        ]
+    }
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
new file mode 100644
index 00000000..8de45502
--- /dev/null
+++ b/docs/source/architecture.rst
@@ -0,0 +1,97 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+Keystone Architecture
+=====================
+
+Keystone has two major components: Authentication and a Service Catalog.
+
+Authentication
+--------------
+
+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.
+
+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.
+
+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
+---------------
+
+Keystone also provides a list of REST API endpoints as a definitive list for
+an OpenStack installation. Key concepts include:
+
+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.
+
+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.
+
+Template
+    A collection of endpoints representing a set of consumable OpenStack
+    service endpoints.
+
+Components of Keystone
+----------------------
+
+Keystone includes a command-line interface which interacts with the Keystone
+API for administrating keystone and related services.
+
+* 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
+
+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.
diff --git a/docs/source/backends.rst b/docs/source/backends.rst
new file mode 100644
index 00000000..b3fc2d91
--- /dev/null
+++ b/docs/source/backends.rst
@@ -0,0 +1,188 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+========
+Backends
+========
+
+Keystone supports multiple types of data stores for things like users, tenants, and
+tokens, including SQL, LDAP, and memcache.
+
+SQL
+===
+
+In the default backend configuration (SQL-only), Keystone depends on the following database tables.
+
+``users``
+---------
+
+``id``
+    Auto-incremented primary key.
+``name``
+    Unqiue username used for authentication via ``passwordCredentials``.
+``password``
+    Password used for authentication via ``passwordCredentials``.
+
+    Salted and hashed using ``passlib``.
+``email``
+    Email address (uniqueness is expected, but not enforced).
+``enabled``
+    If false, the user is unable to authenticate and the user's tokens will fail validation.
+``tenant_id``
+    Default tenant for the user.
+
+``tokens``
+----------
+
+``id``
+    The actual token provided after successful authentication (*plaintext*).
+``user_id``
+    References the user who owns the token.
+``tenant_id``
+    (*optional*) References the tenant the token is scoped to.
+``expires``
+    Indicates the expiration date of the token, after which the token can no longer be validated successfully.
+
+``tenants``
+-----------
+
+``id``
+    Auto-incremented primary key.
+``name``
+    Unique string identifying the tenant.
+``desc``
+    Description of the tenant.
+``enabled``
+    If false, users are unable to scope to the tenant.
+
+``roles``
+---------
+
+``id``
+    Auto-incremented primary key.
+``name``
+    Name of the role.
+
+    If the role is owned by a service, the role name **must** follow the convention::
+
+        serviceName:roleName
+``desc``
+    Description of the role.
+``service_id``
+    (*optional*) References the service that owns the role.
+
+``user_roles``
+--------------
+
+Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant).
+
+``id``
+    Auto-incremented primary key.
+``user_id``
+    References the user the role is granted to.
+``role_id``
+    References the granted role.
+``tenant_id``
+    (*optional*) References a tenant upon which this grant is applies.
+
+``services``
+------------
+
+``id``
+    Auto-incremented primary key.
+``name``
+    Unique name of the service.
+``type``
+    Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc).
+
+    This can also be extended to support non-core services. Extended services
+    follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``).
+``desc``
+    Describes the service.
+``owner_id``
+    (*optional*) References the user who owns the service.
+
+``credentials``
+---------------
+
+Currently only used for Amazon EC2 credential storage, this table is designed to support multiple
+types of credentials in the future.
+
+``id``
+    Auto-incremented primary key.
+``user_id``
+    References the user who owns the credential.
+``tenant_id``
+    References the tenant upon which the credential is valid.
+``types``
+    Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``).
+``key``
+    Amazon EC2 access key.
+``secret``
+    Amazon EC2 secret key.
+
+``endpoints``
+-------------
+
+Tenant-specific endpoints map endpoint templates to specific tenants.
+The ``tenant_id`` which appears here replaces the
+``%tenant_id%`` template variable in the specified endpoint template.
+
+``id``
+    Auto-incremented primary key.
+``tenant_id``
+    References the tenant this endpoint applies to.
+``endpoint_template_id``
+    The endpoint template to appear in the user's service catalog.
+
+``endpoint_templates``
+----------------------
+
+A multi-purpose model for the service catalog which can be:
+
+- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false.
+- Provided to all users as-is, when ``is_global`` is true.
+
+``id``
+    Auto-incremented primary key.
+``region``
+    Identifies the geographic region the endpoint is physically located within.
+``service_id``
+    TODO: References the service which owns the endpoints?
+``public_url``
+    Appears in the service catalog [#first]_.
+
+    Represents an endpoint available on the public Internet.
+``admin_url``
+    Appears in the service catalog [#first]_.
+
+    Users of this endpoint must have an Admin or ServiceAdmin role.
+``internal_url``
+    Appears in the service catalog [#first]_.
+
+    Represents an endpoint on an internal, unmetered network.
+``enabled``
+    If false, this endpoint template will not appear in the service catalog.
+``is_global``
+    If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users.
+``version_id``
+    Identifies the version of the API contract that endpoint supports.
+``version_list``
+    A URL which lists versions supported by the endpoint.
+``version_info``
+    A URL which provides detailed version info regarding the service.
+
+.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record.
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
new file mode 100644
index 00000000..a98d92f8
--- /dev/null
+++ b/docs/source/configuration.rst
@@ -0,0 +1,100 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+====================
+Configuring Keystone
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   keystone.conf
+   man/keystone-manage
+
+Once Keystone is installed, there are a number of configuration options
+available and potentially some initial data to create and set up.
+
+Sample data / Quick Setup
+=========================
+
+Default sampledata is provided for easy setup and testing in bin/sampeldata. To
+set up the sample data run the following command while Keystone is running::
+
+    $ ./bin/sampledata
+
+The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata`
+
+
+Keystone Configuration File
+===========================
+
+Most configuration is done via configuration files. The default files are
+in ``/etc/keystone.conf``
+
+When starting up a Keystone server, you can specify the configuration file to
+use (see :doc:`controllingservers`).
+If you do **not** specify a configuration file, keystone will look in the following
+directories for a configuration file, in order:
+
+* ``~/.keystone``
+* ``~/``
+* ``/etc/keystone``
+* ``/etc``
+
+The keystone configuration file should be named ``keystone.conf``.
+If you installed keystone via your operating system's
+package management system, it is likely that you will have sample
+configuration files installed in ``/etc/keystone``.
+
+In addition to this documentation page, you can check the
+``etc/keystone.conf`` sample configuration
+files distributed with keystone for example configuration files for each server
+application with detailed comments on what each options does.
+
+Sample Configuration Files
+--------------------------
+
+Keystone ships with sample configuration files in keystone/etc. These files are:
+
+1. keystone.conf
+
+    A standard configuration file for running keystone in stand-alone mode.
+    It has a set of default extensions loaded to support administering Keystone
+    over REST. It uses a local SQLite database.
+
+2. memcache.conf
+
+    A configuration that uses memcached for storing tokens (but still SQLite for all
+    other entities). This requires memcached running.
+
+3. ssl.conf
+
+    A configuration that runs Keystone with SSL (so all URLs are accessed over HTTPS).
+
+To run any of these configurations, use the `-c` option::
+
+    ./keystone -c ../etc/ssl.conf
+
+
+
+Usefule Links
+-------------
+
+For a sample configuration file with explanations of the settings, see :doc:`keystone.conf`
+
+For configuring an LDAP backend, see http://mirantis.blogspot.com/2011/08/ldap-identity-store-for-openstack.html
+
+For configuration settings of middleware components, see :doc:`middleware`
\ No newline at end of file
diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst
new file mode 100644
index 00000000..083c3ec5
--- /dev/null
+++ b/docs/source/configuringservices.rst
@@ -0,0 +1,333 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+==========================================
+Configuring Services to work with Keystone
+==========================================
+
+.. toctree::
+   :maxdepth: 1
+
+Once Keystone is installed and running, services need to be configured to work
+with it. These are the steps to configure a service to work with Keystone:
+
+1. Create or get credentials for the service to use
+
+  A set of credentials are needed for each service (they may be
+  shared if you chose to). Depending on the service, these credentials are
+  either a username and password or a long-lived token..
+
+2. Register the service, endpoints, roles and other entities
+
+  In order for a service to have it's endpoints and roles show in the service
+  catalog returned by Keystone, a service record needs to be added for the
+  service. Endpoints and roles associated with that service can then be created.
+
+  This can be done through the REST interface (using the OS-KSCATALOG extension)
+  or using keystone-manage.
+
+3. Install and configure middleware for the service to handle authentication
+
+  Clients making calls to the service will pass in an authentication token. The
+  Keystone middleware will look for and validate that token, taking the
+  appropriate action. It will also retrive additional information from the token
+  such as user name, id, tenant name, id, roles, etc...
+
+  The middleware will pass those data down to the service as headers. The
+  detailed description of this architecture is available here :doc:`middleware_architecture`
+
+Setting up credentials
+======================
+
+First admin user - bootstrapping
+--------------------------------
+
+For a default installation of Keystone, before you can use the REST API, you
+need to create your first initial user and grant that user the right to
+administer Keystone.
+
+For the keystone service itself, two
+Roles are pre-defined in the keystone configuration file
+(:doc:`keystone.conf`).
+
+    #Role that allows admin operations (access to all operations)
+    keystone-admin-role = Admin
+
+    #Role that allows acting as service (validate tokens, register service,
+    etc...)
+    keystone-service-admin-role = KeystoneServiceAdmin
+
+In order to create your first user, once Keystone is running use
+the `keystone-manage` command:
+
+    $ keystone-manage user add admin secrete
+    $ keystone-manage role add Admin
+    $ keystone-manage role add KeystoneServiceAdmin
+    $ keystone-manage role grant Admin admin
+    $ keystone-manage role grant KeystoneServiceAdmin admin
+
+This creates the `admin` user (with a password of `secrete`), creates
+two roles (`Admin` and `KeystoneServiceAdmin`), and assigns those roles to
+the `admin` user. From here, you should now have the choice of using the
+administrative API (as well as the :doc:`man/keystone-manage` commands) to
+further configure keystone. There are a number of examples of how to use
+that API at :doc:`adminAPI_curl_examples`.
+
+
+Setting up services
+===================
+
+Defining Services and Service Endpoints
+---------------------------------------
+
+Keystone also acts as a service catalog to let other OpenStack systems know
+where relevant API endpoints exist for OpenStack Services. The OpenStack
+Dashboard, in particular, uses this heavily - and this **must** be configured
+for the OpenStack Dashboard to properly function.
+
+Here's how we define the services::
+
+    $ keystone-manage service add nova compute "Nova Compute Service"
+    $ keystone-manage service add glance image "Glance Image Service"
+    $ keystone-manage service add swift storage "Swift Object Storage Service"
+    $ keystone-manage service add keystone identity "Keystone Identity Service"
+
+Once the services are defined, we create endpoints for them. Each service
+has three relevant URL's associated with it that are used in the command:
+
+* the public API URL
+* an administrative API URL
+* an internal URL
+
+The "internal URL" is an endpoint the generally offers the same API as the
+public URL, but over a high-bandwidth, low-latency, unmetered (free) network.
+You would use that to transfer images from nova to glance for example, and
+not the Public URL which would go over the internet and be potentially chargeable.
+
+The "admin URL" is for administering the services and is not exposed or accessible
+to customers without the apporpriate privileges.
+
+An example of setting up the endpoint for Nova::
+
+    $ keystone-manage endpointTemplates add RegionOne nova \
+    http://nova-api.mydomain:8774/v1.1/%tenant_id% \
+    http://nova-api.mydomain:8774/v1.1/%tenant_id% \
+    http://nova-api.mydomain:8774/v1.1/%tenant_id% \
+    1 1
+
+Glance::
+
+    $ keystone-manage endpointTemplates add RegionOne glance \
+    http://glance.mydomain:9292/v1 \
+    http://glance.mydomain:9292/v1 \
+    http://glance.mydomain:9292/v1 \
+    1 1
+
+Swift::
+
+    $ keystone-manage endpointTemplates add RegionOne swift \
+    http://swift.mydomain:8080/v1/AUTH_%tenant_id% \
+    http://swift.mydomain:8080/v1.0/ \
+    http://swift.mydomain:8080/v1/AUTH_%tenant_id% \
+    1 1
+
+And setting up an endpoint for Keystone::
+
+    $ keystone-manage endpointTemplates add RegionOne keystone \
+    http://keystone.mydomain:5000/v2.0 \
+    http://keystone.mydomain:35357/v2.0 \
+    http://keystone.mydomain:5000/v2.0 \
+    1 1
+
+
+Defining an Administrative Service Token
+----------------------------------------
+
+An Administrative Service Token is a bit of arbitrary text which is configured
+in Keystone and used (typically configured into) Nova, Swift, Glance, and any
+other OpenStack projects, to be able to use Keystone services.
+
+This token is an arbitrary text string, but must be identical between Keystone
+and the services using Keystone. This token is bound to a user and tenant as
+well, so those also need to be created prior to setting it up.
+
+The *admin* user was set up above, but we haven't created a tenant for that
+user yet::
+
+    $ keystone-manage tenant add admin
+
+and while we're here, let's grant the admin user the 'Admin' role to the
+'admin' tenant::
+
+    $ keystone-manage role add Admin
+    $ keystone-manage role grant Admin admin admin
+
+Now we can create a service token::
+
+    $ keystone-manage token add 999888777666 admin admin 2015-02-05T00:00
+
+This creates a service token of '999888777666' associated to the admin user,
+admin tenant, and expires on February 5th, 2015. This token will be used when
+configuring Nova, Glance, or other OpenStack services.
+
+Securing Communications with SSL
+--------------------------------
+
+To encrypt traffic between services and Keystone, see :doc:`ssl`
+
+
+Setting up OpenStack users
+==========================
+
+Creating Tenants, Users, and Roles
+----------------------------------
+
+Let's set up a 'demo' tenant::
+
+    $ keystone-manage tenant add demo
+
+And add a 'demo' user with the password 'guest'::
+
+    $ keystone-manage user add demo guest
+
+Now let's add a role of "Member" and grant 'demo' user that role
+as it pertains to the tenant 'demo'::
+
+    $ keystone-manage role add Member
+    $ keystone-manage role grant Member demo demo
+
+Let's also add the admin user as an Admin role to the demo tenant::
+
+    $ keystone-manage role grant Admin admin demo
+
+Creating EC2 credentials
+------------------------
+
+To add EC2 credentials for the `admin` and `demo` accounts::
+
+    $ keystone-manage credentials add admin EC2 'admin' 'secretpassword'
+    $ keystone-manage credentials add admin EC2 'demo' 'secretpassword'
+
+If you have a large number of credentials to create, you can put them all
+into a single large file and import them using :doc:`man/keystone-import`. The
+format of the document looks like::
+
+    credentials add admin EC2 'username' 'password'
+    credentials add admin EC2 'username' 'password'
+
+Then use::
+
+    $ keystone-import `filename`
+
+
+Setting Up Middleware
+=====================
+
+Keystone Auth-Token Middleware
+--------------------------------
+
+The Keystone auth_token middleware is a WSGI component that can be inserted in
+the WSGI pipeline to handle authenticating tokens with Keystone. See :doc:`middleware`
+for details on middleware and configuration parameters.
+
+
+Configuring Nova to use Keystone
+--------------------------------
+
+To configure Nova to use Keystone for authentication, the Nova API service
+can be run against the api-paste file provided by Keystone. This is most
+easily accomplished by setting the `--api_paste_config` flag in nova.conf to
+point to `examples/paste/nova-api-paste.ini` from Keystone. This paste file
+included references to the WSGI authentication middleware provided with the
+keystone installation.
+
+When configuring Nova, it is important to create a admin service token for
+the service (from the Configuration step above) and include that as the key
+'admin_token' in the nova-api-paste.ini. See the documented
+:doc:`nova-api-paste` file for references.
+
+Configuring Swift to use Keystone
+---------------------------------
+
+Similar to Nova, swift can be configured to use Keystone for authentication
+rather than it's built in 'tempauth'.
+
+1. Add a service endpoint for Swift to Keystone
+
+2. Configure the paste file for swift-proxy (`/etc/swift/swift-proxy.conf`)
+
+3.  Reconfigure Swift's proxy server to use Keystone instead of TempAuth.
+    Here's an example `/etc/swift/proxy-server.conf`::
+
+        [DEFAULT]
+        bind_port = 8888
+        user = <user>
+
+        [pipeline:main]
+        pipeline = catch_errors cache keystone proxy-server
+
+        [app:proxy-server]
+        use = egg:swift#proxy
+        account_autocreate = true
+
+        [filter:keystone]
+        use = egg:keystone#tokenauth
+        auth_protocol = http
+        auth_host = 127.0.0.1
+        auth_port = 35357
+        admin_token = 999888777666
+        delay_auth_decision = 0
+        service_protocol = http
+        service_host = 127.0.0.1
+        service_port = 8100
+        service_pass = dTpw
+        cache = swift.cache
+
+        [filter:cache]
+        use = egg:swift#memcache
+        set log_name = cache
+
+        [filter:catch_errors]
+        use = egg:swift#catch_errors
+
+   Note that the optional "cache" property in the keystone filter allows any
+   service (not just Swift) to register its memcache client in the WSGI
+   environment.  If such a cache exists, Keystone middleware will utilize it 
+   to store validated token information, which could result in better overall
+   performance.
+
+4. Restart swift
+
+5. Verify that keystone is providing authentication to Swift
+
+Use `swift` to check everything works (note: you currently have to create a
+container or upload something as your first action to have the account
+created; there's a Swift bug to be fixed soon)::
+
+    $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete post container
+    $ swift -A http://127.0.0.1:5000/v1.0 -U joeuser -K secrete stat -v
+    StorageURL: http://127.0.0.1:8888/v1/AUTH_1234
+    Auth Token: 74ce1b05-e839-43b7-bd76-85ef178726c3
+    Account: AUTH_1234
+    Containers: 1
+    Objects: 0
+    Bytes: 0
+    Accept-Ranges: bytes
+    X-Trans-Id: tx25c1a6969d8f4372b63912f411de3c3b
+
+.. WARNING::
+    Keystone currently allows any valid token to do anything with any account.
+
diff --git a/docs/source/controllingservers.rst b/docs/source/controllingservers.rst
new file mode 100644
index 00000000..ba8bfc06
--- /dev/null
+++ b/docs/source/controllingservers.rst
@@ -0,0 +1,288 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+============================
+Controlling Keystone Servers
+============================
+
+This section describes the ways to start, stop, and reload the Keystone
+services.
+
+Keystone Services
+-----------------
+
+Keystone can serve a number of REST APIs and extensions on different TCP/IP
+ports.
+
+The Service API
+~~~~~~~~~~~~~~~~
+
+The core Keystone
+API is primarily a read-only API (the only write operation being POST /tokens
+which authenticates a client, and returns a generated token).
+This API is sufficient to use OpenStack if all users, roles, endpoints already
+exist. This is often the case if Keystone is using an enterprise backend
+and the backend is managed through other entperrise tools and business
+processes. This core API is called the Service API and can be started
+separately from the more complete Admin API. By default, Keystone runs
+this API on port 5000. This is not an IANA assigned port and should not
+be relied upon (instead, use the Admin API on port 35357 to look for
+this endpoint - more on this later)
+
+The Service API is started using this command in the /bin directory::
+
+    $ ./keystone-auth
+
+The Admin API
+~~~~~~~~~~~~~
+
+Inn order for Keystone to be a fully functional service out of the box,
+API extensions that provide full CRUD operations is included with Keystone.
+This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2
+extensions. These extensions provide a full set of create, read, update, delete
+(CRUD) operations that can be used to manage Keystone objects through REST
+calls. By default Keystone runs this full REST API on TCP/IP port 35357
+(assigned by IANA to Keystone).
+
+The Admin API is started using this command in the /bin directory::
+
+    $ ./keystone-admin
+
+
+Both APIs can be loaded simultaneously (on different ports) using this command::
+
+    $ ./keystone
+
+Starting a server
+-----------------
+
+There are two ways to start a Keystone service (either the Service API server
+or the Admin API server):
+
+- Manually calling the server program
+- Using the ``keystone-control`` server daemon wrapper program
+
+We recommend using the second way in production and the first for development
+and debugging.
+
+Manually starting the server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first is by directly calling the server program, passing in command-line
+options and a single argument for a ``paste.deploy`` configuration file to
+use when configuring the server application.
+
+.. note::
+
+  Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy``
+  configuration files that you can copy to a standard configuration directory and
+  adapt for your own uses.
+
+If you do `not` specify a configuration file on the command line, Keystone will
+do its best to locate a configuration file in one of the
+following directories, stopping at the first config file it finds:
+
+- ``$CWD``
+- ``~/.keystone``
+- ``~/``
+- ``/etc/keystone``
+- ``/etc``
+
+The filename that is searched for is ``keystone.conf`` by default.
+
+If no configuration file is found, you will see an error, like::
+
+    $ keystone
+    ERROR: Unable to locate any configuration file. Cannot load application keystone
+
+Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell::
+
+    $ ./keystone -d
+    keystone-legacy-auth: INFO     **************************************************
+    keystone-legacy-auth: INFO     Configuration options gathered from config file:
+    keystone-legacy-auth: INFO     /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf
+    keystone-legacy-auth: INFO     ================================================
+    keystone-legacy-auth: INFO     admin_host           0.0.0.0
+    keystone-legacy-auth: INFO     admin_port           35357
+    keystone-legacy-auth: INFO     admin_ssl            False
+    keystone-legacy-auth: INFO     backends             keystone.backends.sqlalchemy
+    keystone-legacy-auth: INFO     ca_certs             /etc/keystone/ssl/certs/ca.pem
+    keystone-legacy-auth: INFO     cert_required        True
+    keystone-legacy-auth: INFO     certfile             /etc/keystone/ssl/certs/keystone.pem
+    keystone-legacy-auth: INFO     debug                True
+    keystone-legacy-auth: INFO     default_store        sqlite
+    keystone-legacy-auth: INFO     extensions           osksadm,oskscatalog,hpidm
+    keystone-legacy-auth: INFO     hash-password        True
+    keystone-legacy-auth: INFO     keyfile              /etc/keystone/ssl/private/keystonekey.pem
+    keystone-legacy-auth: INFO     keystone-admin-role  Admin
+    keystone-legacy-auth: INFO     keystone-service-admin-role KeystoneServiceAdmin
+    keystone-legacy-auth: INFO     log_dir              .
+    keystone-legacy-auth: INFO     log_file             keystone.log
+    keystone-legacy-auth: INFO     service-header-mappings {
+    'nova' : 'X-Server-Management-Url',
+    'swift' : 'X-Storage-Url',
+    'cdn' : 'X-CDN-Management-Url'}
+    keystone-legacy-auth: INFO     service_host         0.0.0.0
+    keystone-legacy-auth: INFO     service_port         5000
+    keystone-legacy-auth: INFO     service_ssl          False
+    keystone-legacy-auth: INFO     verbose              False
+    keystone-legacy-auth: INFO     **************************************************
+    passlib.registry: INFO     registered crypt handler 'sha512_crypt': <class 'passlib.handlers.sha2_crypt.sha512_crypt'>
+    Starting the RAX-KEY extension
+    Starting the Legacy Authentication component
+    admin       : INFO     **************************************************
+    admin       : INFO     Configuration options gathered from config file:
+    admin       : INFO     /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf
+    admin       : INFO     ================================================
+    admin       : INFO     admin_host           0.0.0.0
+    admin       : INFO     admin_port           35357
+    admin       : INFO     admin_ssl            False
+    admin       : INFO     backends             keystone.backends.sqlalchemy
+    admin       : INFO     ca_certs             /etc/keystone/ssl/certs/ca.pem
+    admin       : INFO     cert_required        True
+    admin       : INFO     certfile             /etc/keystone/ssl/certs/keystone.pem
+    admin       : INFO     debug                True
+    admin       : INFO     default_store        sqlite
+    admin       : INFO     extensions           osksadm,oskscatalog,hpidm
+    admin       : INFO     hash-password        True
+    admin       : INFO     keyfile              /etc/keystone/ssl/private/keystonekey.pem
+    admin       : INFO     keystone-admin-role  Admin
+    admin       : INFO     keystone-service-admin-role KeystoneServiceAdmin
+    admin       : INFO     log_dir              .
+    admin       : INFO     log_file             keystone.log
+    admin       : INFO     service-header-mappings {
+    'nova' : 'X-Server-Management-Url',
+    'swift' : 'X-Storage-Url',
+    'cdn' : 'X-CDN-Management-Url'}
+    admin       : INFO     service_host         0.0.0.0
+    admin       : INFO     service_port         5000
+    admin       : INFO     service_ssl          False
+    admin       : INFO     verbose              False
+    admin       : INFO     **************************************************
+    Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf
+    Service API (ssl=False) listening on 0.0.0.0:5000
+    Admin API (ssl=False) listening on 0.0.0.0:35357
+    eventlet.wsgi.server: DEBUG    (77128) wsgi starting up on http://0.0.0.0:5000/
+    eventlet.wsgi.server: DEBUG    (77128) wsgi starting up on http://0.0.0.0:35357/
+
+    $ sudo keystone-registry keystone-registry.conf &
+    jsuh@mc-ats1:~$ 2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images")
+    2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] ()
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0)
+    2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties")
+    2011-04-13 14:51:16     INFO [sqlalchemy.engine.base.Engine.0x...feac] ()
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0)
+    2011-04-13 14:51:16    DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0)
+
+    $ ps aux | grep keystone
+    myuser    77148   0.0  0.0  2434892    472 s012  U+   11:50AM   0:00.01 grep keystone
+    myuser    77128   0.0  0.6  2459356  25360 s011  S+   11:48AM   0:00.82 python ./keystone -d
+
+Simply supply the configuration file as the first argument
+and then any common options
+you want to use (``-d`` was used above to show some of the debugging
+output that the server shows when starting up. Call the server program
+with ``--help`` to see all available options you can specify on the
+command line.)
+
+Using ``--trace-calls`` is useful for showing a trace of calls (errors in red)
+for debugging.
+
+For more information on configuring the server via the ``paste.deploy``
+configuration files, see the section entitled
+:doc:`Configuring Keystone <configuration>`
+
+Note that the server `daemonizes` itself by using the standard
+shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend
+using the ``keystone-control`` server daemon wrapper for daemonizing. See below
+for more details on daemonization with ``keystone-control``.
+
+Using ``keystone-control`` to start the server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The second way to start up a Keystone server is to use the ``keystone-control``
+program. ``keystone-control`` is a wrapper script that allows the user to
+start, stop, restart, and reload the other Keystone server programs in
+a fashion that is more conducive to automation and scripting.
+
+Servers started via the ``keystone-control`` program are always `daemonized`,
+meaning that the server program process runs in the background.
+
+To start a Keystone server with ``keystone-control``, simply call
+``keystone-control`` with a server and the word "start", followed by
+any command-line options you wish to provide. Start the server with ``keystone-control``
+in the following way::
+
+    $ sudo keystone-control <SERVER> start [CONFPATH]
+
+.. note::
+
+    You must use the ``sudo`` program to run ``keystone-control`` currently, as the
+    pid files for the server programs are written to /var/run/keystone/
+
+Start the ``keystone-admin`` server using ``keystone-control``::
+
+    $ sudo keystone-control admin start
+    Starting keystone-admin with /etc/keystone.conf
+
+The same ``paste.deploy`` configuration files are used by ``keystone-control``
+to start the Keystone server programs, and you can specify (as the example above
+shows) a configuration file when starting the server.
+
+Stopping a server
+-----------------
+
+If you started a Keystone server manually and did not use the ``&`` backgrounding
+function, simply send a terminate signal to the server process by typing
+``Ctrl-C``
+
+If you started the Keystone server using ``keystone-control``, you can
+use the ``keystone-control`` program to stop it::
+
+    $ sudo keystone-control <SERVER> stop
+
+For example::
+
+    $ sudo keystone-control auth stop
+    Stopping keystone-auth  pid: 77401  signal: 15
+
+Restarting a server
+-------------------
+
+Restart the Keystone server using ``keystone-control``::
+
+    $ sudo keystone-control admin restart /etc/keystone.conf
+    Stopping keystone-admin  pid: 77401  signal: 15
+    Starting keystone-admin with /etc/keystone.conf
diff --git a/docs/source/endpoints.rst b/docs/source/endpoints.rst
new file mode 100644
index 00000000..84a42e09
--- /dev/null
+++ b/docs/source/endpoints.rst
@@ -0,0 +1,430 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+================================
+Endpoints and Endpoint Templates
+================================
+
+.. toctree::
+   :maxdepth: 1
+
+What are Endpoints?
+-------------------
+
+Simply, endpoints are URLs that point to OpenStack services. When you
+authenticate to Keystone you get back a token which has a service catalog in
+it. The service catalog is basically a list of the OpenStack services that
+you have access to and the URLs you can use to get to them; their endpoints.
+
+Here is an example response from Keystone when you authenticate::
+
+    {
+        "access":{
+            "token":{
+                "id":"ab48a9efdfedb23ty3494",
+                "expires":"2010-11-01T03:32:15-05:00",
+                "tenant":{
+                    "id": "t1000",
+                    "name": "My Project"
+                }
+            },
+            "user":{
+                "id":"u123",
+                "name":"jqsmith",
+                "roles":[{
+                        "id":"100",
+                        "name":"compute:admin"
+                    },
+                    {
+                        "id":"101",
+                        "name":"object-store:admin",
+                        "tenantId":"t1000"
+                    }
+                ],
+                "roles_links":[]
+            },
+            "serviceCatalog":[{
+                    "name":"Nova",
+                    "type":"compute",
+                    "endpoints":[{
+                            "tenantId":"t1000",
+                            "publicURL":"https://compute.north.host.com/v1/t1000",
+                            "internalURL":"https://compute.north.internal/v1/t1000",
+                            "region":"North",
+                            "versionId":"1",
+                            "versionInfo":"https://compute.north.host.com/v1/",
+                            "versionList":"https://compute.north.host.com/"
+                        },
+                        {
+                            "tenantId":"t1000",
+                            "publicURL":"https://compute.north.host.com/v1.1/t1000",
+                            "internalURL":"https://compute.north.internal/v1.1/t1000",
+                            "region":"North",
+                            "versionId":"1.1",
+                            "versionInfo":"https://compute.north.host.com/v1.1/",
+                            "versionList":"https://compute.north.host.com/"
+                        }
+                    ],
+                    "endpoints_links":[]
+                },
+                {
+                    "name":"Swift",
+                    "type":"object-store",
+                    "endpoints":[{
+                            "tenantId":"t1000",
+                            "publicURL":"https://storage.north.host.com/v1/t1000",
+                            "internalURL":"https://storage.north.internal/v1/t1000",
+                            "region":"North",
+                            "versionId":"1",
+                            "versionInfo":"https://storage.north.host.com/v1/",
+                            "versionList":"https://storage.north.host.com/"
+                        },
+                        {
+                            "tenantId":"t1000",
+                            "publicURL":"https://storage.south.host.com/v1/t1000",
+                            "internalURL":"https://storage.south.internal/v1/t1000",
+                            "region":"South",
+                            "versionId":"1",
+                            "versionInfo":"https://storage.south.host.com/v1/",
+                            "versionList":"https://storage.south.host.com/"
+                        }
+                    ]
+                },
+                {
+                    "name":"DNS-as-a-Service",
+                    "type":"dnsextension:dns",
+                    "endpoints":[{
+                            "tenantId":"t1000",
+                            "publicURL":"https://dns.host.com/v2.0/t1000",
+                            "versionId":"2.0",
+                            "versionInfo":"https://dns.host.com/v2.0/",
+                            "versionList":"https://dns.host.com/"
+                        }
+                    ]
+                }
+            ]
+        }
+    }
+
+Note the following about this response:
+
+#. There are two endpoints given to the Nova compute service. The only
+   difference between them is the version (1.0 vs. 1.1). This allows for code
+   written to look for the version 1.0 endpoint to still work even after the 1.1
+   version is released.
+
+#. There are two endpoints for the Swift object-store service. The difference
+   between them is they are in different regions (North and South).
+
+#. Note the DNS service is global; it does not have a Region. Also, since DNS
+   is not a core OpenStack service, the endpoint type is "dnsextension:dns"
+   showing it is coming from an extension to the Keystone service.
+
+#. The Region, Tenant, and versionId are listed under the endpoint. You do not
+   (and should not) have to parse those out of the URL. In fact, they may not be
+   embedded in the URL if the service developer so chooses.
+
+
+What do the fields in an Endpoint mean?
+---------------------------------------
+
+The schema definition for an endpoint is in endpoints.xsd under
+keystone/content/common/xsd in the Keystone code repo. The fields are:
+
+id
+    A unique ID for the endpoint.
+
+type
+    The OpenStack-registered type (ex. 'compute', 'object-store', 'image service')
+    This can also be extended using the OpenStack Extension mechanism to support
+    non-core services. Extended services will be in the form ``extension:type``
+    (e.g. ``dnsextension:dns``)
+
+name
+    This can be anything that the operator of OpenStack chooses. It could be a
+    brand or marketing name (ex. Rackspace Cloud Servers).
+
+region
+    This is a string that identifies the region where this endpoint exists.
+    Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or
+    'Data Center 1', 'Data Center 2'.
+    The list of regions and what a region means is decided by the operator. The
+    spec treats them as opaque strings.
+
+publicURL
+    This is the URL to use to access that endpoint over the internet.
+
+internalURL
+    This is the URL to use to communicate between services. This is genenrally
+    a way to communicate between services over a high bandwidth, low latency,
+    unmetered (free, no bandwidth charges) network. An example would be if you
+    want to access a swift cluster from inside your Nova VMs and want to make
+    sure the communication stays local and does not go over a public network
+    and rack up your bandwidth charges.
+
+adminURL
+    This is the URL to use to administer the service. In Keystone, this URL
+    is only shown to users with the appropriate rights.
+
+tenantId
+    If an endpoint is specific to a tenant, the tenantId field identifies the
+    tenant that URL applies to. Some operators include the tenant in the
+    URLs for a service, while others may provide one endpoint and use some
+    other mechanism to identify the tenant. This field is therefore optional.
+    Having this field also means you do not have to parse the URL to identify
+    a tenant if the operator includes it in the URL.
+
+versionId
+    This identifies the version of the API contract that endpoint supports.
+    While many APIs include the version in the URL (ex: https://compute.host/v1),
+    this field allows you to identify the version without parsing the URL. It
+    therefore also allows operators and service developers to publish endpoints
+    that do not have versions embedded in the URL.
+
+versionInfo
+    This is the URL to call to get some information on the version. This returns
+    information in this format::
+
+        {
+        "version": {
+          "id": "v2.0",
+          "status": "CURRENT",
+          "updated": "2011-01-21T11:33:21-06:00",
+          "links": [
+            {
+              "rel": "self",
+              "href": "http://identity.api.openstack.org/v2.0/"
+            }, {
+              "rel": "describedby",
+              "type": "application/pdf",
+              "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf"
+            }, {
+              "rel": "describedby",
+              "type": "application/vnd.sun.wadl+xml",
+              "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl"
+            }
+          ],
+            "media-types": [
+              {
+                "base": "application/xml",
+                "type": "application/vnd.openstack.identity+xml;version=2.0"
+              }, {
+                "base": "application/json",
+                "type": "application/vnd.openstack.identity+json;version=2.0"
+              }
+            ]
+          }
+        }
+
+versionList
+
+    This is the URL to call to find out which versions are supported at that
+    endpoint. The response is in this format::
+
+        {
+            "versions":[{
+                    "id":"v1.0",
+                    "status":"DEPRECATED",
+                    "updated":"2009-10-09T11:30:00Z",
+                    "links":[{
+                            "rel":"self",
+                            "href":"http://identity.api.openstack.org/v1.0/"
+                        }
+                    ]
+                },
+                {
+                    "id":"v1.1",
+                    "status":"CURRENT",
+                    "updated":"2010-12-12T18:30:02.25Z",
+                    "links":[{
+                            "rel":"self",
+                            "href":"http://identity.api.openstack.org/v1.1/"
+                        }
+                    ]
+                },
+                {
+                    "id":"v2.0",
+                    "status":"BETA",
+                    "updated":"2011-05-27T20:22:02.25Z",
+                    "links":[{
+                            "rel":"self",
+                            "href":"http://identity.api.openstack.org/v2.0/"
+                        }
+                    ]
+                }
+            ],
+            "versions_links":[]
+        }
+
+    Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0.
+    It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA.
+
+What are Endpoint Templates?
+----------------------------
+
+Endpoint Templates are a way for an administrator to manage endpoints en masse.
+They provide a way to define Endpoints that apply to many or all tenants
+without having to a create each endpoint on each tenant manually. Without
+Endpoint Templates, if I wanted to create Endpoints for each tenant in my
+OpenStack deployment, I'd have to manually create a bunch of endpoints on
+each tenant (probably when I created the tenant). And then I'd have to go change
+them all whenever a service changed versions or I added a new service.
+
+To provide a simpler mechanism to manage endpoints on tenants, Keystone uses
+Endpoint Templates. I can, for example, define a template with parametrized URLs
+and set it's `global` to true and that will show up as an endpoint on all the tenants
+I have. Here is an example:
+
+Define a global Endpoint Template::
+
+    $ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1
+
+    The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global'
+
+This creates a global endpoint (global means it gets applied to all tenants automatically).
+
+Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example
+authentication request for use against tenant 1::
+
+    $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens
+
+The response is::
+
+    {
+        "access": {
+            "serviceCatalog": [
+                {
+                    "endpoints": [
+                        {
+                            "internalURL": "https://compute.north.example.local",
+                            "publicURL": "https://compute.north.example.com/v1/1/",
+                            "region": "North"
+                        }
+                    ],
+                    "name": "nova",
+                    "type": "compute"
+                }
+            ],
+            "token": {
+                "expires": "2012-02-05T00:00:00",
+                "id": "887665443383838",
+                "tenant": {
+                    "id": "1",
+                    "name": "customer-x"
+                }
+            },
+            "user": {
+                "id": "1",
+                "name": "joeuser",
+                "roles": [
+                    {
+                        "id": "3",
+                        "name": "Member",
+                        "tenantId": "1"
+                    }
+                ]
+            }
+        }
+    }
+
+Notice the adminURL is not showing (this user is a regular user and does not
+have rights to see the adminURL) and the tenant ID has been substituted in the
+URL::
+
+    "publicURL": "https://compute.north.example.com/v1/1/",
+
+This endpoint will show up for all tenants. The OpenStack administrator does
+not need to create the endpoint manually.
+
+.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are).
+
+
+What parameters can I use in a Template URL
+-------------------------------------------
+
+Currently the only parameterization available is %tenant_id% which gets
+substituted by the Tenant ID.
+
+
+Endpoint Template Types: Global or not
+--------------------------------------
+
+When the global flag is set to true on an Endpoint Template, it means it should
+be available to all tenants. Whenever someone authenticates to a tenant, they
+will see the Endpoint generated by that template.
+
+When the global flag is not set, the template only shows up when it is added to
+a tenant manually. To add an endpoint to a tenant manually, you must create
+the Endpoint and supply the Endpoint Template ID:
+
+Create the Endpoint Template::
+
+    $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0
+
+    Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating.
+
+Find the Endpoint Template ID::
+
+    $ ./keystone-manage endpointTemplates list
+
+    All EndpointTemplates
+    id    service    type    region    enabled    is_global    Public URL    Admin URL
+    -------------------------------------------------------------------------------
+    15    nova    compute    North    True    True    https://compute.north.example.com/v1/%tenant_id%/    https://compute.north.example.corp
+    16    nova    compute    West    True    False    https://compute.west.example.com/v1/%tenant_id%/    https://compute.west.example.corp
+
+Add the Endpoint to the tenant::
+
+    $ ./keystone-manage endpoint add customer-x 16
+
+Now, when the user authenticates, they get the endpoint::
+
+    {
+        "internalURL": "https://compute.west.example.local",
+        "publicURL": "https://compute.west.example.com/v1/1/",
+        "region": "West"
+    }
+
+Who can see the AdminURL?
+-------------------------
+
+Users who have the Keystone `Admin` or `Service Admin` roles will see the
+AdminURL when they authenticate or when they retrieve token information:
+
+Using an administrator token to authenticate, GET a client token's endpoints::
+
+    $ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints
+
+    {
+        "endpoints": [
+            {
+                "adminURL": "https://compute.west.example.corp",
+                "id": 6,
+                "internalURL": "https://compute.west.example.local",
+                "name": "nova",
+                "publicURL": "https://compute.west.example.com/v1/1/",
+                "region": "West",
+                "tenantId": 1,
+                "type": "compute"
+            }
+        ],
+        "endpoints_links": [
+            {
+                "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", 
+                "rel": "next"
+            }
+        ]
+    }
diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst
new file mode 100644
index 00000000..539bef39
--- /dev/null
+++ b/docs/source/extensions.rst
@@ -0,0 +1,183 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+==========
+Extensions
+==========
+
+Extensions support adding features and functions to OpenStack APIs at any time, without prior
+approval or waiting for a new API and release cycles.
+
+The extension framework is in development and documented in extensions_ and extensionspresentation_.
+
+This document describes the extensions included with Keystone, how to enable and disable them,
+and briefly touches on how to write your own extensions.
+
+.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html
+.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions
+
+Built-in Extensions
+-------------------
+
+Keystone ships with a number of extensions found under the
+``keystone/contib/extensions`` folder.
+
+The following built-in extensions are included:
+
+OS-KSADM
+
+    This is an extensions that supports managing users, tenants, and roles
+    through the API. Without this extensions, the ony way to manage those
+    objects is through keystone-manage or directly in the underlying database.
+
+    This is an Admin API extension only.
+
+OS-KSCATALOG
+
+    This extensions supports managing Endpoints and prrovides the Endpoint
+    Template mechanism for managing bulk endpoints.
+
+    This is an Admin API extension only.
+
+OS-EC2
+
+    This extension adds support for EC2 credentials.
+
+    This is an Admin and Service API extension.
+
+RAX-GRP
+
+    This extension adds functionality the enables groups.
+
+    This is an Admin and Service API extension.
+
+RAX-KEY
+
+    This extensions adds support for authentication with an API Key (the core
+    Keystone API only supports username/password credentials)
+
+    This is an Admin and Service API extension.
+
+HP-IDM
+
+    This extension adds capability to filter roles with optional service IDs
+    for token validation to mitigate security risks with role name conflicts.
+    See https://bugs.launchpad.net/keystone/+bug/890411 for more details.
+
+    This is an Admin API extension. Applicable to validate token (GET)
+    and check token (HEAD) APIs only.
+
+OS-KSVALIDATE
+
+    This extensions supports admin calls to /tokens without having to specify
+    the token ID in the URL. Instead, the ID is supplied in a header called
+    X-Subject-Token. This is provided as an alternative to address any security
+    concerns that arise when token IDs are passed as part of the URL which is
+    often (and by default) logged to insecure media.
+
+    This is an Admin API extension only.
+
+.. note::
+
+    The included extensions are in the process of being rewritten. Currently
+    osksadm, oskscatalog, hpidm, and osksvalidate work with this new
+    extensions design.
+
+
+Enabling & Disabling Extensions
+-------------------------------
+
+The Keystone conf file has a property called extensions. This property holds
+the list of supported extensions that you want enabled. If you want to
+add/remove an extension from being supported, add/remove the extension key
+from this property. The key is the name of the folder of the extension
+under the keystone/contrib/extensions folder.
+
+.. note::
+
+    If you want to load different extensions in the service API than the Admin API
+    you need to use different config files.
+
+Creating New Extensions
+-----------------------
+
+#. **Adopt a unique organization abbreviation.**
+
+   This prefix should uniquely identify your organization within the community.
+   The goal is to avoid schema and resource collisions with similiar extensions.
+   (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard)
+
+#. **Adopt a unique extension abbreviation.**
+
+   Select an abbreviation to identify your extension, and append to
+   your organization prefix using a hyphen (``-``), by convention
+   (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension).
+
+   This combination is referred to as your extension's prefix.
+
+#. **Determine the scope of your extension.**
+
+   Extensions can enhance the Admin API, Service API or both.
+
+#. **Create a new module.**
+
+   Create a module to isolate your namespace based on the extension prefix
+   you selected::
+
+       keystone/contrib/extensions/admin
+
+   ... and/or::
+
+       keystone/contrib/extensions/service/
+
+   ... based on which API you are enhancing.
+
+   .. note::
+
+       In the future, we will support loading external extensions.
+
+#. Add static extension files for JSON (``*.json``) and XML
+   (``*.xml``) to the new extension module.
+
+   Refer to `Service Guide <https://github.com/openstack/keystone/blob/master/keystone/content/admin/identityadminguide.pdf?raw=true>`_
+   `Sample extension XML <https://github.com/openstack/keystone/blob/master/keystone/content/common/samples/extension.json>`_
+   `Sample extension JSON <https://github.com/openstack/keystone/blob/master/keystone/content/common/samples/extension.xml>`_ for the the content and structure.
+
+#. If your extension is adding additional methods override the base class
+   ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods.
+
+#. **Document your work.**
+
+   Provide documentation to support your extension.
+
+   Extensions documentation, WADL, and XSD files can be stored in the
+   ``keystone/content`` folder.
+
+#. Add your extension name to the list of supported extensions in The
+   ``keystone.conf`` file.
+
+Which extensions are enabled?
+-----------------------------
+
+Discover which extensions are available (service API)::
+
+    curl http://localhost:5000/v2.0/extensions
+
+... or (admin API)::
+
+    curl http://localhost:35357/v2.0/extensions
+
+The response will list the extensions available.
diff --git a/docs/source/images/305.svg b/docs/source/images/305.svg
new file mode 100644
index 00000000..7d79464e
--- /dev/null
+++ b/docs/source/images/305.svg
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="193.58089"
+   height="100.32214"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="proxyAuth.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98901497"
+     inkscape:cx="134.39587"
+     inkscape:cy="72.635488"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="912"
+     inkscape:window-height="842"
+     inkscape:window-x="66"
+     inkscape:window-y="87"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-240.60414,-504.67553)">
+    <g
+       id="1"
+       transform="translate(239.41667,503.49764)">
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="25.6"
+         x="136"
+         xml:space="preserve"
+         id="2">Request</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="36"
+         x="136"
+         xml:space="preserve"
+         id="3">service directly</text>
+      <path
+         d="m 1.85,14.45 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="4"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,43.25 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="5"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="25.6"
+         x="24.799999"
+         xml:space="preserve"
+         id="6">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="37.599998"
+         x="8.8000002"
+         xml:space="preserve"
+         id="7">Component</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="53.599998"
+         x="79.199997"
+         xml:space="preserve"
+         id="8">305 </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="53.599998"
+         x="96"
+         xml:space="preserve"
+         id="9">Use proxy to </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="63.200001"
+         x="79.199997"
+         xml:space="preserve"
+         id="10">redirect to Auth</text>
+      <path
+         d="M 64.25,72.05 C 83.45,33.65 87.8,15.9 75.1,6.45 67.75,1 54.85,-1.65 42.3,7.85"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="11"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 45.35,9.75 -9.9,4.7 5.1,-9.65 4.8,4.95 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="12"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 154.25,14.45 c 0,0 -4.85,0.5 -9.45,0.95 -7,0.7 -13.45,1.2 -17.85,5.1 -2.95,2.65 -5.05,6.8 -3.6,10.1 2.65,6.1 17.05,9.3 23.85,14 5,3.45 5.95,7.65 4.9,11.1 -1.9,6.35 -10.5,10 -23.85,16.2 -8.35,3.9 -18.6,8.85 -26.1,11.85"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="13"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 104,86.8 93.05,86.45 102,80.2 l 2,6.6 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="14"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 25.85,72.05 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="15"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 25.85,100.85 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="16"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="83.199997"
+         x="34.400002"
+         xml:space="preserve"
+         id="17">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="95.199997"
+         x="42.400002"
+         xml:space="preserve"
+         id="18">Service</text>
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/images/authComp.svg b/docs/source/images/authComp.svg
new file mode 100644
index 00000000..d344b871
--- /dev/null
+++ b/docs/source/images/authComp.svg
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="131.44359"
+   height="154.62857"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="New document 1">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98901497"
+     inkscape:cx="111.31439"
+     inkscape:cy="-34.431283"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="912"
+     inkscape:window-height="842"
+     inkscape:window-x="66"
+     inkscape:window-y="87"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-263.68561,-343.30233)">
+    <g
+       id="1"
+       transform="translate(262.49833,342.08712)">
+      <path
+         d="m 1.85,49.6 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="2"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,78.4 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="3"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="60.799999"
+         x="24.799999"
+         xml:space="preserve"
+         id="4">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="72.800003"
+         x="8.8000002"
+         xml:space="preserve"
+         id="5">Component</text>
+      <path
+         d="m 1.85,126.4 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="6"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,155.2 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="7"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="137.60001"
+         x="10.4"
+         xml:space="preserve"
+         id="8">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="149.60001"
+         x="18.4"
+         xml:space="preserve"
+         id="9">Service</text>
+      <path
+         d="m 35.45,78.4 0,38.5"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="10"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 38.9,116.05 35.45,126.4 32,116.05 l 6.9,0 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="11"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 16.25,1.6 15.7,39.2"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="12"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 34.8,38.7 35.45,49.6 28.4,41.25 34.8,38.7 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="13"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 41.05,49.6 56.75,10.45"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="14"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 53.2,9.95 60.25,1.6 59.6,12.5 53.2,9.95 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="15"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="18.4"
+         x="69.599998"
+         xml:space="preserve"
+         id="16">Reject</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="28.799999"
+         x="69.599998"
+         xml:space="preserve"
+         id="17">unauthenticated</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="39.200001"
+         x="69.599998"
+         xml:space="preserve"
+         id="18">requests</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="95.199997"
+         x="52"
+         xml:space="preserve"
+         id="19">Forward</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="105.6"
+         x="52"
+         xml:space="preserve"
+         id="20">authenticated</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="116"
+         x="52"
+         xml:space="preserve"
+         id="21">requests</text>
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/images/both.svg b/docs/source/images/both.svg
new file mode 100644
index 00000000..d29872a4
--- /dev/null
+++ b/docs/source/images/both.svg
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="68.500092"
+   height="110.50006"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="mapper.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98901497"
+     inkscape:cx="34.262561"
+     inkscape:cy="55.237534"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="912"
+     inkscape:window-height="842"
+     inkscape:window-x="66"
+     inkscape:window-y="87"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-340.73745,-315.32253)">
+    <g
+       id="1"
+       transform="translate(339.55001,314.13506)">
+      <path
+         d="m 1.85,1.85 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="2"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,30.65 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="3"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="13.6"
+         x="24.799999"
+         xml:space="preserve"
+         id="4">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="24.799999"
+         x="8.8000002"
+         xml:space="preserve"
+         id="5">Component</text>
+      <path
+         d="m 1.85,81.05 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#a6a6a6;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="6"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#bfbfbf;font-family:Arial"
+         y="64"
+         x="24.799999"
+         xml:space="preserve"
+         id="7">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#bfbfbf;font-family:Arial"
+         y="75.199997"
+         x="8.8000002"
+         xml:space="preserve"
+         id="8">Component</text>
+      <path
+         d="m 1.85,82.25 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="9"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,111.05 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="10"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="93.599998"
+         x="10.4"
+         xml:space="preserve"
+         id="11">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="105.6"
+         x="18.4"
+         xml:space="preserve"
+         id="12">Service</text>
+      <path
+         d="m 35.45,30.65 0,40.9"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="13"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 38.9,70.7 35.45,81.05 32,70.7 l 6.9,0 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="14"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/images/graphs_305.svg b/docs/source/images/graphs_305.svg
new file mode 100644
index 00000000..1dff61a6
--- /dev/null
+++ b/docs/source/images/graphs_305.svg
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: Handle305 Pages: 1 -->
+<svg width="310pt" height="208pt"
+ viewBox="0.00 0.00 310.00 208.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 204)">
+<title>Handle305</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-204 307,-204 307,5 -4,5"/>
+<!-- AuthComp -->
+<g id="node2" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="98,-146 0,-146 0,-106 98,-106 98,-146"/>
+<text text-anchor="middle" x="49" y="-129.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="49" y="-113.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Service -->
+<g id="node4" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="119,-40 25,-40 25,-0 119,-0 119,-40"/>
+<text text-anchor="middle" x="72" y="-23.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="72" y="-7.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge5" class="edge"><title>Service:n&#45;&gt;AuthComp:n</title>
+<path fill="none" stroke="black" d="M72,-40C72,-62.2222 76.6172,-67.8558 86,-88 90.0596,-96.7157 95.2138,-96.7977 98,-106 103.152,-123.015 110.312,-133.175 98,-146 92.6344,-151.589 70.1318,-155.75 57.5709,-153.773"/>
+<polygon fill="black" stroke="black" points="59.2494,-150.684 49,-148 55.3388,-156.489 59.2494,-150.684"/>
+<text text-anchor="middle" x="144" y="-75.4" font-family="Times,serif" font-size="14.00">305 Use Proxy</text>
+<text text-anchor="middle" x="144" y="-60.4" font-family="Times,serif" font-size="14.00">To Redirect to Auth</text>
+</g>
+<!-- Start -->
+<!-- Start&#45;&gt;Service -->
+<g id="edge7" class="edge"><title>Start:sw&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M216,-164C182.398,-130.398 232.934,-94.0727 202,-58 192.167,-46.5338 159.461,-37.0056 129.317,-30.3582"/>
+<polygon fill="black" stroke="black" points="129.738,-26.8696 119.229,-28.2156 128.284,-33.7169 129.738,-26.8696"/>
+<text text-anchor="middle" x="255.5" y="-128.4" font-family="Times,serif" font-size="14.00">Request</text>
+<text text-anchor="middle" x="255.5" y="-113.4" font-family="Times,serif" font-size="14.00">Service Directly</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_authComp.svg b/docs/source/images/graphs_authComp.svg
new file mode 100644
index 00000000..6be629c1
--- /dev/null
+++ b/docs/source/images/graphs_authComp.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: AuthComp Pages: 1 -->
+<svg width="510pt" height="118pt"
+ viewBox="0.00 0.00 510.00 118.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 114)">
+<title>AuthComp</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-114 507,-114 507,5 -4,5"/>
+<!-- AuthComp -->
+<g id="node2" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="292,-65 194,-65 194,-25 292,-25 292,-65"/>
+<text text-anchor="middle" x="243" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="243" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Reject -->
+<!-- AuthComp&#45;&gt;Reject -->
+<g id="edge3" class="edge"><title>AuthComp&#45;&gt;Reject</title>
+<path fill="none" stroke="black" d="M193.933,-51.2787C157.514,-55.939 108.38,-62.2263 73.8172,-66.649"/>
+<polygon fill="black" stroke="black" points="73.0637,-63.2168 63.5888,-67.9578 73.9522,-70.1602 73.0637,-63.2168"/>
+<text text-anchor="middle" x="129" y="-97.4" font-family="Times,serif" font-size="14.00">Reject</text>
+<text text-anchor="middle" x="129" y="-82.4" font-family="Times,serif" font-size="14.00">Unauthenticated</text>
+<text text-anchor="middle" x="129" y="-67.4" font-family="Times,serif" font-size="14.00">Requests</text>
+</g>
+<!-- Service -->
+<g id="node6" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="502,-65 408,-65 408,-25 502,-25 502,-65"/>
+<text text-anchor="middle" x="455" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="455" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M292.17,-45C323.626,-45 364.563,-45 397.52,-45"/>
+<polygon fill="black" stroke="black" points="397.917,-48.5001 407.917,-45 397.917,-41.5001 397.917,-48.5001"/>
+<text text-anchor="middle" x="350" y="-77.4" font-family="Times,serif" font-size="14.00">Forward</text>
+<text text-anchor="middle" x="350" y="-62.4" font-family="Times,serif" font-size="14.00">Authenticated</text>
+<text text-anchor="middle" x="350" y="-47.4" font-family="Times,serif" font-size="14.00">Requests</text>
+</g>
+<!-- Start -->
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge7" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M59.1526,-21.4745C90.4482,-25.4792 142.816,-32.1802 183.673,-37.4084"/>
+<polygon fill="black" stroke="black" points="183.43,-40.9057 193.793,-38.7034 184.318,-33.9623 183.43,-40.9057"/>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_authCompDelegate.svg b/docs/source/images/graphs_authCompDelegate.svg
new file mode 100644
index 00000000..4788829a
--- /dev/null
+++ b/docs/source/images/graphs_authCompDelegate.svg
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: AuthCompDelegate Pages: 1 -->
+<svg width="588pt" height="104pt"
+ viewBox="0.00 0.00 588.00 104.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 100)">
+<title>AuthCompDelegate</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-100 585,-100 585,5 -4,5"/>
+<!-- AuthComp -->
+<g id="node2" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="338,-65 240,-65 240,-25 338,-25 338,-65"/>
+<text text-anchor="middle" x="289" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="289" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Reject -->
+<!-- AuthComp&#45;&gt;Reject -->
+<g id="edge3" class="edge"><title>AuthComp&#45;&gt;Reject</title>
+<path fill="none" stroke="black" d="M239.6,-50.1899C191.406,-55.2531 118.917,-62.8686 73.5875,-67.6309"/>
+<polygon fill="black" stroke="black" points="73.0928,-64.1635 63.5132,-68.6893 73.8242,-71.1252 73.0928,-64.1635"/>
+<text text-anchor="middle" x="152" y="-83.4" font-family="Times,serif" font-size="14.00">Reject Requests</text>
+<text text-anchor="middle" x="152" y="-68.4" font-family="Times,serif" font-size="14.00">Indicated by the Service</text>
+</g>
+<!-- Service -->
+<g id="node6" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="580,-65 486,-65 486,-25 580,-25 580,-65"/>
+<text text-anchor="middle" x="533" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="533" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M338.009,-49.0804C344.065,-49.4598 350.172,-49.7828 356,-50 405.743,-51.8535 418.259,-51.9103 468,-50 470.523,-49.9031 473.101,-49.7851 475.704,-49.6504"/>
+<polygon fill="black" stroke="black" points="476.03,-53.1374 485.807,-49.0576 475.62,-46.1494 476.03,-53.1374"/>
+<text text-anchor="middle" x="412" y="-68.4" font-family="Times,serif" font-size="14.00">Forward Requests</text>
+<text text-anchor="middle" x="412" y="-53.4" font-family="Times,serif" font-size="14.00">with Identiy Status</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge7" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M495.062,-24.9037C486.397,-21.2187 477.064,-17.9304 468,-16 419.314,-5.63183 404.743,-5.9037 356,-16 349.891,-17.2653 343.655,-19.116 337.566,-21.2803"/>
+<polygon fill="black" stroke="black" points="336.234,-18.0426 328.158,-24.9003 338.748,-24.5757 336.234,-18.0426"/>
+<text text-anchor="middle" x="412" y="-33.4" font-family="Times,serif" font-size="14.00">Send Response OR</text>
+<text text-anchor="middle" x="412" y="-18.4" font-family="Times,serif" font-size="14.00">Reject Message</text>
+</g>
+<!-- Start -->
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge9" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M59.0178,-20.8384C99.2135,-25.0613 175.782,-33.1055 229.492,-38.7482"/>
+<polygon fill="black" stroke="black" points="229.265,-42.2435 239.576,-39.8076 229.997,-35.2818 229.265,-42.2435"/>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_both.svg b/docs/source/images/graphs_both.svg
new file mode 100644
index 00000000..6aa87612
--- /dev/null
+++ b/docs/source/images/graphs_both.svg
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: Both Pages: 1 -->
+<svg width="116pt" height="180pt"
+ viewBox="0.00 0.00 116.00 180.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 176)">
+<title>Both</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-176 113,-176 113,5 -4,5"/>
+<!-- AuthComp -->
+<g id="node2" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="104,-172 6,-172 6,-132 104,-132 104,-172"/>
+<text text-anchor="middle" x="55" y="-155.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="55" y="-139.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Together -->
+<g id="node4" class="node"><title>Together</title>
+<polygon fill="white" stroke="white" points="108,-95.5 0,-95.5 0,-0.5 108,-0.5 108,-95.5"/>
+<polygon fill="white" stroke="white" points="8,-47 8,-91 101,-91 101,-47 8,-47"/>
+<polygon fill="none" stroke="#c00000" points="8,-47 8,-91 101,-91 101,-47 8,-47"/>
+<text text-anchor="start" x="38" y="-75.2333" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="start" x="13.5" y="-58.4333" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+<polygon fill="#d1ebf1" stroke="#d1ebf1" points="8,-4 8,-47 101,-47 101,-4 8,-4"/>
+<polygon fill="none" stroke="#1f477d" points="8,-4 8,-47 101,-47 101,-4 8,-4"/>
+<text text-anchor="start" x="15.5" y="-31.7333" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="start" x="28" y="-14.9333" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Together -->
+<g id="edge3" class="edge"><title>AuthComp&#45;&gt;Together:OStack:n</title>
+<path fill="none" stroke="black" d="M55,-131.871C55,-113.129 55,-84.1127 55,-57.1901"/>
+<polygon fill="black" stroke="black" points="58.5001,-57 55,-47 51.5001,-57 58.5001,-57"/>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_delegate_accept.svg b/docs/source/images/graphs_delegate_accept.svg
new file mode 100644
index 00000000..1d86cadf
--- /dev/null
+++ b/docs/source/images/graphs_delegate_accept.svg
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: DelegateAcceptAuth Pages: 1 -->
+<svg width="656pt" height="81pt"
+ viewBox="0.00 0.00 656.00 81.23" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 77.234)">
+<title>DelegateAcceptAuth</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-77.234 653,-77.234 653,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="348,-48.234 250,-48.234 250,-8.23398 348,-8.23398 348,-48.234"/>
+<text text-anchor="middle" x="299" y="-31.634" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="299" y="-15.634" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.0748,-28.234C97.1107,-28.234 182.142,-28.234 239.791,-28.234"/>
+<polygon fill="black" stroke="black" points="239.864,-31.7341 249.863,-28.234 239.863,-24.7341 239.864,-31.7341"/>
+<text text-anchor="middle" x="152" y="-30.634" font-family="Times,serif" font-size="14.00">Authorization: Basic VTpQ</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge9" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M249.934,-12.6562C243.944,-11.2496 237.868,-10.0499 232,-9.23398 161.567,0.55976 141.697,4.87673 72,-9.23398 69.1948,-9.80192 66.3471,-10.5503 63.5169,-11.4218"/>
+<polygon fill="black" stroke="black" points="62.3066,-8.13733 54.0489,-14.7751 64.6436,-14.7357 62.3066,-8.13733"/>
+<text text-anchor="middle" x="152" y="-11.634" font-family="Times,serif" font-size="14.00">200 Okay</text>
+</g>
+<!-- Service -->
+<g id="node6" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="648,-48.234 554,-48.234 554,-8.23398 648,-8.23398 648,-48.234"/>
+<text text-anchor="middle" x="601" y="-31.634" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="601" y="-15.634" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M348.194,-28.234C401.691,-28.234 487.101,-28.234 543.616,-28.234"/>
+<polygon fill="black" stroke="black" points="543.818,-31.7341 553.818,-28.234 543.818,-24.7341 543.818,-31.7341"/>
+<text text-anchor="middle" x="451" y="-60.634" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="451" y="-45.634" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy U</text>
+<text text-anchor="middle" x="451" y="-30.634" font-family="Times,serif" font-size="14.00">X&#45;Identity&#45;Status: Confirmed</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge7" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M553.774,-12.7435C547.845,-11.2995 541.819,-10.067 536,-9.23398 461.207,1.47328 440.836,1.17187 366,-9.23398 363.341,-9.6037 360.639,-10.0522 357.922,-10.5631"/>
+<polygon fill="black" stroke="black" points="357.121,-7.15517 348.066,-12.6562 358.575,-14.0025 357.121,-7.15517"/>
+<text text-anchor="middle" x="451" y="-11.634" font-family="Times,serif" font-size="14.00">200 Okay</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_delegate_forbiden_basic.svg b/docs/source/images/graphs_delegate_forbiden_basic.svg
new file mode 100644
index 00000000..dcd62b77
--- /dev/null
+++ b/docs/source/images/graphs_delegate_forbiden_basic.svg
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: DelegateRejectForbidden Pages: 1 -->
+<svg width="670pt" height="102pt"
+ viewBox="0.00 0.00 670.00 101.64" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 97.6355)">
+<title>DelegateRejectForbidden</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-97.6355 667,-97.6355 667,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="348,-61.6355 250,-61.6355 250,-21.6355 348,-21.6355 348,-61.6355"/>
+<text text-anchor="middle" x="299" y="-45.0355" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="299" y="-29.0355" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.0748,-41.6355C97.1107,-41.6355 182.142,-41.6355 239.791,-41.6355"/>
+<polygon fill="black" stroke="black" points="239.864,-45.1356 249.863,-41.6355 239.863,-38.1356 239.864,-45.1356"/>
+<text text-anchor="middle" x="152" y="-44.0355" font-family="Times,serif" font-size="14.00">Authorization: Basic VTpQ</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M249.934,-26.0577C243.944,-24.6511 237.868,-23.4514 232,-22.6355 161.567,-12.8417 141.697,-8.52478 72,-22.6355 69.1948,-23.2034 66.3471,-23.9518 63.5169,-24.8233"/>
+<polygon fill="black" stroke="black" points="62.3066,-21.5388 54.0489,-28.1766 64.6436,-28.1372 62.3066,-21.5388"/>
+<text text-anchor="middle" x="152" y="-25.0355" font-family="Times,serif" font-size="14.00">403 Forbidden</text>
+</g>
+<!-- Service -->
+<g id="node7" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="662,-61.6355 568,-61.6355 568,-21.6355 662,-21.6355 662,-61.6355"/>
+<text text-anchor="middle" x="615" y="-45.0355" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="615" y="-29.0355" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge7" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M348.009,-45.7159C354.065,-46.0953 360.172,-46.4183 366,-46.6355 447.721,-49.6805 468.282,-49.7738 550,-46.6355 552.523,-46.5386 555.101,-46.4206 557.704,-46.2859"/>
+<polygon fill="black" stroke="black" points="558.03,-49.7729 567.807,-45.6931 557.62,-42.7849 558.03,-49.7729"/>
+<text text-anchor="middle" x="458" y="-81.0355" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="458" y="-66.0355" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy U</text>
+<text text-anchor="middle" x="458" y="-51.0355" font-family="Times,serif" font-size="14.00">X&#45;Identity&#45;Status: Confirmed</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge9" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M577.062,-21.5392C568.397,-17.8542 559.064,-14.5658 550,-12.6355 470.016,4.39794 446.078,3.95128 366,-12.6355 359.891,-13.9008 353.655,-15.7515 347.566,-17.9158"/>
+<polygon fill="black" stroke="black" points="346.234,-14.6781 338.158,-21.5358 348.748,-21.2112 346.234,-14.6781"/>
+<text text-anchor="middle" x="458" y="-30.0355" font-family="Times,serif" font-size="14.00">403 Forbidden</text>
+<text text-anchor="middle" x="458" y="-15.0355" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: Delegated</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_delegate_forbiden_proxy.svg b/docs/source/images/graphs_delegate_forbiden_proxy.svg
new file mode 100644
index 00000000..df53212b
--- /dev/null
+++ b/docs/source/images/graphs_delegate_forbiden_proxy.svg
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: DelegateForbiddnProxy Pages: 1 -->
+<svg width="656pt" height="81pt"
+ viewBox="0.00 0.00 656.00 81.23" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 77.234)">
+<title>DelegateForbiddnProxy</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-77.234 653,-77.234 653,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="348,-48.234 250,-48.234 250,-8.23398 348,-8.23398 348,-48.234"/>
+<text text-anchor="middle" x="299" y="-31.634" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="299" y="-15.634" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.0748,-28.234C97.1107,-28.234 182.142,-28.234 239.791,-28.234"/>
+<polygon fill="black" stroke="black" points="239.864,-31.7341 249.863,-28.234 239.863,-24.7341 239.864,-31.7341"/>
+<text text-anchor="middle" x="152" y="-30.634" font-family="Times,serif" font-size="14.00">Authorization: Basic VTpQ</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M249.934,-12.6562C243.944,-11.2496 237.868,-10.0499 232,-9.23398 161.567,0.55976 141.697,4.87673 72,-9.23398 69.1948,-9.80192 66.3471,-10.5503 63.5169,-11.4218"/>
+<polygon fill="black" stroke="black" points="62.3066,-8.13733 54.0489,-14.7751 64.6436,-14.7357 62.3066,-8.13733"/>
+<text text-anchor="middle" x="152" y="-11.634" font-family="Times,serif" font-size="14.00">500 Internal Error</text>
+</g>
+<!-- Service -->
+<g id="node7" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="648,-48.234 554,-48.234 554,-8.23398 648,-8.23398 648,-48.234"/>
+<text text-anchor="middle" x="601" y="-31.634" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="601" y="-15.634" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge7" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M348.194,-28.234C401.691,-28.234 487.101,-28.234 543.616,-28.234"/>
+<polygon fill="black" stroke="black" points="543.818,-31.7341 553.818,-28.234 543.818,-24.7341 543.818,-31.7341"/>
+<text text-anchor="middle" x="451" y="-60.634" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="451" y="-45.634" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy U</text>
+<text text-anchor="middle" x="451" y="-30.634" font-family="Times,serif" font-size="14.00">X&#45;Identity&#45;Status: Confirmed</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge9" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M553.774,-12.7435C547.845,-11.2995 541.819,-10.067 536,-9.23398 461.207,1.47328 440.836,1.17187 366,-9.23398 363.341,-9.6037 360.639,-10.0522 357.922,-10.5631"/>
+<polygon fill="black" stroke="black" points="357.121,-7.15517 348.066,-12.6562 358.575,-14.0025 357.121,-7.15517"/>
+<text text-anchor="middle" x="451" y="-11.634" font-family="Times,serif" font-size="14.00">403 Forbidden</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_delegate_reject_basic.svg b/docs/source/images/graphs_delegate_reject_basic.svg
new file mode 100644
index 00000000..a33ea095
--- /dev/null
+++ b/docs/source/images/graphs_delegate_reject_basic.svg
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: DelegateRejectAuthBasic Pages: 1 -->
+<svg width="670pt" height="113pt"
+ viewBox="0.00 0.00 670.00 112.84" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 108.841)">
+<title>DelegateRejectAuthBasic</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-108.841 667,-108.841 667,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="346,-72.8409 248,-72.8409 248,-32.8409 346,-32.8409 346,-72.8409"/>
+<text text-anchor="middle" x="297" y="-56.2409" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="297" y="-40.2409" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.3777,-61.3549C60.1429,-62.8044 66.2278,-64.0845 72,-64.8409 141.627,-73.9651 160.053,-71.0554 230,-64.8409 232.523,-64.6168 235.094,-64.346 237.686,-64.038"/>
+<polygon fill="black" stroke="black" points="238.294,-67.4878 247.737,-62.6852 237.36,-60.5504 238.294,-67.4878"/>
+<text text-anchor="middle" x="151" y="-72.2409" font-family="Times,serif" font-size="14.00">Authorization: Basic Yjpw</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M268.012,-32.6508C256.688,-25.9141 243.253,-19.2572 230,-15.8409 162.001,1.68741 138.106,7.84667 72,-15.8409 64.6685,-18.468 57.6762,-22.8621 51.4824,-27.7226"/>
+<polygon fill="black" stroke="black" points="48.8781,-25.3457 43.5743,-34.5174 53.44,-30.655 48.8781,-25.3457"/>
+<text text-anchor="middle" x="151" y="-48.2409" font-family="Times,serif" font-size="14.00">401 Unauthorized</text>
+<text text-anchor="middle" x="151" y="-33.2409" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: Basic</text>
+<text text-anchor="middle" x="151" y="-18.2409" font-family="Times,serif" font-size="14.00">Realm=&quot;API Realm&quot;</text>
+</g>
+<!-- Service -->
+<g id="node7" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="662,-72.8409 568,-72.8409 568,-32.8409 662,-32.8409 662,-72.8409"/>
+<text text-anchor="middle" x="615" y="-56.2409" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="615" y="-40.2409" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge7" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M346.009,-56.9214C352.065,-57.3007 358.172,-57.6238 364,-57.8409 446.609,-60.9191 467.394,-61.0134 550,-57.8409 552.523,-57.744 555.101,-57.626 557.704,-57.4913"/>
+<polygon fill="black" stroke="black" points="558.03,-60.9783 567.807,-56.8985 557.62,-53.9903 558.03,-60.9783"/>
+<text text-anchor="middle" x="457" y="-92.2409" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="457" y="-77.2409" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy b</text>
+<text text-anchor="middle" x="457" y="-62.2409" font-family="Times,serif" font-size="14.00">X&#45;Identity&#45;Status: Indeterminate</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge9" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M577.062,-32.7447C568.397,-29.0597 559.064,-25.7713 550,-23.8409 469.146,-6.62237 444.948,-7.07388 364,-23.8409 357.891,-25.1063 351.655,-26.957 345.566,-29.1213"/>
+<polygon fill="black" stroke="black" points="344.234,-25.8836 336.158,-32.7413 346.748,-32.4166 344.234,-25.8836"/>
+<text text-anchor="middle" x="457" y="-41.2409" font-family="Times,serif" font-size="14.00">401 Unauthorized</text>
+<text text-anchor="middle" x="457" y="-26.2409" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: Delegated</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_delegate_reject_oauth.svg b/docs/source/images/graphs_delegate_reject_oauth.svg
new file mode 100644
index 00000000..760adeb6
--- /dev/null
+++ b/docs/source/images/graphs_delegate_reject_oauth.svg
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: DelegateRejectAuthOAuth Pages: 1 -->
+<svg width="722pt" height="128pt"
+ viewBox="0.00 0.00 722.00 127.50" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 123.504)">
+<title>DelegateRejectAuthOAuth</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-123.504 719,-123.504 719,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="398,-87.504 300,-87.504 300,-47.504 398,-47.504 398,-87.504"/>
+<text text-anchor="middle" x="349" y="-70.904" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="349" y="-54.904" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.4752,-81.8682C60.1286,-84.2034 66.1458,-86.2617 72,-87.504 163.3,-106.879 189.647,-100.994 282,-87.504 284.667,-87.1144 287.375,-86.642 290.098,-86.104"/>
+<polygon fill="black" stroke="black" points="290.972,-89.4951 299.969,-83.9 289.446,-82.6633 290.972,-89.4951"/>
+<text text-anchor="middle" x="177" y="-101.904" font-family="Times,serif" font-size="14.00">Authorization: OAuth 000&#45;999&#45;222</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M325.91,-47.4946C313.721,-38.2548 297.999,-28.2878 282,-23.504 192.578,3.23327 158.428,11.7282 72,-23.504 62.489,-27.3811 53.8955,-34.3434 46.8279,-41.6023"/>
+<polygon fill="black" stroke="black" points="43.8515,-39.6795 39.7866,-49.4636 49.0657,-44.3499 43.8515,-39.6795"/>
+<text text-anchor="middle" x="177" y="-70.904" font-family="Times,serif" font-size="14.00">401 Unauthorized</text>
+<text text-anchor="middle" x="177" y="-55.904" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: OAuth</text>
+<text text-anchor="middle" x="177" y="-40.904" font-family="Times,serif" font-size="14.00">Realm=’API Realm’,</text>
+<text text-anchor="middle" x="177" y="-25.904" font-family="Times,serif" font-size="14.00">Error=’invalid&#45;token’</text>
+</g>
+<!-- Service -->
+<g id="node7" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="714,-87.504 620,-87.504 620,-47.504 714,-47.504 714,-87.504"/>
+<text text-anchor="middle" x="667" y="-70.904" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="667" y="-54.904" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge7" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M398.009,-71.5844C404.065,-71.9638 410.172,-72.2868 416,-72.504 498.609,-75.5822 519.394,-75.6765 602,-72.504 604.523,-72.4071 607.101,-72.2891 609.704,-72.1544"/>
+<polygon fill="black" stroke="black" points="610.03,-75.6414 619.807,-71.5616 609.62,-68.6534 610.03,-75.6414"/>
+<text text-anchor="middle" x="509" y="-106.904" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="509" y="-91.904" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy</text>
+<text text-anchor="middle" x="509" y="-76.904" font-family="Times,serif" font-size="14.00">X&#45;Identity&#45;Status: Indeterminate</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge9" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M629.062,-47.4077C620.397,-43.7227 611.064,-40.4344 602,-38.504 521.146,-21.2854 496.948,-21.7369 416,-38.504 409.891,-39.7693 403.655,-41.62 397.566,-43.7843"/>
+<polygon fill="black" stroke="black" points="396.234,-40.5466 388.158,-47.4043 398.748,-47.0797 396.234,-40.5466"/>
+<text text-anchor="middle" x="509" y="-55.904" font-family="Times,serif" font-size="14.00">401 Unauthorized</text>
+<text text-anchor="middle" x="509" y="-40.904" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: Delegated</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_delegate_unimplemented.svg b/docs/source/images/graphs_delegate_unimplemented.svg
new file mode 100644
index 00000000..8c4fdc6b
--- /dev/null
+++ b/docs/source/images/graphs_delegate_unimplemented.svg
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: DelegateUnimplemented Pages: 1 -->
+<svg width="670pt" height="102pt"
+ viewBox="0.00 0.00 670.00 101.64" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 97.6355)">
+<title>DelegateUnimplemented</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-97.6355 667,-97.6355 667,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="348,-61.6355 250,-61.6355 250,-21.6355 348,-21.6355 348,-61.6355"/>
+<text text-anchor="middle" x="299" y="-45.0355" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="299" y="-29.0355" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.0748,-41.6355C97.1107,-41.6355 182.142,-41.6355 239.791,-41.6355"/>
+<polygon fill="black" stroke="black" points="239.864,-45.1356 249.863,-41.6355 239.863,-38.1356 239.864,-45.1356"/>
+<text text-anchor="middle" x="152" y="-44.0355" font-family="Times,serif" font-size="14.00">Authorization: Basic VTpQ</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M249.934,-26.0577C243.944,-24.6511 237.868,-23.4514 232,-22.6355 161.567,-12.8417 141.697,-8.52478 72,-22.6355 69.1948,-23.2034 66.3471,-23.9518 63.5169,-24.8233"/>
+<polygon fill="black" stroke="black" points="62.3066,-21.5388 54.0489,-28.1766 64.6436,-28.1372 62.3066,-21.5388"/>
+<text text-anchor="middle" x="152" y="-25.0355" font-family="Times,serif" font-size="14.00">500 Internal Error</text>
+</g>
+<!-- Service -->
+<g id="node7" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="662,-61.6355 568,-61.6355 568,-21.6355 662,-21.6355 662,-61.6355"/>
+<text text-anchor="middle" x="615" y="-45.0355" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="615" y="-29.0355" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge7" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M348.009,-45.7159C354.065,-46.0953 360.172,-46.4183 366,-46.6355 447.721,-49.6805 468.282,-49.7738 550,-46.6355 552.523,-46.5386 555.101,-46.4206 557.704,-46.2859"/>
+<polygon fill="black" stroke="black" points="558.03,-49.7729 567.807,-45.6931 557.62,-42.7849 558.03,-49.7729"/>
+<text text-anchor="middle" x="458" y="-81.0355" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="458" y="-66.0355" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy U</text>
+<text text-anchor="middle" x="458" y="-51.0355" font-family="Times,serif" font-size="14.00">X&#45;Identity&#45;Status: Confirmed</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge9" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M577.062,-21.5392C568.397,-17.8542 559.064,-14.5658 550,-12.6355 470.016,4.39794 446.078,3.95128 366,-12.6355 359.891,-13.9008 353.655,-15.7515 347.566,-17.9158"/>
+<polygon fill="black" stroke="black" points="346.234,-14.6781 338.158,-21.5358 348.748,-21.2112 346.234,-14.6781"/>
+<text text-anchor="middle" x="458" y="-30.0355" font-family="Times,serif" font-size="14.00">501 Unimplemented</text>
+<text text-anchor="middle" x="458" y="-15.0355" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: Delegated</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_mapper.svg b/docs/source/images/graphs_mapper.svg
new file mode 100644
index 00000000..52c6c55b
--- /dev/null
+++ b/docs/source/images/graphs_mapper.svg
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: Mapper Pages: 1 -->
+<svg width="174pt" height="264pt"
+ viewBox="0.00 0.00 174.00 264.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 260)">
+<title>Mapper</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-260 171,-260 171,5 -4,5"/>
+<!-- Start -->
+<!-- Mapper -->
+<g id="node4" class="node"><title>Mapper</title>
+<polygon fill="#ebf1de" stroke="#687b37" points="119,-184 49,-184 49,-148 119,-148 119,-184"/>
+<text text-anchor="middle" x="84" y="-161.4" font-family="Helvetica,sans-Serif" font-size="14.00">Mapper</text>
+</g>
+<!-- Start&#45;&gt;Mapper -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;Mapper</title>
+<path fill="none" stroke="black" d="M84,-219.831C84,-212.131 84,-202.974 84,-194.417"/>
+<polygon fill="black" stroke="black" points="87.5001,-194.413 84,-184.413 80.5001,-194.413 87.5001,-194.413"/>
+</g>
+<!-- Auths -->
+<g id="node6" class="node"><title>Auths</title>
+<polygon fill="white" stroke="white" points="166,-112 0,-112 0,-76 166,-76 166,-112"/>
+<polygon fill="#fdefe3" stroke="#fdefe3" points="8,-81 8,-106 59,-106 59,-81 8,-81"/>
+<polygon fill="none" stroke="#c00000" points="8,-81 8,-106 59,-106 59,-81 8,-81"/>
+<text text-anchor="start" x="13.5" y="-90.2333" font-family="Helvetica,sans-Serif" font-size="14.00">Auth1</text>
+<polygon fill="#fdefe3" stroke="#fdefe3" points="59,-81 59,-106 109,-106 109,-81 59,-81"/>
+<polygon fill="none" stroke="#c00000" points="59,-81 59,-106 109,-106 109,-81 59,-81"/>
+<text text-anchor="start" x="64" y="-90.2333" font-family="Helvetica,sans-Serif" font-size="14.00">Auth2</text>
+<polygon fill="#fdefe3" stroke="#fdefe3" points="109,-81 109,-106 159,-106 159,-81 109,-81"/>
+<polygon fill="none" stroke="#c00000" points="109,-81 109,-106 159,-106 159,-81 109,-81"/>
+<text text-anchor="start" x="114" y="-90.2333" font-family="Helvetica,sans-Serif" font-size="14.00">Auth3</text>
+</g>
+<!-- Mapper&#45;&gt;Auths -->
+<g id="edge5" class="edge"><title>Mapper:sw&#45;&gt;Auths:auth1</title>
+<path fill="none" stroke="black" d="M49,-148C37.5237,-136.524 34.1339,-129.157 33.2662,-116.083"/>
+<polygon fill="black" stroke="black" points="36.7628,-115.904 33,-106 29.7652,-116.089 36.7628,-115.904"/>
+</g>
+<!-- Mapper&#45;&gt;Auths -->
+<g id="edge7" class="edge"><title>Mapper:s&#45;&gt;Auths:auth2</title>
+<path fill="none" stroke="black" d="M84,-148C84,-133.271 84,-127.258 84,-116.207"/>
+<polygon fill="black" stroke="black" points="87.5001,-116 84,-106 80.5001,-116 87.5001,-116"/>
+</g>
+<!-- Mapper&#45;&gt;Auths -->
+<g id="edge9" class="edge"><title>Mapper:se&#45;&gt;Auths:auth3</title>
+<path fill="none" stroke="black" d="M119,-148C130.388,-136.612 133.173,-129.088 133.817,-116.035"/>
+<polygon fill="black" stroke="black" points="137.317,-116.062 134,-106 130.318,-115.934 137.317,-116.062"/>
+</g>
+<!-- Service -->
+<g id="node10" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="131,-40 37,-40 37,-0 131,-0 131,-40"/>
+<text text-anchor="middle" x="84" y="-23.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="84" y="-7.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- Auths&#45;&gt;Service -->
+<g id="edge11" class="edge"><title>Auths:auth1&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M33,-81C33,-68.2561 39.6326,-56.7707 48.1141,-47.2933"/>
+<polygon fill="black" stroke="black" points="50.6575,-49.6992 55.221,-40.1376 45.6908,-44.7664 50.6575,-49.6992"/>
+</g>
+<!-- Auths&#45;&gt;Service -->
+<g id="edge13" class="edge"><title>Auths:auth2&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M84,-81C84,-70.9674 84,-60.0066 84,-50.1784"/>
+<polygon fill="black" stroke="black" points="87.5001,-50.0559 84,-40.056 80.5001,-50.056 87.5001,-50.0559"/>
+</g>
+<!-- Auths&#45;&gt;Service -->
+<g id="edge15" class="edge"><title>Auths:auth3&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M134,-81C134,-68.4835 127.626,-57.1283 119.429,-47.7009"/>
+<polygon fill="black" stroke="black" points="121.686,-45.0006 112.215,-40.2521 116.658,-49.8705 121.686,-45.0006"/>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_proxyAuth.svg b/docs/source/images/graphs_proxyAuth.svg
new file mode 100644
index 00000000..7b94b077
--- /dev/null
+++ b/docs/source/images/graphs_proxyAuth.svg
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: ProxyAuth Pages: 1 -->
+<svg width="644pt" height="74pt"
+ viewBox="0.00 0.00 644.00 73.70" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 69.7025)">
+<title>ProxyAuth</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-69.7025 641,-69.7025 641,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="348,-55.7025 250,-55.7025 250,-15.7025 348,-15.7025 348,-55.7025"/>
+<text text-anchor="middle" x="299" y="-39.1025" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="299" y="-23.1025" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.0748,-35.7025C97.1107,-35.7025 182.142,-35.7025 239.791,-35.7025"/>
+<polygon fill="black" stroke="black" points="239.864,-39.2026 249.863,-35.7025 239.863,-32.2026 239.864,-39.2026"/>
+<text text-anchor="middle" x="152" y="-38.1025" font-family="Times,serif" font-size="14.00">Authorization: Basic VTpQ</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge9" class="edge"><title>AuthComp:w&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M250,-35.7025C238.368,-35.7025 242.686,-21.2988 232,-16.7025 166.676,11.3956 141.697,-2.59182 72,-16.7025 69.1948,-17.2705 66.3471,-18.0189 63.5169,-18.8903"/>
+<polygon fill="black" stroke="black" points="62.3066,-15.6059 54.0489,-22.2437 64.6436,-22.2043 62.3066,-15.6059"/>
+<text text-anchor="middle" x="152" y="-19.1025" font-family="Times,serif" font-size="14.00">500 Internal Error</text>
+</g>
+<!-- Service -->
+<g id="node6" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="636,-55.7025 542,-55.7025 542,-15.7025 636,-15.7025 636,-55.7025"/>
+<text text-anchor="middle" x="589" y="-39.1025" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="589" y="-23.1025" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M348.195,-35.7025C399.052,-35.7025 478.372,-35.7025 531.947,-35.7025"/>
+<polygon fill="black" stroke="black" points="531.971,-39.2026 541.971,-35.7025 531.971,-32.2026 531.971,-39.2026"/>
+<text text-anchor="middle" x="445" y="-53.1025" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="445" y="-38.1025" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy U</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge7" class="edge"><title>Service:w&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M542,-35.7025C530.368,-35.7025 534.686,-21.2988 524,-16.7025 459.492,11.0444 435.553,-7.03121 366,-16.7025 363.341,-17.0723 360.639,-17.5208 357.922,-18.0316"/>
+<polygon fill="black" stroke="black" points="357.121,-14.6237 348.066,-20.1248 358.575,-21.471 357.121,-14.6237"/>
+<text text-anchor="middle" x="445" y="-19.1025" font-family="Times,serif" font-size="14.00">403 Forbidden</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_separate.svg b/docs/source/images/graphs_separate.svg
new file mode 100644
index 00000000..376e5988
--- /dev/null
+++ b/docs/source/images/graphs_separate.svg
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: Seperate Pages: 1 -->
+<svg width="106pt" height="124pt"
+ viewBox="0.00 0.00 106.00 124.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 120)">
+<title>Seperate</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-120 103,-120 103,5 -4,5"/>
+<!-- AuthComp -->
+<g id="node2" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="98,-116 0,-116 0,-76 98,-76 98,-116"/>
+<text text-anchor="middle" x="49" y="-99.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="49" y="-83.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Service -->
+<g id="node4" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="96,-40 2,-40 2,-0 96,-0 96,-40"/>
+<text text-anchor="middle" x="49" y="-23.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="49" y="-7.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge3" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M49,-75.6334C49,-67.8186 49,-58.7253 49,-50.183"/>
+<polygon fill="black" stroke="black" points="52.5001,-50.1593 49,-40.1593 45.5001,-50.1593 52.5001,-50.1593"/>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_standard_accept.svg b/docs/source/images/graphs_standard_accept.svg
new file mode 100644
index 00000000..bddf4b5f
--- /dev/null
+++ b/docs/source/images/graphs_standard_accept.svg
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: StandardAcceptAuth Pages: 1 -->
+<svg width="644pt" height="66pt"
+ viewBox="0.00 0.00 644.00 66.23" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 62.234)">
+<title>StandardAcceptAuth</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-62.234 641,-62.234 641,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="348,-48.234 250,-48.234 250,-8.23398 348,-8.23398 348,-48.234"/>
+<text text-anchor="middle" x="299" y="-31.634" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="299" y="-15.634" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.0748,-28.234C97.1107,-28.234 182.142,-28.234 239.791,-28.234"/>
+<polygon fill="black" stroke="black" points="239.864,-31.7341 249.863,-28.234 239.863,-24.7341 239.864,-31.7341"/>
+<text text-anchor="middle" x="152" y="-30.634" font-family="Times,serif" font-size="14.00">Authorization: Basic VTpQ</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge9" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M249.934,-12.6562C243.944,-11.2496 237.868,-10.0499 232,-9.23398 161.567,0.55976 141.697,4.87673 72,-9.23398 69.1948,-9.80192 66.3471,-10.5503 63.5169,-11.4218"/>
+<polygon fill="black" stroke="black" points="62.3066,-8.13733 54.0489,-14.7751 64.6436,-14.7357 62.3066,-8.13733"/>
+<text text-anchor="middle" x="152" y="-11.634" font-family="Times,serif" font-size="14.00">200 Okay</text>
+</g>
+<!-- Service -->
+<g id="node6" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="636,-48.234 542,-48.234 542,-8.23398 636,-8.23398 636,-48.234"/>
+<text text-anchor="middle" x="589" y="-31.634" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="589" y="-15.634" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+<!-- AuthComp&#45;&gt;Service -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Service</title>
+<path fill="none" stroke="black" d="M348.195,-28.234C399.052,-28.234 478.372,-28.234 531.947,-28.234"/>
+<polygon fill="black" stroke="black" points="531.971,-31.7341 541.971,-28.234 531.971,-24.7341 531.971,-31.7341"/>
+<text text-anchor="middle" x="445" y="-45.634" font-family="Times,serif" font-size="14.00">Authorization: Basic dTpw</text>
+<text text-anchor="middle" x="445" y="-30.634" font-family="Times,serif" font-size="14.00">X&#45;Authorization: Proxy U</text>
+</g>
+<!-- Service&#45;&gt;AuthComp -->
+<g id="edge7" class="edge"><title>Service&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M541.774,-12.7435C535.845,-11.2995 529.819,-10.067 524,-9.23398 454.486,0.717471 435.553,0.437338 366,-9.23398 363.341,-9.6037 360.639,-10.0522 357.922,-10.5631"/>
+<polygon fill="black" stroke="black" points="357.121,-7.15517 348.066,-12.6562 358.575,-14.0025 357.121,-7.15517"/>
+<text text-anchor="middle" x="445" y="-11.634" font-family="Times,serif" font-size="14.00">200 Okay</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_standard_reject.svg b/docs/source/images/graphs_standard_reject.svg
new file mode 100644
index 00000000..6020ad67
--- /dev/null
+++ b/docs/source/images/graphs_standard_reject.svg
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: StandardRejectAuth Pages: 1 -->
+<svg width="590pt" height="84pt"
+ viewBox="0.00 0.00 590.00 84.11" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 80.1142)">
+<title>StandardRejectAuth</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-80.1142 587,-80.1142 587,5 -4,5"/>
+<!-- Start -->
+<!-- AuthComp -->
+<g id="node4" class="node"><title>AuthComp</title>
+<polygon fill="#fdefe3" stroke="#c00000" points="470,-72.1142 372,-72.1142 372,-32.1142 470,-32.1142 470,-72.1142"/>
+<text text-anchor="middle" x="421" y="-55.5142" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="middle" x="421" y="-39.5142" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+</g>
+<!-- Start&#45;&gt;AuthComp -->
+<g id="edge3" class="edge"><title>Start&#45;&gt;AuthComp</title>
+<path fill="none" stroke="black" d="M54.087,-55.6146C59.9818,-56.239 66.1921,-56.7925 72,-57.1142 197.142,-64.0451 228.754,-61.7811 354,-57.1142 356.55,-57.0192 359.153,-56.9039 361.782,-56.7725"/>
+<polygon fill="black" stroke="black" points="362.204,-60.2543 371.991,-56.1946 361.809,-53.2655 362.204,-60.2543"/>
+<text text-anchor="middle" x="213" y="-63.5142" font-family="Times,serif" font-size="14.00">Authorization: Basic Yjpw</text>
+</g>
+<!-- AuthComp&#45;&gt;Start -->
+<g id="edge5" class="edge"><title>AuthComp&#45;&gt;Start</title>
+<path fill="none" stroke="black" d="M381.842,-32.0145C372.913,-28.3297 363.309,-25.0423 354,-23.1142 231.272,2.30687 192.234,12.2721 72,-23.1142 67.3413,-24.4853 62.7097,-26.5048 58.2883,-28.8508"/>
+<polygon fill="black" stroke="black" points="56.3831,-25.9114 49.5663,-34.022 59.9531,-31.9327 56.3831,-25.9114"/>
+<text text-anchor="middle" x="213" y="-40.5142" font-family="Times,serif" font-size="14.00">401 Unauthorized</text>
+<text text-anchor="middle" x="213" y="-25.5142" font-family="Times,serif" font-size="14.00">WWW&#45;Authenticate: Basic Realm=&quot;API Realm&quot;</text>
+</g>
+<!-- Service -->
+<g id="node8" class="node"><title>Service</title>
+<polygon fill="#d1ebf1" stroke="#1f477d" points="582,-72.1142 488,-72.1142 488,-32.1142 582,-32.1142 582,-72.1142"/>
+<text text-anchor="middle" x="535" y="-55.5142" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="middle" x="535" y="-39.5142" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/graphs_together.svg b/docs/source/images/graphs_together.svg
new file mode 100644
index 00000000..1425a28b
--- /dev/null
+++ b/docs/source/images/graphs_together.svg
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545)
+ -->
+<!-- Title: Together Pages: 1 -->
+<svg width="116pt" height="104pt"
+ viewBox="0.00 0.00 116.00 104.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 100)">
+<title>Together</title>
+<polygon fill="white" stroke="white" points="-4,5 -4,-100 113,-100 113,5 -4,5"/>
+<!-- Together -->
+<g id="node2" class="node"><title>Together</title>
+<polygon fill="#fdefe3" stroke="#fdefe3" points="8,-47 8,-91 101,-91 101,-47 8,-47"/>
+<polygon fill="none" stroke="#c00000" points="8,-47 8,-91 101,-91 101,-47 8,-47"/>
+<text text-anchor="start" x="38" y="-75.2333" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text>
+<text text-anchor="start" x="13.5" y="-58.4333" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text>
+<polygon fill="#d1ebf1" stroke="#d1ebf1" points="8,-4 8,-47 101,-47 101,-4 8,-4"/>
+<polygon fill="none" stroke="#1f477d" points="8,-4 8,-47 101,-47 101,-4 8,-4"/>
+<text text-anchor="start" x="15.5" y="-31.7333" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text>
+<text text-anchor="start" x="28" y="-14.9333" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text>
+</g>
+</g>
+</svg>
diff --git a/docs/source/images/images_layouts.svg b/docs/source/images/images_layouts.svg
new file mode 100644
index 00000000..e7fe7a95
--- /dev/null
+++ b/docs/source/images/images_layouts.svg
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="222pt"
+   height="135pt"
+   viewBox="0.00 0.00 245.00 135.00"
+   id="svg3479"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="layouts-full.svg">
+  <metadata
+     id="metadata3492">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs3490" />
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1680"
+     inkscape:window-height="1002"
+     id="namedview3488"
+     showgrid="false"
+     inkscape:zoom="1"
+     inkscape:cx="-0.58191504"
+     inkscape:cy="23.096747"
+     inkscape:window-x="0"
+     inkscape:window-y="22"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg3479" />
+  <g
+     id="layouts">
+    <title
+       id="title3482">Auth Layouts</title>
+    <text
+       text-anchor="middle"
+       x="58"
+       y="134"
+       font-family="Helvetica,sans-Serif"
+       font-size="14.00"
+       id="text3484">(a)</text>
+    <text
+       text-anchor="middle"
+       x="178"
+       y="134"
+       font-family="Helvetica,sans-Serif"
+       font-size="14.00"
+       id="text3486">(b)</text>
+  </g>
+  <g
+     id="graph1"
+     class="graph"
+     transform="matrix(0.81928538,0,0,0.77044025,18.190271,97.915731)">
+    <title
+       id="title3172">Together</title>
+    <polygon
+       style="fill:#ffffff;stroke:#ffffff"
+       points="-4,5 -4,5 -4,-100 113,-100 113,5 "
+       id="polygon3174" />
+    <!-- Together -->
+    <g
+       id="node2"
+       class="node">
+      <title
+         id="title3177">Together</title>
+      <polygon
+         style="fill:#fdefe3;stroke:#fdefe3"
+         points="8,-47 8,-47 8,-91 101,-91 101,-47 "
+         id="polygon3179" />
+      <polygon
+         style="fill:none;stroke:#c00000"
+         points="8,-47 8,-47 8,-91 101,-91 101,-47 "
+         id="polygon3181" />
+      <text
+         style="font-size:14px;text-anchor:start;font-family:'Helvetica,sans-Serif'"
+         x="38"
+         y="-75.233299"
+         font-size="14.00"
+         id="text3183">Auth</text>
+      <text
+         style="font-size:14px;text-anchor:start;font-family:'Helvetica,sans-Serif'"
+         x="13.5"
+         y="-58.4333"
+         font-size="14.00"
+         id="text3185">Component</text>
+      <polygon
+         style="fill:#d1ebf1;stroke:#d1ebf1"
+         points="8,-4 8,-4 8,-47 101,-47 101,-4 "
+         id="polygon3187" />
+      <polygon
+         style="fill:none;stroke:#1f477d"
+         points="8,-4 8,-4 8,-47 101,-47 101,-4 "
+         id="polygon3189" />
+      <text
+         style="font-size:14px;text-anchor:start;font-family:'Helvetica,sans-Serif'"
+         x="15.5"
+         y="-31.733299"
+         font-size="14.00"
+         id="text3191">OpenStack</text>
+      <text
+         style="font-size:14px;text-anchor:start;font-family:'Helvetica,sans-Serif'"
+         x="28"
+         y="-14.9333"
+         font-size="14.00"
+         id="text3193">Service</text>
+    </g>
+  </g>
+  <g
+     id="graph2"
+     class="graph"
+     transform="matrix(0.84200867,0,0,0.82332332,134.01425,108.66091)">
+    <title
+       id="title3134">Seperate</title>
+    <polygon
+       style="fill:#ffffff;stroke:#ffffff"
+       points="-4,-120 103,-120 103,5 -4,5 -4,5 "
+       id="polygon3136" />
+    <!-- AuthComp -->
+    <g
+       id="node2-9"
+       class="node">
+      <title
+         id="title3139">AuthComp</title>
+      <polygon
+         style="fill:#fdefe3;stroke:#c00000"
+         points="0,-116 0,-76 98,-76 98,-116 98,-116 "
+         id="polygon3141" />
+      <text
+         style="font-size:14px;text-anchor:middle;font-family:'Helvetica,sans-Serif'"
+         x="49"
+         y="-99.400002"
+         font-size="14.00"
+         id="text3143">Auth</text>
+      <text
+         style="font-size:14px;text-anchor:middle;font-family:'Helvetica,sans-Serif'"
+         x="49"
+         y="-83.400002"
+         font-size="14.00"
+         id="text3145">Component</text>
+    </g>
+    <!-- Service -->
+    <g
+       id="node4"
+       class="node">
+      <title
+         id="title3148">Service</title>
+      <polygon
+         style="fill:#d1ebf1;stroke:#1f477d"
+         points="2,-40 2,0 96,0 96,-40 96,-40 "
+         id="polygon3150" />
+      <text
+         style="font-size:14px;text-anchor:middle;font-family:'Helvetica,sans-Serif'"
+         x="49"
+         y="-23.4"
+         font-size="14.00"
+         id="text3152">OpenStack</text>
+      <text
+         style="font-size:14px;text-anchor:middle;font-family:'Helvetica,sans-Serif'"
+         x="49"
+         y="-7.4000001"
+         font-size="14.00"
+         id="text3154">Service</text>
+    </g>
+    <!-- AuthComp&#45;&gt;Service -->
+    <g
+       id="edge3"
+       class="edge">
+      <title
+         id="title3157">AuthComp-&gt;Service</title>
+      <path
+         style="fill:none;stroke:#000000"
+         inkscape:connector-curvature="0"
+         d="m 49,-75.6334 c 0,7.8148 0,16.9081 0,25.4504"
+         id="path3159" />
+      <polygon
+         style="fill:#000000;stroke:#000000"
+         points="52.5001,-50.1593 49,-40.1593 45.5001,-50.1593 52.5001,-50.1593 "
+         id="polygon3161" />
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/images/layouts.svg b/docs/source/images/layouts.svg
new file mode 100644
index 00000000..fdf61b7d
--- /dev/null
+++ b/docs/source/images/layouts.svg
@@ -0,0 +1,215 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="183.71901"
+   height="100.41289"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="authComp.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98901497"
+     inkscape:cx="69.71099"
+     inkscape:cy="-12.532713"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="912"
+     inkscape:window-height="842"
+     inkscape:window-x="66"
+     inkscape:window-y="87"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-305.28902,-419.41658)">
+    <g
+       id="1"
+       transform="translate(304.10174,415.42322)">
+      <path
+         d="m 117.05,14.8 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="2"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 117.05,43.6 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="3"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="26.4"
+         x="140"
+         xml:space="preserve"
+         id="4">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="37.599998"
+         x="124"
+         xml:space="preserve"
+         id="5">Component</text>
+      <path
+         d="m 117.05,72.4 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="6"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 117.05,101.2 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="7"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="84"
+         x="125.6"
+         xml:space="preserve"
+         id="8">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="95.199997"
+         x="133.60001"
+         xml:space="preserve"
+         id="9">Service</text>
+      <path
+         d="m 150.65,43.6 0,19.3"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="10"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 154.1,62.05 -3.45,10.35 -3.45,-10.35 6.9,0 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="11"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="131.2"
+         xml:space="preserve"
+         id="12">Option </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="158.39999"
+         xml:space="preserve"
+         id="13">(</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="161.60001"
+         xml:space="preserve"
+         id="14">b</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="166.39999"
+         xml:space="preserve"
+         id="15">)</text>
+      <path
+         d="m 1.85,14.8 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="16"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,43.6 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="17"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="26.4"
+         x="24.799999"
+         xml:space="preserve"
+         id="18">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="37.599998"
+         x="8.8000002"
+         xml:space="preserve"
+         id="19">Component</text>
+      <path
+         d="m 1.85,44.8 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="20"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 1.85,73.6 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="21"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="56"
+         x="10.4"
+         xml:space="preserve"
+         id="22">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="68"
+         x="18.4"
+         xml:space="preserve"
+         id="23">Service</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="13.6"
+         xml:space="preserve"
+         id="24">Option </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="41.599998"
+         xml:space="preserve"
+         id="25">(</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="44"
+         xml:space="preserve"
+         id="26">a</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="48.799999"
+         xml:space="preserve"
+         id="27">)</text>
+      <path
+         d="m 93.45,5.2 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,5.6 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-5.6 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z m 0,9.6 0,2.4 c 0,0.25 -0.15,0.4 -0.4,0.4 -0.2,0 -0.4,-0.15 -0.4,-0.4 l 0,-2.4 c 0,-0.2 0.2,-0.4 0.4,-0.4 0.25,0 0.4,0.2 0.4,0.4 z"
+         style="fill:#1f477d;fill-opacity:1;fill-rule:nonzero;stroke:#1f477d;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:bevel;stroke-opacity:1;stroke-dasharray:none"
+         id="28"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/images/mapper.svg b/docs/source/images/mapper.svg
new file mode 100644
index 00000000..b5a2b7b1
--- /dev/null
+++ b/docs/source/images/mapper.svg
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="118.9"
+   height="159.425"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="mapper.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1"
+     inkscape:cx="50.251985"
+     inkscape:cy="133.71622"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="1920"
+     inkscape:window-height="1024"
+     inkscape:window-x="-4"
+     inkscape:window-y="-4"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(106.03799,-264.63332)">
+    <g
+       id="g3015">
+      <path
+         d="m -80.18799,394.60832 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="2"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -80.18799,423.40832 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="3"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="405.85831"
+         x="-72.037987"
+         xml:space="preserve"
+         id="4">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="417.85831"
+         x="-64.037987"
+         xml:space="preserve"
+         id="5">Service</text>
+      <path
+         d="m -46.58799,265.00832 0,19.3"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="6"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -42.804657,340.4626 -3.45,10.35 -3.45,-10.35 6.9,0 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="7"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -46.58799,365.80832 0,19.3"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="10"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -43.13799,384.25832 -3.45,10.35 -3.45,-10.35 6.9,0 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="11"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -80.18799,322.60832 c -7.2,7.2 -7.2,13.45 -7.2,17.1 0,0.6 0,1.1 0,1.6"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="12"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -83.98799,340.25832 -2.8,10.55 -4.1,-10.15 6.9,-0.4 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="13"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -12.98799,322.60832 c 4.4,7 5.3,13.3 4.9,18.7"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="14"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -4.68799,340.25832 -2.9,10.55 -4,-10.15 6.9,-0.4 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="15"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -6.98799,366.40832 -17.75,20.4"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="16"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -21.58799,388.45832 -9.4,5.55 4.2,-10.1 5.2,4.55 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="17"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -85.58799,366.40832 15.25,20.05"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="18"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -68.08799,383.65832 3.5,10.35 -9,-6.15 5.5,-4.2 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="19"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -80.18799,293.80832 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#ebf1de;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="20"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -80.18799,322.60832 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#688037;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="21"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="311.45834"
+         x="-64.037987"
+         xml:space="preserve"
+         id="22">Mapper</text>
+      <path
+         d="m -105.38799,351.40832 0,14.4 38.4,0 0,-14.4 -38.4,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="23"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -105.38799,365.80832 38.4,0 0,-14.4 -38.4,0 0,14.4 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="24"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="361.85831"
+         x="-100.03799"
+         xml:space="preserve"
+         id="25">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="361.85831"
+         x="-77.637993"
+         xml:space="preserve"
+         id="26">1</text>
+      <path
+         d="m -65.78799,351.40832 0,14.4 38.4,0 0,-14.4 -38.4,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="27"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -65.78799,365.80832 38.4,0 0,-14.4 -38.4,0 0,14.4 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="28"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="361.85831"
+         x="-60.037991"
+         xml:space="preserve"
+         id="29">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="361.85831"
+         x="-38.437988"
+         xml:space="preserve"
+         id="30">2</text>
+      <path
+         d="m -26.18799,351.40832 0,14.4 38.4,0 0,-14.4 -38.4,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="31"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -26.18799,365.80832 38.4,0 0,-14.4 -38.4,0 0,14.4 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="32"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="361.85831"
+         x="-20.837988"
+         xml:space="preserve"
+         id="33">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="361.85831"
+         x="1.562013"
+         xml:space="preserve"
+         id="34">3</text>
+      <path
+         d="m -46.000001,323.49386 0,18.51832"
+         style="fill:none;stroke:#000000;stroke-width:0.73465496;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+         id="6-1"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m -42.883334,284.52051 -3.45,10.35 -3.45,-10.35 6.9,0 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="7-7"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/images/proxyAuth.svg b/docs/source/images/proxyAuth.svg
new file mode 100644
index 00000000..f60b40d8
--- /dev/null
+++ b/docs/source/images/proxyAuth.svg
@@ -0,0 +1,238 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="360.43942"
+   height="43.693935"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.0 r9654"
+   sodipodi:docname="layouts.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98901497"
+     inkscape:cx="238.80946"
+     inkscape:cy="161.99774"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:window-width="912"
+     inkscape:window-height="842"
+     inkscape:window-x="66"
+     inkscape:window-y="87"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-136.19055,-650.66599)">
+    <g
+       id="1"
+       transform="translate(134.9737,646.56521)">
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="190.39999"
+         xml:space="preserve"
+         id="2">Authorization</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="240.8"
+         xml:space="preserve"
+         id="3">: </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="10.4"
+         x="245.60001"
+         xml:space="preserve"
+         id="4">Basic dTpw</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="190.39999"
+         xml:space="preserve"
+         id="5">X</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="196"
+         xml:space="preserve"
+         id="6">-</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="199.2"
+         xml:space="preserve"
+         id="7">Authorization</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="248.8"
+         xml:space="preserve"
+         id="8">: </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="253.60001"
+         xml:space="preserve"
+         id="9">Proxy U</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="5.5999999"
+         xml:space="preserve"
+         id="10">Authorization</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="56"
+         xml:space="preserve"
+         id="11">: </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#1f477d;font-family:Arial"
+         y="20"
+         x="60.799999"
+         xml:space="preserve"
+         id="12">Basic VTpQ</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#ff0000;font-family:Arial"
+         y="31.200001"
+         x="34.400002"
+         xml:space="preserve"
+         id="13">500 </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#ff0000;font-family:Arial"
+         y="31.200001"
+         x="50.400002"
+         xml:space="preserve"
+         id="14">Internal Error</text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#ff0000;font-family:Arial"
+         y="32.799999"
+         x="190.39999"
+         xml:space="preserve"
+         id="15">403 </text>
+      <text
+         style="font-size:8.80000019px;font-style:italic;font-weight:normal;text-align:start;text-anchor:start;fill:#ff0000;font-family:Arial"
+         y="32.799999"
+         x="206.39999"
+         xml:space="preserve"
+         id="16">Proxy Unauthorized</text>
+      <path
+         d="m 114.4,23.3 c 1,12.6 -38.55,19.05 -91.35,14.85"
+         style="fill:none;stroke:#ff0000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="17"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 23.6,41.65 -10,-4.35 10.65,-2.55 -0.65,6.9 z"
+         style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="18"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 115.6,8.5 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#fdefe3;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="19"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 115.6,37.3 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#c00000;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="20"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="20"
+         x="138.39999"
+         xml:space="preserve"
+         id="21">Auth</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="31.200001"
+         x="122.4"
+         xml:space="preserve"
+         id="22">Component</text>
+      <path
+         d="M 292.6,22.9 C 295,47.25 251.2,54.6 192,39.75"
+         style="fill:none;stroke:#ff0000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="23"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 191.95,43.3 -9.15,-6 10.9,-0.7 -1.75,6.7 z"
+         style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="24"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 293.8,8.5 0,28.8 67.2,0 0,-28.8 -67.2,0 z"
+         style="fill:#d1ebf1;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="25"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 293.8,37.3 67.2,0 0,-28.8 -67.2,0 0,28.8 z"
+         style="fill:none;stroke:#1f477d;stroke-width:1.29999995px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="26"
+         inkscape:connector-curvature="0" />
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="20"
+         x="302.39999"
+         xml:space="preserve"
+         id="27">OpenStack</text>
+      <text
+         style="font-size:9.60000038px;font-style:normal;font-weight:bold;text-align:start;text-anchor:start;fill:#000000;font-family:Arial"
+         y="31.200001"
+         x="310.39999"
+         xml:space="preserve"
+         id="28">Service</text>
+      <path
+         d="m 182.8,22.9 101.5,0"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="29"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 283.45,19.4 10.35,3.5 -10.35,3.45 0,-6.95 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="30"
+         inkscape:connector-curvature="0" />
+      <path
+         d="M 1.6,22.9 106.7,22.85"
+         style="fill:none;stroke:#000000;stroke-width:0.75px;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;stroke-dasharray:none"
+         id="31"
+         inkscape:connector-curvature="0" />
+      <path
+         d="m 105.85,19.35 10.35,3.5 -10.35,3.45 0,-6.95 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:none"
+         id="32"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>
diff --git a/docs/source/middleware.rst b/docs/source/middleware.rst
new file mode 100644
index 00000000..69506ee2
--- /dev/null
+++ b/docs/source/middleware.rst
@@ -0,0 +1,169 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+==========
+Middleware
+==========
+
+The Keystone middleware sits in front of an OpenStack service and handles authenticating
+incoming requests. The middleware was designed according to `this spec`.
+
+The middleware is found in source under Keystone/middleware.
+
+The middleware supports two interfaces; WSGI and REST/HTTP.
+
+.. _`this spec`: http://wiki.openstack.org/openstack-authn
+
+REST & HTTP API
+===============
+
+If an unauthenticated call comes in, the middleware will respond with a 401 Unauthorized error. As per
+HTTP standards, it will also return a WWW-Authenticate header informing the caller
+of what protocols are supported. For Keystone authentication, the response syntax will be::
+
+    WWW-Authenticate: Keystone uri="url to Keystone server"
+
+The client can then make the necessary calls to the Keystone server, obtain a token, and retry the call with the token.
+
+The token is passed in using ther X-Auth-Token header.
+
+WSGI API (Headers)
+==================
+
+Upon successful authentication the middleware sends the following
+headers to the downstream WSGI app:
+
+X-Identity-Status
+    Provides information on whether the request was authenticated or not.
+
+X-Tenant
+    Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants.
+
+X-Tenant-Id
+    The unique, immutable tenant Id
+
+X-Tenant-Name
+    The unique, but mutable (it can change) tenant name.
+
+X-User-Id
+    The user id of the user used to log in
+
+X-User-Name
+    The username used to log in
+
+X-User
+    The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants.
+
+X-Roles
+    The roles associated with that user
+
+
+Configuration
+=============
+
+The middleware is configured within the config file of the main application as
+a WSGI component. Example for the auth_token middleware::
+
+    [app:myService]
+    paste.app_factory = myService:app_factory
+
+    [pipeline:main]
+    pipeline =
+        tokenauth
+        myService
+
+    [filter:tokenauth]
+    paste.filter_factory = keystone.middleware.auth_token:filter_factory
+    auth_host = 127.0.0.1
+    auth_port = 35357
+    auth_protocol = http
+    auth_uri = http://127.0.0.1:5000/
+    admin_token = 999888777666
+    ;Uncomment next line and check ip:port to use memcached to cache token requests
+    ;memcache_hosts = 127.0.0.1:11211
+
+*The required configuration entries are:*
+
+auth_host
+    The IP address or DNS name of the Keystone server
+
+auth_port
+    The TCP/IP port of the Keystone server
+
+auth_protocol
+    The protocol of the Keystone server ('http' or 'https')
+
+auth_uri
+    The externally accessible URL of the Keystone server. This will be where unauthenticated
+    clients are redirected to. This is in the form of a URL. For example, if they make an
+    unauthenticated call, they get this response::
+    
+        HTTP/1.1 401 Unauthorized
+        Www-Authenticate: Keystone uri='https://auth.example.com/'
+        Content-Length: 381
+    
+    In this case, the auth_uri setting is set to https://auth.example.com/
+
+admin_token
+    This is the long-lived token issued to the service to authenticate itself when calling
+    Keystone. See :doc:`configuration` for more information on setting this up.
+
+
+*Optional parameters are:*
+
+delay_auth_decision
+    Whether the middleware should reject invalid or unauthenticated calls directly or not. If not,
+    it will send all calls down to the service to decide, but it will set the HTTP-X-IDENTITY-STATUS
+    header appropriately (set to'Confirmed' or 'Indeterminate' based on validation) and the
+    service can then decide if it wants to honor the call or not. This is useful if the service offers
+    some resources publicly, for example.
+
+auth_timeout
+    The amount of time to wait before timing out a call to Keystone (in seconds)
+
+memcache_hosts
+    This is used to point to a memcached server (in ip:port format). If supplied,
+    the middleware will cache tokens and data retrieved from Keystone in memcached
+    to minimize calls made to Keystone and optimize performance.
+
+.. warning::
+    Tokens are cached for the duration of their validity. If they are revoked eariler in Keystone,
+    the service will not know and will continue to honor the token as it has them stored in memcached.
+    Also note that tokens and data stored in memcached are not encrypted. The memcached server must
+    be trusted and on a secure network.
+
+
+*Parameters needed in a distributed topology.* In this configuration, the middleware is running
+on a separate machine or cluster than the protected service (not common - see :doc:`middleware_architecture`
+for details on different deployment topologies):
+
+service_host
+    The IP address or DNS name of the location of the service (since it is remote
+    and not automatically down the WSGI chain)
+
+service_port
+    The TCP/IP port of the remote service.
+
+service_protocol
+    The protocol of the service ('http' or 'https')
+
+service_pass
+    The basic auth password used to authenticate to the service (so the service
+    knows the call is coming from a server that has validated the token and not from
+    an untrusted source or spoofer)
+
+service_timeout
+    The amount of time to wait for the service to respond before timing out.
diff --git a/docs/source/middleware_architecture.rst b/docs/source/middleware_architecture.rst
new file mode 100644
index 00000000..a8c38f3c
--- /dev/null
+++ b/docs/source/middleware_architecture.rst
@@ -0,0 +1,529 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+=======================
+Middleware Architecture
+=======================
+
+Abstract
+========
+
+The Keystone middleware architecture supports multiple authentication protocols
+in a pluggable manner in OpenStack. By providing support for authentication via
+pluggable authentication components, this architecture allows OpenStack
+services to be integrated easily into existing deployment environments. It also
+provides a path by which to implement support for emerging authentication
+standards such as OAUTH.
+
+Rationale and Goals
+===================
+
+Keystone is the Identity service for OpenStack. To support the easy integrating
+of OpenStack with existing authentication and identity management systems,
+Keystone supports talking to multiple backends like LDAP.
+And to support different deployment needs, it can support multiple
+authentication protocols via pluggable 'authentication components' implemented
+as WSGI middleware.
+
+In this document, we describe the responsibilities of the authentication
+middleware. We describe how these interact with underlying OpenStack services
+and how existing services can be modified to take advantage of pluggable
+authentication. The goal is to allow OpenStack services to be integrated easily
+into existing deployment environments and to provide a path by which to
+implement support for emerging authentication standards such as OAUTH.
+
+Specification Overview
+======================
+
+'Authentication' is the process of determining that users are who they say they
+are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest
+Access, public key, token, etc, are used to verify a user's identity. In this
+document, we define an ''authentication component'' as a software module that
+implements an authentication protocol for an OpenStack service.
+
+At a high level, an authentication component is simply a reverse proxy that
+intercepts HTTP calls from clients. Once it has verified a user's identity, the
+authentication component extends the call with information about the current
+user and forwards the request to the OpenStack service. Otherwise, if a user's
+identity is not verified, the message is rejected before it gets to the
+service. This is illustrated in :ref:`authComponent`.
+
+.. _authComponent:
+
+Authentication Component
+------------------------
+
+Figure 1. Authentication Component
+
+.. image:: images/graphs_authComp.svg
+   :width: 100%
+   :height: 180
+   :alt: An Authentication Component
+
+Authentication components may operate in 'delegated mode'. In this mode, the
+decision reject an unauthenticated client is delegated to the OpenStack
+service. Delegated mode is illustrated in :ref:`authComponentDelegated`.
+
+Here, requests are forwarded to the OpenStack service with an identity status
+message that indicates whether the client's identity has been confirmed or is
+indeterminate. It is the OpenStack service that decides whether or not a reject
+message should be sent to the client. Note that it is always the responsibility
+of the Authentication Component to transmit reject messages to the client.
+
+.. _authComponentDelegated:
+
+Authentication Component (Delegated Mode)
+-----------------------------------------
+
+Figure 2. Authentication Component (Delegated Mode)
+
+.. image:: images/graphs_authCompDelegate.svg
+   :width: 100%
+   :height: 180
+   :alt: An Authentication Component (Delegated Mode)
+
+In this architecture, we define interactions between the authentication component
+and the OpenStack service. Interactions between the client and the
+authentication component are defined only for exceptional cases. For example,
+we define the message that should be returned when the OpenStack service is
+down. Other interactions, however, are defined by the underlying authentication
+protocol and the OpenStack service and are considered out of scope.
+
+.. _deployStrategies:
+
+Deployment Strategies
+=====================
+
+An authentication component may be integrated directly into the service
+implementation, or it may be deployed separately as an HTTP reverse proxy. This
+is illustrated in :ref:`deployment`, showing both approaches to
+authentication, labeled Option (a) and Option (b).
+
+.. _deployment:
+
+Authentication Component Deployments Options
+--------------------------------------------
+
+Figure 3. Authentication Component Deployments Options
+
+.. image:: images/images_layouts.svg
+   :width: 100%
+   :height: 180
+   :alt: Authentication Component Deployments Options
+
+In Option (a), the component is integrated into the service implementation. In
+this case, communication between the authentication component and the service
+can be efficiently implemented via a method call. In Option (b), the component
+is deployed separately and communication between the service and the component
+involves an HTTP request. In both cases, unauthenticated requests are filtered
+before they reach the service.
+
+Each approach offers some benefits. Option (a) offers low latency and ease of
+initial implementation, making it possibly most appropriate as a starting point
+for simple configurations. Option (b) offers several key advantages that may be
+of particular value in complex and dynamic configurations. It offers the
+ability to scale horizontally in cases where authentication is computationally
+expensive, such as when verifying digital signatures. Option (b) also allows
+authentication components to be written in different programming languages.
+Finally, Option (b) allows multiple authentication components to be deployed in
+front of the same service.
+
+OpenStack services can support both embedded (Option (a)) and external (Option
+(b)) deployment strategies. Individual authentication components should support
+either strategy or they |may| support both strategies. In order to support
+option (a), authentication components written in the Python programming
+language should be written as WSGI middleware components (in accordance with
+the Web Server Gateway Interface (WSGI) standard [PEP-333]_.
+
+Additionally, services should support the ability to swap between different
+embedded or external authentication components via configuration options.
+
+Exchanging User Information
+===========================
+
+If a request is successfully authenticated, the authentication component must
+extend the request by adding an ``X-Authorization`` header. The header |must|
+be formatted as illustrated in :ref:`xAuthHeader`.
+
+.. _xAuthHeader:
+
+X-Authorization Header
+----------------------
+
+Example 1. X-Authorization Header::
+
+    X-Authorization: Proxy JoeUser
+
+Here, `Proxy` denotes that the authentication occurred via a proxy (in this
+case authentication component) and ''JoeUser'' is the name of the user who
+issued the request.
+
+.. note:
+
+   We considered using an ``Authorization`` header rather than an
+   ``X-Authorization``, thereby following normal HTTP semantics. There are some
+   cases, however, where multiple ``Authorization`` headers need to be transmitted
+   in a single request. We want to assure ourselves that this will not break
+   common clients before we recommend the approach.
+
+Authentication components |may| extend the request with additional
+information. For example, an authentication system may add additional headers
+or modify the target URI to pass authentication information to the back-end
+service. Additionally, an authentication component |may| strip sensitive
+information — a plain text password, for example — from the request. That said,
+an authentication component |should| pass the majority of the request
+unmodified.
+
+Reverse Proxy Authentication
+----------------------------
+
+An OpenStack service |should| verify that it is receiving requests from a
+trusted authentication component. This is particularly important in cases where
+the authentication component and the OpenStack service are deployed separately.
+In order to trust incoming requests, the OpenStack service should therefore
+authenticate the authentication component. To avoid confusion, we call this
+'reverse proxy authentication', since in this case the authentication
+component is acting as an HTTP reverse proxy.
+
+Any HTTP-based authentication scheme may be used for reverse proxy
+authentication; however, all OpenStack services and all authentication
+components |must| support HTTP Basic Authentication as defined in
+[RFC-2617]_.
+
+Whether or not reverse proxy authentication is required is strictly a
+deployment concern. For example, an operations team may opt to utilize firewall
+rules instead of an authentication protocol to verify the integrity of incoming
+request. Because of this, both OpenStack services and authentication components
+|must| also allow for unauthenticated communication.
+
+In cases where reverse proxy authentication is used, the authorization
+component may receive an HTTP 401 authentication error or an HTTP 403
+authorization error. These errors indicate that the component does not have
+access to the underlying OpenStack service. The authentication component
+|must not| return these errors to the client application. Instead, the
+component |must| return a 500 internal error. This is illustrated in
+:ref:`proxyAuth` and :ref:`proxyAuthDelegated` below. The component
+|should| format the errors in a manner that does not break the service
+contract defined by the OpenStack service. :ref:`proxyAuthDelegated`
+illustrates proxy authorization in delegated mode. Delegated mode is discussed
+in detail in the next section.
+
+.. _proxyAuth:
+
+Reverse Proxy Authentication
+----------------------------
+
+Figure 4. Reverse Proxy Authentication
+
+.. image:: images/graphs_proxyAuth.svg
+   :width: 100%
+   :height: 180
+   :alt: Reverse Proxy Authentication
+
+.. _proxyAuthDelegated:
+
+Reverse Proxy Authentication (Delegated Mode)
+---------------------------------------------
+
+Figure 5. Reverse Proxy Authentication (Delegated Mode)
+
+.. image:: images/graphs_delegate_forbiden_proxy.svg
+   :width: 100%
+   :height: 180
+   :alt: Reverse Proxy Authentication (Delegated Mode)
+
+Delegated Mode
+==============
+In some cases, the decision to reject an unauthenticated request should be
+delegated to the OpenStack service. An unauthenticated request may be
+appropriate in cases when anonymous access is allowed. In order to support
+these cases, an authentication component may be placed in Delegated Mode. In
+this mode, the component forwards requests to the OpenStack service when the
+client's identity has been confirmed or is indeterminate — that is when
+credentials are missing. The authentication component directly rejects requests
+with invalid credentials. Authentication components |must| extend the
+request by adding an `X-Identity-Status` header. The identity status header
+|must| contain one of the following values:
+
+Identity Status Values
+----------------------
+
+Confirmed
+    A `confirmed` value indicates that valid credentials were sent and identity
+    has been confirmed. The service can trust that the request has been sent on
+    behalf of the user specified in the `X-Authorization` header.
+
+Indeterminate
+    An `indeterminate` value indicates that no credentials were sent and
+    identity has not been confirmed. In this case, the service will receive an
+    `X-Authorization` header with no user entry as illustrated in
+    :ref:`xauth-header-indeterminate`.
+
+.. _xauth-header-indeterminate:
+
+Indeterminate Identity Headers
+------------------------------
+
+Example 2. Indeterminate Identity Headers::
+
+    X-Identity-Status: Indeterminate
+    X-Authorization: Proxy
+
+Services |may| reject a delegated request by issuing an HTTP 401
+authentication error or an HTTP 403 authorization error. These responses
+|must| contain an ``WWW-Authenticate`` header with a value of ``Delegated`` as
+illustrated in :ref:`unauthHeaders`.
+
+X-Identity-Status
+    Provides information on whether the request was authenticated or not.
+
+X-Tenant
+    Provides the tenant ID (as it appears in the URL in Keystone). This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants.
+
+X-Tenant-Id
+    The unique, immutable tenant Id
+
+X-Tenant-Name
+    The unique, but mutable (it can change) tenant name.
+
+X-User-Id
+    The user id of the user used to log in
+
+X-User-Name
+    The username used to log in
+
+X-User
+    The username used to log in. This is to support any legacy implementations before Keystone switched to an ID/Name schema for tenants.
+
+X-Roles
+    The roles associated with that user
+
+.. _unauthHeaders:
+
+Delegated WWW-Authenticate Header
+---------------------------------
+
+::
+
+    WWW-Authenticate: Delegated
+
+It is important to note that the actual reject message will likely be modified
+by the authentication component in order to comply with the authentication
+scheme it is implementing. This is illustrated in :ref:`delegateRejectBasic` and
+:ref:`delegateRejectOAuth` below.
+
+.. _delegateRejectBasic:
+
+Delegated Reject Basic Auth
+---------------------------
+
+.. image:: images/graphs_delegate_reject_basic.svg
+   :width: 100%
+   :height: 180
+   :alt: Delegated Reject Basic Auth
+
+.. _delegateRejectOAuth:
+
+Delegated Reject OAuth
+----------------------
+
+.. image:: images/graphs_delegate_reject_oauth.svg
+   :width: 100%
+   :height: 180
+   :alt: Delegated Reject OAuth
+
+The presence of the `WWW-Authenticate` header with a value of `Delegated`
+distinguishes a client authentication/authorization failure from a component
+failure. For example, compare :ref:`delegateForbidden` with :ref:`proxyAuthDelegated`. In
+:ref:`delegateForbidden`, the client is not allowed to access the OpenStack service.
+In :ref:`proxyAuthDelegated`, it is the authentication component itself which is
+unauthorized.
+
+.. _delegateForbidden:
+
+Delegated Reject Forbidden
+--------------------------
+
+Figure 8. Delegated Reject Forbidden
+
+.. image:: images/graphs_delegate_forbiden_basic.svg
+   :width: 100%
+   :height: 180
+   :alt: Delegated Reject Forbidden
+
+Authentication components |must| support both delegated and undelegated
+(standard) modes. Delegated mode |should| be configured via a configuration
+option. Delegated mode |should| be disabled by default.
+
+OpenStack services are not required to support delegated mode. If a service
+does not support delegated mode, it |must| respond with a 501 not implemented
+error and an `WWW-Authenticate` header with a value of `Delegated`. The
+authentication component |must not| return the error to the client
+application. Instead, the component |must| return a 500 internal error; this is
+illustrated in :ref:`delegateUnimplemented`. The component |should|
+format the error in a manner that does not break the service contract defined
+by the OpenStack service. The component should also log the error such that it
+that will inform operators of the misconfiguration.
+
+.. _delegateUnimplemented:
+
+Unimplemented Delegated Mode
+----------------------------
+
+.. image:: images/graphs_delegate_unimplemented.svg
+   :width: 100%
+   :height: 180
+   :alt: Unimplemented Delegated Mode
+
+Handling Direct Client Connections
+==================================
+
+Requests from the authentication component to an OpenStack service |must|
+contain an ``X-Authorization`` header. If the header is missing, and reverse
+proxy authentication fails or is switched off, the OpenStack service |may|
+assume that the request is coming directly from a client application. In this
+case, the OpenStack service |must| redirect the request to the authentication
+component by issuing an HTTP 305 User Proxy redirect. This is illustrated in
+:ref:`redirect`. Note that the redirect response |must| include a ``Location`` header
+specifying the authentication component's URL as shown in :ref:`redirect-response`.
+
+.. _redirect:
+
+Auth Component Redirect
+-----------------------
+
+.. image:: images/graphs_305.svg
+   :width: 100%
+   :height: 280
+   :alt: Auth Component Redirect
+
+.. _redirect-response:
+
+Auth Component Redirect Response
+--------------------------------
+
+::
+
+    HTTP/1.1 305 Use Proxy
+    Date: Thu, 28 Oct 2011 07:41:16 GMT
+    Location: http://sample.auth.openstack.com/path/to/resource
+
+Using Multiple Authentication Components
+========================================
+
+There are some use cases when a service provider might want to consider using
+multiple authentication components for different purposes. For instance, a
+service provider may have one authentication scheme to authenticate the users
+of the service and another one to authenticate the administrators or operations
+personnel that maintain the service. For such scenarios, we propose using a
+mapper as illustrated in :ref:`multiAuth`.
+
+.. _multiAuth:
+
+Multiple Authentication Components
+----------------------------------
+
+.. image:: images/graphs_mapper.svg
+   :width: 100%
+   :height: 320
+   :alt: Multiple Authentication Components
+
+At a high level, a mapper is a simple reverse proxy that intercepts HTTP calls
+from clients and routes the request to the appropriate authentication
+component. A mapper can make the routing decisions based on a number of routing
+rules that map a resource to a specific authentication component. For example,
+a request URI may determine whether a call should be authenticated via one
+authentication component or another.
+
+Note that neither the authentication component nor the OpenStack service need
+be aware of the mapper. Any external authentication component can be used
+alongside others. Mappers may provide a means by which to offer support for
+anonymous or guest access to a subset of service resources. A mapper may be
+implemented via a traditional reverse proxy server such as Pound or Zeus.
+
+The Default Component
+=====================
+
+Individual services |must| be distributed with a simple integrated
+authentication component by default. Providing such a component lowers barriers
+to the deployment of individual services. This is especially important to]
+developers who may want to deploy OpenStack services on their own machines.
+Also, since there is no direct dependency on an external authentication system,
+OpenStack services can be deployed individually, without the need to stand up
+and configure additional services. Finally, having a standard authentication
+component that all services share promotes a separation of concerns. That is,
+as a community we are explicitly stating that services should not develop their
+own authentication mechanisms. Additional authentication components may be
+developed, of course, but these components should not be intimately coupled to
+any one particular service.
+
+As discussed in :ref:`deployStrategies`, an authentication component may be
+integrated directly into the service implementation (Option (a)), or it may be
+deployed separately as an HTTP reverse proxy (Option (b)). The default
+component should be implemented to support Option (a) and services should
+maintain support for Option (b). One way to achieve this is to provide a
+method that allows the disabling of the default authentication component via
+configuration. This is illustrated in :ref:`both`. Here, requests are
+sent directly to the OpenStack service when the default authentication
+component is disabled.
+
+We will discuss the design of the default component in an upcoming blueprint.
+
+.. _both:
+
+Disabled Embedded Component
+---------------------------
+
+.. image:: images/graphs_both.svg
+   :width: 100%
+   :height: 250
+   :alt: Disabled Embedded Component
+
+Questions and Answers
+=====================
+
+#. Why do authentication components send reject messages? Why not have
+   OpenStack services reject requests themselves?
+
+   The content and format of an authentication failed message is determined by
+   the authentication scheme (or protocol). For the service to respond
+   appropriately, it would have to be aware of the authentication scheme in
+   which it participates; this defeats the purpose of pluggable authentication
+   components.
+
+#. Why require support for deploying authentication components in separate
+   nodes?
+
+   The deployment strategy is very flexible. It allows for authentication
+   components to be horizontally scalable. It allows for components to be written
+   in different languages. Finally, it allows different authentication components
+   to be deployed simultaneously as described above.
+
+References
+==========
+
+.. [PEP-333] pep0333 Phillip J Eby.  'Python Web Server Gateway Interface
+    v1.0.''  http://www.python.org/dev/peps/pep-0333/.
+
+.. [RFC-2617] rfc2617 J Franks.  P Hallam-Baker.  J Hostetler.  S Lawrence.
+    P Leach.  A Luotonen.  L Stewart.  ''HTTP Authentication: Basic and Digest
+    Access Authentication.''  http://tools.ietf.org/html/rfc2617.
+
+.. |must| replace:: must must
+.. |should| replace:: should should
+.. |may| replace:: may may
+.. |must not| replace:: "must not" "must not"
+
diff --git a/docs/source/migration.rst b/docs/source/migration.rst
new file mode 100644
index 00000000..460d980b
--- /dev/null
+++ b/docs/source/migration.rst
@@ -0,0 +1,126 @@
+===================
+Database Migrations
+===================
+
+Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage
+migrations.
+
+Migrations are tracked using a metadata table (``migrate_version``), which
+allows keystone to compare the state of your database to the state it
+expects, and to move between versions.
+
+.. WARNING::
+
+    Backup your database before applying migrations. Migrations may
+    attempt to modify both your schema and data, and could result in data
+    loss.
+
+    Always review the behavior of migrations in a staging environment
+    before applying them in production.
+
+Getting Started
+===============
+
+Your initial approach to migrations should depend on whether you have an
+empty database or a schema full of data.
+
+Starting with an empty database
+-------------------------------
+
+If you have an empty database for keystone to work with, you can simply
+run::
+
+    $ ./bin/keystone-manage database sync
+
+This command will initialize your metadata table, and run through all the
+schema & data migrations necessary to bring your database in sync with
+keystone. That's it!
+
+Starting with an existing database
+----------------------------------
+
+Place an existing database under version control to enable migration
+support::
+
+    $ ./bin/keystone-manage database version_control
+
+This command simply creates a ``migrate_version`` table, set at
+``version_number`` 0, which indicates that no migrations have been applied.
+
+If you are starting with an existing schema, you can jump to a specific
+schema version without performing migrations using the ``database goto``
+command. For example, if you're starting from a diablo-compatible
+database, set your current database ``version_number`` to ``1`` using::
+
+    $ ./bin/keystone-manage database goto <version_number>
+
+Determine your appropriate database ``version_number`` by referencing the
+following table:
+
+    +------------+-------------+
+    | Release    | ``version`` |
+    +============+=============+
+    | pre-diablo | (see below) |
+    +------------+-------------+
+    | diablo     | 1           |
+    +------------+-------------+
+    | essex-m1   | 3           |
+    +------------+-------------+
+    | essex-m2   | 4           |
+    +------------+-------------+
+
+From there, you can upgrade normally (see :ref:`upgrading`).
+
+Starting with a pre-diablo database (cactus)
+--------------------------------------------
+
+You'll need to manually migrate your database to a diablo-compatible
+schema, and continue forward from there (if desired) using migrations.
+
+.. _upgrading:
+
+Upgrading & Downgrading
+=======================
+
+.. note::
+
+    Attempting to start keystone with an outdated schema will cause
+    keystone to abort, to avoid corrupting your data.
+
+Upgrade to the latest version automatically::
+
+    $ ./bin/keystone-manage database sync
+
+Check your current schema version::
+
+    $ ./bin/keystone-manage database version
+
+Jump to a specific version without performing migrations::
+
+    $ ./bin/keystone-manage database goto <version_number>
+
+Upgrade to a specific version::
+
+    $ ./bin/keystone-manage database upgrade <version_number>
+
+Downgrade to a specific version (will likely result in data loss!)::
+
+    $ ./bin/keystone-manage database downgrade <version_number>
+
+Opting Out of Migrations
+========================
+
+If you don't want to use migrations (e.g. if you want to manage your
+schema manually), keystone will complain in your logs on startup, but
+won't actually stop you from doing so.
+
+It's recommended that you use migrations to get up and running, but if
+you want to manage migrations manually after that, simply drop the
+``migrate_version`` table::
+
+    DROP TABLE migrate_version;
+
+Useful Links
+============
+
+Principles to follow when developing migrations `OpenStack Deployability <http://wiki.openstack.org/OpenstackDeployability>`_
diff --git a/docs/source/nova-api-paste.rst b/docs/source/nova-api-paste.rst
new file mode 100644
index 00000000..586bac72
--- /dev/null
+++ b/docs/source/nova-api-paste.rst
@@ -0,0 +1,142 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+nova-api-paste example
+======================
+::
+
+    #######
+    # EC2 #
+    #######
+
+    [composite:ec2]
+    use = egg:Paste#urlmap
+    /: ec2versions
+    /services/Cloud: ec2cloud
+    /services/Admin: ec2admin
+    /latest: ec2metadata
+    /2007-01-19: ec2metadata
+    /2007-03-01: ec2metadata
+    /2007-08-29: ec2metadata
+    /2007-10-10: ec2metadata
+    /2007-12-15: ec2metadata
+    /2008-02-01: ec2metadata
+    /2008-09-01: ec2metadata
+    /2009-04-04: ec2metadata
+    /1.0: ec2metadata
+
+    [pipeline:ec2cloud]
+    pipeline = logrequest totoken authtoken keystonecontext cloudrequest authorizer ec2executor
+
+    [pipeline:ec2admin]
+    pipeline = logrequest totoken authtoken keystonecontext adminrequest authorizer ec2executor
+
+    [pipeline:ec2metadata]
+    pipeline = logrequest ec2md
+
+    [pipeline:ec2versions]
+    pipeline = logrequest ec2ver
+
+    [filter:logrequest]
+    paste.filter_factory = nova.api.ec2:RequestLogging.factory
+
+    [filter:ec2lockout]
+    paste.filter_factory = nova.api.ec2:Lockout.factory
+
+    [filter:totoken]
+    paste.filter_factory = keystone.middleware.ec2_token:EC2Token.factory
+
+    [filter:ec2noauth]
+    paste.filter_factory = nova.api.ec2:NoAuth.factory
+
+    [filter:authenticate]
+    paste.filter_factory = nova.api.ec2:Authenticate.factory
+
+    [filter:cloudrequest]
+    controller = nova.api.ec2.cloud.CloudController
+    paste.filter_factory = nova.api.ec2:Requestify.factory
+
+    [filter:adminrequest]
+    controller = nova.api.ec2.admin.AdminController
+    paste.filter_factory = nova.api.ec2:Requestify.factory
+
+    [filter:authorizer]
+    paste.filter_factory = nova.api.ec2:Authorizer.factory
+
+    [app:ec2executor]
+    paste.app_factory = nova.api.ec2:Executor.factory
+
+    [app:ec2ver]
+    paste.app_factory = nova.api.ec2:Versions.factory
+
+    [app:ec2md]
+    paste.app_factory = nova.api.ec2.metadatarequesthandler:MetadataRequestHandler.factory
+
+    #############
+    # Openstack #
+    #############
+
+    [composite:osapi]
+    use = egg:Paste#urlmap
+    /: osversions
+    /v1.1: openstackapi
+
+    [pipeline:openstackapi]
+    pipeline = faultwrap authtoken keystonecontext ratelimit extensions osapiapp
+
+    [filter:faultwrap]
+    paste.filter_factory = nova.api.openstack:FaultWrapper.factory
+
+    [filter:auth]
+    paste.filter_factory = nova.api.openstack.auth:AuthMiddleware.factory
+
+    [filter:noauth]
+    paste.filter_factory = nova.api.openstack.auth:NoAuthMiddleware.factory
+
+    [filter:ratelimit]
+    paste.filter_factory = nova.api.openstack.limits:RateLimitingMiddleware.factory
+
+    [filter:extensions]
+    paste.filter_factory = nova.api.openstack.extensions:ExtensionMiddleware.factory
+
+    [app:osapiapp]
+    paste.app_factory = nova.api.openstack:APIRouter.factory
+
+    [pipeline:osversions]
+    pipeline = faultwrap osversionapp
+
+    [app:osversionapp]
+    paste.app_factory = nova.api.openstack.versions:Versions.factory
+
+    ##########
+    # Shared #
+    ##########
+
+    [filter:keystonecontext]
+    paste.filter_factory = keystone.middleware.nova_keystone_context:NovaKeystoneContext.factory
+
+    [filter:authtoken]
+    paste.filter_factory = keystone.middleware.auth_token:filter_factory
+    service_protocol = http
+    service_host = 127.0.0.1
+    service_port = 5000
+    auth_host = 127.0.0.1
+    auth_port = 35357
+    auth_protocol = http
+    auth_uri = http://127.0.0.1:5000/
+    admin_token = 999888777666
+    ;Uncomment next line and check ip:port to use memcached to cache token requests
+    ;memcache_hosts = 127.0.0.1:11211
diff --git a/docs/source/releases.rst b/docs/source/releases.rst
new file mode 100644
index 00000000..a4b698d7
--- /dev/null
+++ b/docs/source/releases.rst
@@ -0,0 +1,36 @@
+=============
+Release notes
+=============
+
+
+E3 (January 26, 2012)
+==========================================
+* Contract compliance: version response and ATOM, 300 multiple choice
+* Global endpoints returned for unscoped calls
+* adminUrl only shown to admin clients
+* Endpoints have unique ID
+* Auth-N/Auth-Z for S3 API (OS-KSS3 extension)
+* Default tenant scope optionally returned when authenticating
+* Vary header returned for caching proxies
+
+* Portable identifiers: modifiable, string identifiers in database backend
+* Much improved keystone-manage command (see --help and docs)
+* OS-KSVALIDATE extension to support not passing tokens in URL
+* OS-KSEC2 and OS-KSS3 extensions respond on /tokens
+* HP-IDM extension to filter roles to a given service ID
+* Additional caching options in middleware (memcache and swift cache)
+
+* Enhanced configuration management (in line with other OpenStack projects)
+* Additional logging
+* Enhanced tracer tool (-t or --trace-calls)
+
+See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3
+
+
+E2 (December 15, 2011)
+========================
+* D5 compatibility middleware
+* Database versioning
+* Much more documentation: http://keystone.openstack.org
+
+See https://launchpad.net/keystone/+milestone/essex-2
diff --git a/docs/source/serviceAPI_curl_examples.rst b/docs/source/serviceAPI_curl_examples.rst
new file mode 100644
index 00000000..d05afc9f
--- /dev/null
+++ b/docs/source/serviceAPI_curl_examples.rst
@@ -0,0 +1,69 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+===============================
+Service API Examples Using Curl
+===============================
+
+The service API is defined to be a subset of the Admin API and, by
+default, runs on port 5000.
+
+GET /
+=====
+
+This call is identical to that documented for the Admin API, except
+that it uses port 5000, instead of port 35357, by default::
+
+    $ curl http://0.0.0.0:5000
+
+or::
+
+    $ curl http://0.0.0.0:5000/v2.0/
+
+See the `Admin API Examples Using Curl`_ for more info.
+
+.. _`Admin API Examples Using Curl`: adminAPI_curl_examples.html
+
+GET /extensions
+===============
+
+This call is identical to that documented for the Admin API.
+
+POST /tokens
+============
+
+This call is identical to that documented for the Admin API.
+
+GET /tenants
+============
+
+List all of the tenants your token can access::
+
+    $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants
+
+Returns::
+
+    {
+        "tenants_links": [],
+        "tenants": [
+            {
+                "enabled": true,
+                "description": "None",
+                "name": "customer-x",
+                "id": "1"
+            }
+        ]
+    }
diff --git a/docs/source/services.rst b/docs/source/services.rst
new file mode 100644
index 00000000..d1c33381
--- /dev/null
+++ b/docs/source/services.rst
@@ -0,0 +1,92 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+================
+Services
+================
+
+.. toctree::
+   :maxdepth: 1
+
+
+What are services?
+==================
+
+Keystone includes service registry and service catalog functionality which it
+uses to respond to client authentication requests with information useful to
+clients in locating the list of available services they can access.
+
+The Service entity in Keystone represents an OpenStack service that is integrated
+with Keystone. The Service entity is also used as a reference from roles, endpoints,
+and endpoint templates.
+
+Keystone also includes an authorization mechanism to allow a service to own
+its own roles and endpoints and prevent other services from changing or
+modifying them.
+
+Who can create services?
+========================
+
+Any user with the Admin or Service Admin roles in Keystone may create services.
+
+How are services created?
+=========================
+
+Services can be created using ``keystone-manage`` or through the REST API using
+the OS-KSADM extension calls.
+
+Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details)::
+
+    $ keystone-manage add service compute nova 'This is a sample compute service'
+
+Using the REST API (see `extensions dev guide <https://github.com/openstack/keystone/blob/master/keystone/content/admin/OS-KSADM-admin-devguide.pdf?raw=true>`_ for details)::
+
+    $ curl -H "Content-type: application/json" -X POST -d '{
+                "OS-KSADM:service": {
+                    "name": "nova",
+                    "type": "compute",
+                    "description": "This is a sample compute service"
+                }
+            }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/
+
+How is service ownership determined?
+====================================
+
+Currently, the way to assign ownership to a service is to provide the owner's
+user id in the keystone-manage add command::
+
+    $ keystone-manage add service nova compute 'This is a sample compute service' joeuser
+
+This will assign ownership to the new service to joeuser.
+
+When a service has an owner, then only that owner (or a global Admin) can create and manage
+roles that start with that service name (ex: "nova:admin") and manage endpoints
+and endpoint templates associated with that service.
+
+Listing services
+================
+
+Using ``keystone-manage``, the list of services and their owners can be listed::
+
+    $ keystone-manage service list
+
+    id  name    type     owner_id      description
+    -------------------------------------------------------------------------------
+    1   compute nova     joeuser       This is a sample compute service
+
+Using the REST API, call ``GET /v2.0/OS-KSADM/services``
+
+.. note: The rest API does not yet support service ownership
diff --git a/docs/source/ssl.rst b/docs/source/ssl.rst
new file mode 100644
index 00000000..839e951e
--- /dev/null
+++ b/docs/source/ssl.rst
@@ -0,0 +1,118 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+===========================
+x.509 Client Authentication
+===========================
+
+Purpose
+=======
+
+Allows the Keystone middleware to authenticate itself with the Keystone server
+via an x.509 client certificate.  Both Service API and Admin API may be secured
+with this feature.
+
+Certificates
+============
+
+The following types of certificates are required.  A set of certficates is provided
+in the examples/ssl directory with the Keystone distribution for testing.  Here
+is the description of each of them and their purpose:
+
+ca.pem
+    Certificate Authority chain to validate against.
+
+keystone.pem
+    Public certificate for Keystone server.
+
+middleware-key.pem
+    Public and private certificate for Keystone middleware.
+
+cakey.pem
+    Private key for the CA.
+
+keystonekey.pem
+    Private key for the Keystone server.
+
+Note that you may choose whatever names you want for these certificates, or combine
+the public/private keys in the same file if you wish.  These certificates are just
+provided as an example.
+
+Configuration
+=============
+
+By default, the Keystone server does not use SSL. To enable SSL with client authentication,
+modify the etc/keystone.conf file accordingly:
+
+1. To enable SSL for Service API::
+
+       service_ssl = True
+
+2. To enable SSL for Admin API::
+
+       admin_ssl = True
+
+3. To enable SSL client authentication::
+
+       cert_required = True
+
+4. Set the location of the Keystone certificate file (example)::
+
+       certfile = /etc/keystone/ca/certs/keystone.pem
+
+5. Set the location of the Keystone private file (example)::
+
+       keyfile = /etc/keystone/ca/private/keystonekey.pem
+
+6. Set the location of the CA chain::
+
+       ca_certs = /etc/keystone/ca/certs/ca.pem
+
+Middleware
+==========
+
+Add the following to your middleware configuration to support x.509 client authentication.
+If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters
+in steps 3) and 4) may be commented out.
+
+1. Specify 'https' as the auth_protocol::
+
+       auth_protocol = https
+
+2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured
+   for SSL::
+
+       auth_uri = https://localhost:5000/
+
+3. Set the location of the middleware certificate file (example)::
+
+       certfile = /etc/keystone/ca/certs/middleware-key.pem
+
+4. Set the location of the Keystone private file (example)::
+
+       keyfile = /etc/keystone/ca/certs/middleware-key.pem
+
+For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example
+service in the examples/echo directory.
+
+Testing
+=======
+
+You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory
+and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with
+the path to the client certificate::
+
+    python echo_client.py -s <path to client certificate>
diff --git a/docs/source/usingkeystone.rst b/docs/source/usingkeystone.rst
new file mode 100644
index 00000000..bb52a94d
--- /dev/null
+++ b/docs/source/usingkeystone.rst
@@ -0,0 +1,28 @@
+..
+      Copyright 2011 OpenStack, LLC
+      All Rights Reserved.
+
+      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.
+
+==============
+Using Keystone
+==============
+
+Curl examples
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   adminAPI_curl_examples
+   serviceAPI_curl_examples