Update Keystone code from official Github repository with branch Master on 09/01/2015.

Change-Id: I0ff6099e6e2580f87f502002a998bbfe12673498

27 files changed, 2205 insertions, 336 deletions

diff --git a/keystone-moon/doc/source/apache-httpd.rst b/keystone-moon/doc/source/apache-httpd.rst
index c075512f..91eb7011 100644
--- a/keystone-moon/doc/source/apache-httpd.rst
+++ b/keystone-moon/doc/source/apache-httpd.rst
@@ -31,38 +31,38 @@ Running Keystone in HTTPD
 Files
 -----
 
-Copy the file httpd/wsgi-keystone.conf to the appropriate location for your
-Apache server, most likely::
+Copy the ``httpd/wsgi-keystone.conf`` sample configuration file to the
+appropriate location for your Apache server::
 
-    /etc/httpd/conf.d/wsgi-keystone.conf
+    /etc/$APACHE_DIR/conf.d/sites-available/wsgi-keystone.conf
 
-Update this file to match your system configuration (for example, some
-distributions put httpd logs in the ``apache2`` directory and some in the
-``httpd`` directory; also, enable TLS).
+Where ``$APACHE_DIR`` is ``httpd`` on Fedora-based systems and ``apache2`` on
+Debian/Ubuntu systems.
 
-Create the directory ``/var/www/cgi-bin/keystone/``. You can either hardlink or
-softlink the files ``main`` and ``admin`` to the file ``keystone.py`` in this
-directory. For a distribution appropriate place, it should probably be copied
-to::
+Update the file to match your system configuration. Note the following:
 
-    /usr/share/openstack/keystone/httpd/keystone.py
+* Make sure the correct log directory is used. Some distributions put httpd
+  server logs in the ``apache2`` directory and some in the ``httpd`` directory.
+* Enable TLS by supplying the correct certificates.
 
 Keystone's primary configuration file (``etc/keystone.conf``) and the
 PasteDeploy configuration file (``etc/keystone-paste.ini``) must be readable to
 HTTPD in one of the default locations described in :doc:`configuration`.
 
-SELinux
--------
+Enable the site by creating a symlink from ``sites-enabled`` to the file in
+``sites-available``::
 
-If you are running with SELinux enabled (and you should be) make sure that the
-file has the appropriate SELinux context to access the linked file. If you
-have the file in /var/www/cgi-bin,  you can do this by running:
+  ln -s /etc/$APACHE_DIR/sites-available/keystone.conf /etc/$APACHE_DIR/sites-enabled/
 
-.. code-block:: bash
+Restart Apache to have it start serving keystone.
 
-    $ sudo restorecon /var/www/cgi-bin
 
-Putting it somewhere else requires you set up your SELinux policy accordingly.
+Access Control
+--------------
+
+If you are running with Linux kernel security module enabled (for example
+SELinux or AppArmor) make sure that the file has the appropriate context to
+access the linked file.
 
 Keystone Configuration
 ----------------------
@@ -74,20 +74,20 @@ between processes.
 
 .. WARNING::
 
-    The KVS (``keystone.token.persistence.backends.kvs.Token``) token
-    persistence driver cannot be shared between processes so must not be used
-    when running keystone under HTTPD (the tokens will not be shared between
-    the processes of the server and validation will fail).
+    The KVS (``kvs``) token persistence driver cannot be shared between
+    processes so must not be used when running keystone under HTTPD (the tokens
+    will not be shared between the processes of the server and validation will
+    fail).
 
 For SQL, in ``/etc/keystone/keystone.conf`` set::
 
     [token]
-    driver = keystone.token.persistence.backends.sql.Token
+    driver = sql
 
 For memcached, in ``/etc/keystone/keystone.conf`` set::
 
     [token]
-    driver = keystone.token.persistence.backends.memcache.Token
+    driver = memcache
 
 All servers that are storing tokens need a shared backend. This means that
 either all servers use the same database server or use a common memcached pool.
diff --git a/keystone-moon/doc/source/api_curl_examples.rst b/keystone-moon/doc/source/api_curl_examples.rst
index a4b31553..c88c7fd0 100644
--- a/keystone-moon/doc/source/api_curl_examples.rst
+++ b/keystone-moon/doc/source/api_curl_examples.rst
@@ -72,8 +72,8 @@ Example response::
   "id": "ef303187fc8d41668f25199c298396a5"}], "type": "identity", "id":
   "bd73972c0e14fb69bae8ff76e112a90", "name": "keystone"}], "extras": {},
   "user": {"domain": {"id": "default", "name": "Default"}, "id":
-  "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, "issued_at":
-  "201406-10T20:55:16.806027Z"}}
+  "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, "audit_ids":
+  ["yRt0UrxJSs6-WYJgwEMMmg"], "issued_at": "201406-10T20:55:16.806027Z"}}
 
 
 Project-scoped
@@ -116,11 +116,11 @@ Example response::
   Content-Length: 960
   Date: Tue, 10 Jun 2014 20:40:14 GMT
 
-  {"token": {"methods": ["password"], "roles": [{"id":
-   "c703057be878458588961ce9a0ce686b", "name": "admin"}], "expires_at":
-   "2014-06-10T21:40:14.360795Z", "project": {"domain": {"id": "default",
-   "name": "Default"}, "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c", "name":
-   "demo"}, "catalog": [{"endpoints": [{"url":
+  {"token": {"audit_ids": ["ECwrVNWbSCqmEgPnu0YCRw"], "methods": ["password"],
+   "roles": [{"id": "c703057be878458588961ce9a0ce686b", "name": "admin"}],
+   "expires_at": "2014-06-10T21:40:14.360795Z", "project": {"domain": {"id":
+   "default", "name": "Default"}, "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c",
+   "name": "demo"}, "catalog": [{"endpoints": [{"url":
    "http://localhost:35357/v2.0", "region": "RegionOne", "interface": "admin",
    "id": "29beb2f1567642eb810b042b6719ea88"}, {"url":
    "http://localhost:5000/v2.0", "region": "RegionOne", "interface":
@@ -184,7 +184,8 @@ Example response::
   "id": "ef303187fc8d41668f25199c298396a5"}], "type": "identity", "id":
   "bd7397d2c0e14fb69bae8ff76e112a90", "name": "keystone"}], "extras": {},
   "user": {"domain": {"id": "default", "name": "Default"}, "id":
-  "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, "issued_at":
+  "3ec3164f750146be97f21559ee4d9c51", "name": "admin"},
+  "audit_ids": ["Xpa6Uyn-T9S6mTREudUH3w"], "issued_at":
   "2014-06-10T20:52:58.852194Z"}}
 
 
@@ -219,23 +220,11 @@ Example response::
   Content-Length: 1034
   Date: Tue, 10 Jun 2014 21:00:05 GMT
 
-  {"token": {"methods": ["token", "password"], "roles": [{"id":
-  "9fe2ff9ee4384b1894a90878d3e92bab", "name": "_member_"}, {"id":
-  "c703057be878458588961ce9a0ce686b", "name": "admin"}], "expires_at":
-  "2014-06-10T21:55:16.806001Z", "project": {"domain": {"id": "default",
-  "name": "Default"}, "id": "8538a3f13f9541b28c2620eb19065e45", "name":
-  "admin"}, "catalog": [{"endpoints": [{"url": "http://localhost:35357/v2.0",
-  "region": "RegionOne", "interface": "admin", "id":
-  "29beb2f1567642eb810b042b6719ea88"}, {"url": "http://localhost:5000/v2.0",
-  "region": "RegionOne", "interface": "internal", "id":
-  "87057e3735d4415c97ae231b4841eb1c"}, {"url": "http://localhost:5000/v2.0",
-  "region": "RegionOne", "interface": "public", "id":
-  "ef303187fc8d41668f25199c298396a5"}], "type": "identity", "id":
-  "bd7397d2c0e14fb69bae8ff76e112a90", "name": "keystone"}], "extras": {},
-  "user": {"domain": {"id": "default", "name": "Default"}, "id":
-  "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, "issued_at":
-  "2014-06-10T21:00:05.548559Z"}}
-
+  {"token": {"methods": ["token", "password"], "expires_at":
+  "2015-05-28T07:43:44.808209Z", "extras": {}, "user": {"domain": {"id":
+  "default", "name": "Default"}, "id": "753867c25c3340ffad1abc22d488c31a",
+  "name": "admin"}, "audit_ids": ["ZE0OPSuzTmCXHo0eIOYltw",
+  "xxIQCkHOQOywL0oY6CTppQ"], "issued_at": "2015-05-28T07:19:23.763532Z"}}
 
 .. note::
 
@@ -755,7 +744,53 @@ and supported media types:
 
     $ curl http://0.0.0.0:35357
 
-or:
+.. code-block:: javascript
+
+    {
+        "versions": {
+            "values": [
+                {
+                    "id": "v3.4",
+                    "links": [
+                        {
+                            "href": "http://127.0.0.1:35357/v3/",
+                            "rel": "self"
+                        }
+                    ],
+                    "media-types": [
+                        {
+                            "base": "application/json",
+                            "type": "application/vnd.openstack.identity-v3+json"
+                        }
+                    ],
+                    "status": "stable",
+                    "updated": "2015-03-30T00:00:00Z"
+                },
+                {
+                    "id": "v2.0",
+                    "links": [
+                        {
+                            "href": "http://127.0.0.1:35357/v2.0/",
+                            "rel": "self"
+                        },
+                        {
+                            "href": "http://docs.openstack.org/",
+                            "rel": "describedby",
+                            "type": "text/html"
+                        }
+                    ],
+                    "media-types": [
+                        {
+                            "base": "application/json",
+                            "type": "application/vnd.openstack.identity-v2.0+json"
+                        }
+                    ],
+                    "status": "stable",
+                    "updated": "2014-04-17T00:00:00Z"
+                }
+            ]
+        }
+    }
 
 .. code-block:: bash
 
@@ -766,27 +801,27 @@ Returns:
 .. code-block:: javascript
 
     {
-        "version":{
-            "id":"v2.0",
-            "status":"beta",
-            "updated":"2011-11-19T00:00:00Z",
-            "links":[
+        "version": {
+            "id": "v2.0",
+            "links": [
                 {
-                    "rel":"self",
-                    "href":"http://127.0.0.1:35357/v2.0/"
+                    "href": "http://127.0.0.1:35357/v2.0/",
+                    "rel": "self"
                 },
                 {
-                    "rel":"describedby",
-                    "type":"text/html",
-                    "href":"http://docs.openstack.org/"
-                },
+                    "href": "http://docs.openstack.org/",
+                    "rel": "describedby",
+                    "type": "text/html"
+                }
             ],
-            "media-types":[
+            "media-types": [
                 {
-                    "base":"application/json",
-                    "type":"application/vnd.openstack.identity-v2.0+json"
+                    "base": "application/json",
+                    "type": "application/vnd.openstack.identity-v2.0+json"
                 }
-            ]
+            ],
+            "status": "stable",
+            "updated": "2014-04-17T00:00:00Z"
         }
     }
 
diff --git a/keystone-moon/doc/source/community.rst b/keystone-moon/doc/source/community.rst
index e1df0b89..dfb0870f 100644
--- a/keystone-moon/doc/source/community.rst
+++ b/keystone-moon/doc/source/community.rst
@@ -65,10 +65,10 @@ Keystone on Launchpad
 
 Launchpad is a code hosting that OpenStack is using to track bugs, feature
 work, and releases of OpenStack. Like other OpenStack projects, Keystone source
-code is hosted on GitHub
+code is hosted on git.openstack.org
 
 * `Keystone Project Page on Launchpad <http://launchpad.net/keystone>`_
-* `Keystone Source Repository on GitHub <http://github.com/openstack/keystone>`_
+* `Keystone Source Repository <https://git.openstack.org/cgit/openstack/keystone>`_
 
 Within launchpad, we use
 `blueprints <https://blueprints.launchpad.net/keystone>`_, to track feature
diff --git a/keystone-moon/doc/source/conf.py b/keystone-moon/doc/source/conf.py
index fe46f326..7cca2857 100644
--- a/keystone-moon/doc/source/conf.py
+++ b/keystone-moon/doc/source/conf.py
@@ -24,14 +24,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('..'))  # NOTE(dstanek): path for our
-                                           # Sphinx extension
 
 # NOTE(dstanek): adds _ to the builtins so keystone modules can be imported
 __builtins__['_'] = str
@@ -49,10 +43,6 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.coverage',
               'sphinx.ext.viewcode',
               'oslosphinx',
-              # NOTE(dstanek): Uncomment the [pbr] section in setup.cfg and
-              # remove this Sphinx extension when
-              # https://launchpad.net/bugs/1260495 is fixed.
-              'ext.apidoc',
               ]
 
 todo_include_todos = True
diff --git a/keystone-moon/doc/source/configuration.rst b/keystone-moon/doc/source/configuration.rst
index e365f0ed..96491660 100644
--- a/keystone-moon/doc/source/configuration.rst
+++ b/keystone-moon/doc/source/configuration.rst
@@ -156,10 +156,6 @@ configuration file.
 Domain-specific Drivers
 -----------------------
 
-.. NOTE::
-
-    This functionality is new in Juno.
-
 Keystone supports the option (disabled by default) to specify identity driver
 configurations on a domain by domain basis, allowing, for example, a specific
 domain to have its own LDAP or SQL server. This is configured by specifying the
@@ -182,12 +178,74 @@ the primary configuration file for the specified domain only. Domains without a
 specific configuration file will continue to use the options from the primary
 configuration file.
 
+Keystone also supports the ability to store the domain-specific configuration
+options in the keystone SQL database, managed via the Identity API, as opposed
+to using domain-specific configuration files.
+
 .. NOTE::
 
-    It is important to notice that by enabling this configuration, the
-    operations of listing all users and listing all groups are not supported,
-    those calls will need that either a domain filter is specified or the usage
-    of a domain scoped token.
+    The ability to store and manage configuration options via the Identity API
+    is new and experimental in Kilo.
+
+This capability (which is disabled by default) is enabled by specifying the
+following options in the main keystone configuration file:
+
+.. code-block:: ini
+
+ [identity]
+ domain_specific_drivers_enabled = true
+ domain_configurations_from_database = true
+
+Once enabled, any existing domain-specific configuration files in the
+configuration directory will be ignored and only those domain-specific
+configuration options specified via the Identity API will be used.
+
+Unlike the file-based method of specifying domain-specific configurations,
+options specified via the Identity API will become active without needing to
+restart the keystone server. For performance reasons, the current state of
+configuration options for a domain are cached in the keystone server, and in
+multi-process and multi-threaded keystone configurations, the new
+configuration options may not become active until the cache has timed out. The
+cache settings for domain config options can be adjusted in the general
+keystone configuration file (option ``cache_time`` in the ``domain_config``
+group).
+
+.. NOTE::
+
+    It is important to notice that when using either of these methods of
+    specifying domain-specific configuration options, the main keystone
+    configuration file is still maintained. Only those options that relate
+    to the Identity driver for users and groups (i.e. specifying whether the
+    driver for this domain is SQL or LDAP, and, if LDAP, the options that
+    define that connection) are supported in a domain-specific manner. Further,
+    when using the configuration options via the Identity API, the driver
+    option must be set to an LDAP driver (attempting to set it to an SQL driver
+    will generate an error when it is subsequently used).
+
+For existing installations that already use file-based domain-specific
+configurations who wish to migrate to the SQL-based approach, the
+``keystone-manage`` command can be used to upload all configuration files to
+the SQL database:
+
+.. code-block:: bash
+
+    $ keystone-manage domain_config_upload --all
+
+Once uploaded, these domain-configuration options will be visible via the
+Identity API as well as applied to the domain-specific drivers. It is also
+possible to upload individual domain-specific configuration files by
+specifying the domain name:
+
+.. code-block:: bash
+
+    $ keystone-manage domain_config_upload --domain-name DOMAINA
+
+.. NOTE::
+
+    It is important to notice that by enabling either of the domain-specific
+    configuration methods, the operations of listing all users and listing all
+    groups are not supported, those calls will need either a domain filter to
+    be specified or usage of a domain scoped token.
 
 .. NOTE::
 
@@ -197,17 +255,21 @@ configuration file.
 
 .. NOTE::
 
-    To delete a domain that uses a domain specific backend, it's necessary to
-    first disable it, remove its specific configuration file (i.e. its
-    corresponding keystone.<domain_name>.conf) and then restart the Identity
-    server.
+    When using the file-based domain-specific configuration method, to delete a
+    domain that uses a domain specific backend, it's necessary to first disable
+    it, remove its specific configuration file (i.e. its corresponding
+    keystone.<domain_name>.conf) and then restart the Identity server. When
+    managing configuration options via the Identity API, the domain can simply
+    be disabled and deleted via the Identity API; since any domain-specific
+    configuration options will automatically be removed.
 
 .. NOTE::
 
-    Although Keystone supports multiple LDAP backends via domain specific
-    configuration files, it currently only supports one SQL backend. This could
-    be either the default driver or a single domain-specific backend, perhaps
-    for storing service users in a predominantly LDAP installation.
+    Although Keystone supports multiple LDAP backends via the above
+    domain-specific configuration methods, it currently only supports one SQL
+    backend. This could be either the default driver or a single
+    domain-specific backend, perhaps for storing service users in a
+    predominantly LDAP installation.
 
 Due to the need for user and group IDs to be unique across an OpenStack
 installation and for Keystone to be able to deduce which domain and backend to
@@ -274,8 +336,8 @@ wish to make use of other generator algorithms that have a different trade-off
 of attributes. A different generator can be installed by configuring the
 following property:
 
-* ``generator`` - identity mapping generator. Defaults to
-  ``keystone.identity.generators.sha256.Generator``
+* ``generator`` - identity mapping generator. Defaults to ``sha256``
+  (implemented by :class:`keystone.identity.id_generators.sha256.Generator`)
 
 .. WARNING::
 
@@ -309,7 +371,7 @@ How to Implement an Authentication Plugin
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 All authentication plugins must extend the
-``keystone.auth.core.AuthMethodHandler`` class and implement the
+:class:`keystone.auth.core.AuthMethodHandler` class and implement the
 ``authenticate()`` method. The ``authenticate()`` method expects the following
 parameters.
 
@@ -332,7 +394,7 @@ return the payload in the form of a dictionary for the next authentication
 step.
 
 If authentication is unsuccessful, the ``authenticate()`` method must raise a
-``keystone.exception.Unauthorized`` exception.
+:class:`keystone.exception.Unauthorized` exception.
 
 Simply add the new plugin name to the ``methods`` list along with your plugin
 class configuration in the ``[auth]`` sections of the configuration file to
@@ -365,30 +427,28 @@ provides three non-test persistence backends. These can be set with the
 
 The drivers Keystone provides are:
 
-* ``keystone.token.persistence.backends.memcache_pool.Token`` - The pooled
-  memcached token persistence engine. This backend supports the concept of
-  pooled memcache client object (allowing for the re-use of the client
-  objects). This backend has a number of extra tunable options in the
-  ``[memcache]`` section of the config.
+* ``memcache_pool`` - The pooled memcached token persistence engine. This
+  backend supports the concept of pooled memcache client object (allowing for
+  the re-use of the client objects). This backend has a number of extra tunable
+  options in the ``[memcache]`` section of the config. Implemented by
+  :class:`keystone.token.persistence.backends.memcache_pool.Token`
 
-* ``keystone.token.persistence.backends.sql.Token`` - The SQL-based (default)
-  token persistence engine.
+* ``sql`` - The SQL-based (default) token persistence engine. Implemented by
+  :class:`keystone.token.persistence.backends.sql.Token`
 
-* ``keystone.token.persistence.backends.memcache.Token`` - The memcached based
-  token persistence backend. This backend relies on ``dogpile.cache`` and
-  stores the token data in a set of memcached servers. The servers URLs are
-  specified in the ``[memcache]\servers`` configuration option in the Keystone
-  config.
+* ``memcache`` - The memcached based token persistence backend. This backend
+  relies on ``dogpile.cache`` and stores the token data in a set of memcached
+  servers. The servers URLs are specified in the ``[memcache]\servers``
+  configuration option in the Keystone config. Implemented by
+  :class:`keystone.token.persistence.backends.memcache.Token`
 
 
 .. WARNING::
-    It is recommended you use the
-    ``keystone.token.persistence.backends.memcache_pool.Token`` backend instead
-    of ``keystone.token.persistence.backends.memcache.Token`` as the token
-    persistence driver if you are deploying Keystone under eventlet instead of
-    Apache + mod_wsgi. This recommendation is due to known issues with the use
-    of ``thread.local`` under eventlet that can allow the leaking of memcache
-    client objects and consumption of extra sockets.
+    It is recommended you use the ``memcache_pool`` backend instead of
+    ``memcache`` as the token persistence driver if you are deploying Keystone
+    under eventlet instead of Apache + mod_wsgi. This recommendation is due to
+    known issues with the use of ``thread.local`` under eventlet that can allow
+    the leaking of memcache client objects and consumption of extra sockets.
 
 
 Token Provider
@@ -399,8 +459,8 @@ Keystone supports customizable token provider and it is specified in the
 PKI token providers. However, users may register their own token provider by
 configuring the following property.
 
-* ``provider`` - token provider driver. Defaults to
-  ``keystone.token.providers.uuid.Provider``
+* ``provider`` - token provider driver. Defaults to ``uuid``. Implemented by
+  :class:`keystone.token.providers.uuid.Provider`
 
 
 UUID, PKI, PKIZ, or Fernet?
@@ -749,7 +809,7 @@ following states:
   deployment at all times). In a multi-node Keystone deployment this would
   allow for the *staged* key to be replicated to all Keystone nodes before
   being promoted to *primary* on a single node. This prevents the case where a
-  *primary* key is created on one Keystone node and tokens encryted/signed with
+  *primary* key is created on one Keystone node and tokens encrypted/signed with
   that new *primary* are rejected on another Keystone node because the new
   *primary* doesn't exist there yet.
 
@@ -790,7 +850,7 @@ A dynamic database-backed driver fully supporting persistent configuration.
 .. code-block:: ini
 
     [catalog]
-    driver = keystone.catalog.backends.sql.Catalog
+    driver = sql
 
 .. NOTE::
 
@@ -805,7 +865,7 @@ To build your service catalog using this driver, see the built-in help:
     $ openstack help endpoint create
 
 You can also refer to `an example in Keystone (tools/sample_data.sh)
-<https://github.com/openstack/keystone/blob/master/tools/sample_data.sh>`_.
+<https://git.openstack.org/cgit/openstack/keystone/tree/tools/sample_data.sh>`_.
 
 File-based Service Catalog (``templated.Catalog``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -826,7 +886,7 @@ catalog will not change very much over time.
 .. code-block:: ini
 
     [catalog]
-    driver = keystone.catalog.backends.templated.Catalog
+    driver = templated
     template_file = /opt/stack/keystone/etc/default_catalog.templates
 
 The value of ``template_file`` is expected to be an absolute path to your
@@ -835,7 +895,7 @@ Keystone, however you should create your own to reflect your deployment.
 
 Another such example is `available in devstack
 (files/default_catalog.templates)
-<https://github.com/openstack-dev/devstack/blob/master/files/default_catalog.templates>`_.
+<https://git.openstack.org/cgit/openstack-dev/devstack/tree/files/default_catalog.templates>`_.
 
 Logging
 -------
@@ -1121,10 +1181,10 @@ The following attributes are available
   would ensure that the user object that is being deleted is in the same
   domain as the token provided.
 
-Every target object has an `id` and a `name` available as `target.<object>.id`
-and `target.<object>.name`. Other attributes are retrieved from the database
-and vary between object types. Moreover, some database fields are filtered out
-(e.g. user passwords).
+Every target object (except token) has an `id` and a `name` available as
+`target.<object>.id` and `target.<object>.name`. Other attributes are retrieved
+from the database and vary between object types. Moreover, some database fields
+are filtered out (e.g. user passwords).
 
 List of object attributes:
 
@@ -1158,6 +1218,10 @@ List of object attributes:
     * target.project.id
     * target.project.name
 
+* token
+    * target.token.user_id
+    * target.token.user.domain.id
+
 The default policy.json file supplied provides a somewhat basic example of API
 protection, and does not assume any particular use of domains. For multi-domain
 configuration installations where, for example, a cloud provider wishes to
@@ -1186,7 +1250,7 @@ Ensure that your ``keystone.conf`` is configured to use a SQL driver:
 .. code-block:: ini
 
     [identity]
-    driver = keystone.identity.backends.sql.Identity
+    driver = sql
 
 You may also want to configure your ``[database]`` settings to better reflect
 your environment:
@@ -1234,6 +1298,10 @@ through the normal REST API. At the moment, the following calls are supported:
 
 * ``db_sync``: Sync the database.
 * ``db_version``: Print the current migration version of the database.
+* ``domain_config_upload``: Upload domain configuration file.
+* ``fernet_rotate``: Rotate keys in the Fernet key repository.
+* ``fernet_setup``: Setup a Fernet key repository.
+* ``mapping_engine``: Test your federation mapping rules.
 * ``mapping_purge``: Purge the identity mapping table.
 * ``pki_setup``: Initialize the certificates used to sign tokens.
 * ``saml_idp_metadata``: Generate identity provider metadata.
@@ -1629,23 +1697,23 @@ enable this option, you must have the following ``keystone.conf`` options set:
 .. code-block:: ini
 
   [identity]
-  driver = keystone.identity.backends.ldap.Identity
+  driver = ldap
 
   [resource]
-  driver = keystone.resource.backends.sql.Resource
+  driver = sql
 
   [assignment]
-  driver = keystone.assignment.backends.sql.Assignment
+  driver = sql
 
   [role]
-  driver = keystone.assignment.role_backends.sql.Role
+  driver = sql
 
 With the above configuration, Keystone will only lookup identity related
 information such users, groups, and group membership from the directory, while
 resources, roles and assignment related information will be provided by the SQL
 backend. Also note that if there is an LDAP Identity, and no resource,
 assignment or role backend is specified, they will default to LDAP. Although
-this may seem counterintuitive, it is provided for backwards compatibility.
+this may seem counter intuitive, it is provided for backwards compatibility.
 Nonetheless, the explicit option will always override the implicit option, so
 specifying the options as shown above will always be correct.  Finally, it is
 also worth noting that whether or not the LDAP accessible directory is to be
@@ -1662,7 +1730,7 @@ section:
 
 .. NOTE::
 
-    While having identity related infomration backed by LDAP while other
+    While having identity related information backed by LDAP while other
     information is backed by SQL is a supported configuration, as shown above;
     the opposite is not true. If either resource or assignment drivers are
     configured for LDAP, then Identity must also be configured for LDAP.
@@ -1671,32 +1739,31 @@ Connection Pooling
 ------------------
 
 Various LDAP backends in Keystone use a common LDAP module to interact with
-LDAP data. By default, a new connection is established for LDAP operations.
-This can become highly expensive when TLS support is enabled which is a likely
-configuraton in enterprise setup. Re-using of connectors from a connection pool
-drastically reduces overhead of initiating a new connection for every LDAP
+LDAP data. By default, a new connection is established for each LDAP operation.
+This can become highly expensive when TLS support is enabled, which is a likely
+configuration in an enterprise setup. Reuse of connectors from a connection
+pool drastically reduces overhead of initiating a new connection for every LDAP
 operation.
 
-Keystone now provides connection pool support via configuration. This change
-will keep LDAP connectors alive and re-use for subsequent LDAP operations. A
-connection lifespan is going to be configurable with other pooling specific
-attributes. The change is made in LDAP handler layer logic which is primarily
-responsible for LDAP connection and shared common operations.
-
-In LDAP identity driver, Keystone authenticates end user by LDAP bind with user
-DN and provided password. These kind of auth binds can fill up the pool pretty
-quickly so a separate pool is provided for those end user auth bind calls. If a
-deployment does not want to use pool for those binds, then it can disable
-pooling selectively by ``use_auth_pool`` as false. If a deployment wants to use
-pool for those auth binds, then ``use_auth_pool`` needs to be true. For auth
-pool, a different pool size (``auth_pool_size``) and connection lifetime
-(``auth_pool_connection_lifetime``) can be specified. With enabled auth pool,
-its connection lifetime should be kept short so that pool frequently re-binds
-the connection with provided creds and works reliably in end user password
-change case. When ``use_pool`` is false (disabled), then auth pool
-configuration is also not used.
-
-Connection pool configuration is added in ``[ldap]`` configuration section:
+Keystone provides connection pool support via configuration. This will keep
+LDAP connectors alive and reused for subsequent LDAP operations. The connection
+lifespan is configurable as other pooling specific attributes.
+
+In the LDAP identity driver, Keystone authenticates end users via an LDAP bind
+with the user's DN and provided password. This kind of authentication bind
+can fill up the pool pretty quickly, so a separate pool is provided for end
+user authentication bind calls. If a deployment does not want to use a pool for
+those binds, then it can disable pooling selectively by setting
+``use_auth_pool`` to false. If a deployment wants to use a pool for those 
+authentication binds, then ``use_auth_pool`` needs to be set to true. For the
+authentication pool, a different pool size (``auth_pool_size``) and connection
+lifetime (``auth_pool_connection_lifetime``) can be specified. With an enabled
+authentication pool, its connection lifetime should be kept short so that the
+pool frequently re-binds the connection with the provided credentials and works
+reliably in the end user password change case. When ``use_pool`` is false
+(disabled), then the authentication pool configuration is also not used.
+
+Connection pool configuration is part of the ``[ldap]`` configuration section:
 
 .. code-block:: ini
 
diff --git a/keystone-moon/doc/source/configure_federation.rst b/keystone-moon/doc/source/configure_federation.rst
index 2da5f822..09d0984d 100644
--- a/keystone-moon/doc/source/configure_federation.rst
+++ b/keystone-moon/doc/source/configure_federation.rst
@@ -34,54 +34,72 @@ Keystone as a Service Provider (SP)
 Prerequisites
 -------------
 
-This approach to federation supports Keystone as a Service Provider, consuming
+This approach to federation supports keystone as a Service Provider, consuming
 identity properties issued by an external Identity Provider, such as SAML
 assertions or OpenID Connect claims.
 
-Federated users are not mirrored in the Keystone identity backend
+Federated users are not mirrored in the keystone identity backend
 (for example, using the SQL driver). The external Identity Provider is
 responsible for authenticating users, and communicates the result of
-authentication to Keystone using identity properties. Keystone maps these
-values to Keystone user groups and assignments created in Keystone.
+authentication to keystone using identity properties. Keystone maps these
+values to keystone user groups and assignments created in keystone.
 
 The following configuration steps were performed on a machine running
 Ubuntu 12.04 and Apache 2.2.22.
 
 To enable federation, you'll need to:
 
-1. Run Keystone under Apache, rather than using ``keystone-all``.
+1. Run keystone under Apache, rather than using ``keystone-all``.
 2. Configure Apache to use a federation capable authentication method.
-3. Enable ``OS-FEDERATION`` extension.
+3. Configure ``federation`` in keystone.
 
 Configure Apache to use a federation capable authentication method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are many ways to configure Federation in the Apache HTTPD server.
-Using Shibboleth and OpenID Connect are documented so far.
+There is currently support for two major federation protocols:
 
-* To use Shibboleth, follow the steps outlined at: `Setup Shibboleth`_.
-* To use OpenID Connect, follow the steps outlined at: `Setup OpenID Connect`_.
+* SAML - Keystone supports the following implementations:
 
-.. _`Setup Shibboleth`: extensions/shibboleth.html
-.. _`Setup OpenID Connect`: extensions/openidc.html
+  * Shibboleth - see `Setup Shibboleth`_.
+  * Mellon - see `Setup Mellon`_.
 
-Enable the ``OS-FEDERATION`` extension
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* OpenID Connect - see `Setup OpenID Connect`_.
 
-Follow the steps outlined at: `Enabling Federation Extension`_.
+.. _`Setup Shibboleth`: federation/shibboleth.html
+.. _`Setup OpenID Connect`: federation/openidc.html
+.. _`Setup Mellon`: federation/mellon.html
 
-.. _`Enabling Federation Extension`: extensions/federation.html
+Configure keystone and Horizon for Single Sign-On
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Configuring Federation
-----------------------
+* To configure horizon to access a federated keystone,
+  follow the steps outlined at: `Keystone Federation and Horizon`_.
 
-Now that the Identity Provider and Keystone are communicating we can start to
-configure the ``OS-FEDERATION`` extension.
+.. _`Keystone Federation and Horizon`: federation/websso.html
 
-1. Add local Keystone groups and roles
-2. Add Identity Provider(s), Mapping(s), and Protocol(s)
+Configuring Federation in Keystone
+-----------------------------------
+
+Now that the Identity Provider and keystone are communicating we can start to
+configure ``federation``.
+
+1. Configure authentication drivers in ``keystone.conf``
+2. Add local keystone groups and roles
+3. Add Identity Provider(s), Mapping(s), and Protocol(s)
+
+Configure authentication drivers in ``keystone.conf``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add the authentication methods to the ``[auth]`` section in ``keystone.conf``.
+Names should be equal to protocol names added via Identity API v3. Here we use
+examples ``saml2`` and ``openid``.
 
-Create Keystone groups and assign roles
+.. code-block:: bash
+
+       [auth]
+       methods = external,password,token,saml2,openid
+
+Create keystone groups and assign roles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As mentioned earlier, no new users will be added to the Identity backend, but
@@ -109,14 +127,14 @@ To utilize federation the following must be created in the Identity Service:
 * Mapping
 * Protocol
 
-More information on ``OS-FEDERATION`` can be found `here
+More information on ``federation in keystone`` can be found `here
 <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html>`__.
 
 ~~~~~~~~~~~~~~~~~
 Identity Provider
 ~~~~~~~~~~~~~~~~~
 
-Create an Identity Provider object in Keystone, which represents the Identity
+Create an Identity Provider object in keystone, which represents the Identity
 Provider we will use to authenticate end users.
 
 More information on identity providers can be found `here
@@ -129,8 +147,10 @@ A mapping is a list of rules. The only Identity API objects that will support ma
 and users.
 
 Mapping adds a set of rules to map federation protocol attributes to Identity API objects.
-An Identity Provider has exactly one mapping specified per protocol.
+There are many different ways to setup as well as combine these rules. More information on
+rules can be found on the :doc:`mapping_combinations` page.
 
+An Identity Provider has exactly one mapping specified per protocol.
 Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol.
 
 More information on mapping can be found `here
@@ -150,7 +170,7 @@ you want to use with the combination of the IdP and Protocol.
 Performing federated authentication
 -----------------------------------
 
-1. Authenticate externally and generate an unscoped token in Keystone
+1. Authenticate externally and generate an unscoped token in keystone
 2. Determine accessible resources
 3. Get a scoped token
 
@@ -243,11 +263,22 @@ Keystone as an Identity Provider (IdP)
     that will not be backported). These issues have been fixed and this feature
     is considered stable and supported as of the Kilo release.
 
+.. NOTE::
+
+    This feature requires installation of the xmlsec1 tool via your
+    distribution packaging system (for instance apt or yum)
+
+    Example for apt:
+
+    .. code-block:: bash
+
+            $ apt-get install xmlsec1
+
 Configuration Options
 ---------------------
 
 There are certain settings in ``keystone.conf`` that must be setup, prior to
-attempting to federate multiple Keystone deployments.
+attempting to federate multiple keystone deployments.
 
 Within ``keystone.conf``, assign values to the ``[saml]`` related fields, for
 example:
@@ -270,7 +301,7 @@ also be setup. It is recommended that these values be URL safe.
     idp_organization_display_name=Example Corp.
     idp_organization_url=example.com
 
-As with the Organizaion options, the Contact options, are not necessary, but
+As with the Organization options, the Contact options, are not necessary, but
 it's advisable to set these values too.
 
 .. code-block:: ini
@@ -286,7 +317,7 @@ Generate Metadata
 -----------------
 
 In order to create a trust between the IdP and SP, metadata must be exchanged.
-To create metadata for your Keystone IdP, run the ``keystone-manage`` command
+To create metadata for your keystone IdP, run the ``keystone-manage`` command
 and pipe the output to a file. For example:
 
 .. code-block:: bash
@@ -304,33 +335,44 @@ In this example we are creating a new Service Provider with an ID of ``BETA``,
 a ``sp_url`` of ``http://beta.example.com/Shibboleth.sso/POST/ECP`` and a
 ``auth_url`` of ``http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth``
 . The ``sp_url`` will be used when creating a SAML assertion for ``BETA`` and
-signed by the current Keystone IdP. The ``auth_url`` is used to retrieve the
-token for ``BETA`` once the SAML assertion is sent.
+signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
+token for ``BETA`` once the SAML assertion is sent. Although the ``enabled``
+field is optional we are passing it set to ``true`` otherwise it will be set to
+``false`` by default.
 
 .. code-block:: bash
 
     $ curl -s -X PUT \
       -H "X-Auth-Token: $OS_TOKEN" \
       -H "Content-Type: application/json" \
-      -d '{"service_provider": {"auth_url": "http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth", "sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP"}' \
+      -d '{"service_provider": {"auth_url": "http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth", "sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP", "enabled": true}' \
       http://localhost:5000/v3/service_providers/BETA | python -mjson.tool
 
 Testing it all out
 ------------------
 
-Lastly, if a scoped token and a Service Provider region are presented to
-Keystone, the result will be a full SAML Assertion, signed by the IdP
-Keystone, specifically intended for the Service Provider Keystone.
+Lastly, if a scoped token and a Service Provider scope are presented to the
+local keystone, the result will be a full ECP wrapped SAML Assertion,
+specifically intended for the Service Provider keystone.
+
+.. NOTE::
+    ECP stands for Enhanced Client or Proxy, an extension from the SAML2
+    protocol used in non-browser interfaces, like in the following example
+    with cURL.
 
 .. code-block:: bash
 
     $ curl -s -X POST \
       -H "Content-Type: application/json" \
       -d '{"auth": {"scope": {"service_provider": {"id": "BETA"}}, "identity": {"token": {"id": "d793d935b9c343f783955cf39ee7dc3c"}, "methods": ["token"]}}}' \
-      http://localhost:5000/v3/auth/OS-FEDERATION/saml2
+      http://localhost:5000/v3/auth/OS-FEDERATION/saml2/ecp
+
+.. NOTE::
+    Use URL http://localhost:5000/v3/auth/OS-FEDERATION/saml2 to request for
+    pure SAML Assertions.
 
-At this point the SAML Assertion can be sent to the Service Provider Keystone
-using the provided ``auth_url`` in the ``X-Auth-Url`` header present in the
-response containing the SAML Assertion, and a valid OpenStack token, issued by
-a Service Provider Keystone, will be returned.
+At this point the ECP wrapped SAML Assertion can be sent to the Service
+Provider keystone using the provided ``auth_url`` in the ``X-Auth-Url`` header
+present in the response containing the Assertion, and a valid OpenStack
+token, issued by a Service Provider keystone, will be returned.
 
diff --git a/keystone-moon/doc/source/developing.rst b/keystone-moon/doc/source/developing.rst
index 33b2dd58..50fed9e5 100644
--- a/keystone-moon/doc/source/developing.rst
+++ b/keystone-moon/doc/source/developing.rst
@@ -48,7 +48,7 @@ To run the Keystone Admin and API server instances, use:
 
 .. code-block:: bash
 
-    $ tools/with_venv.sh bin/keystone-all
+    $ tools/with_venv.sh keystone-all
 
 This runs Keystone with the configuration the etc/ directory of the project.
 See :doc:`configuration` for details on how Keystone is configured. By default,
@@ -74,7 +74,8 @@ place:
 
     $ bin/keystone-manage db_sync
 
-.. _`python-keystoneclient`: https://github.com/openstack/python-keystoneclient
+.. _`python-keystoneclient`: https://git.openstack.org/cgit/openstack/python-keystoneclient
+.. _`openstackclient`: https://git.openstack.org/cgit/openstack/python-openstackclient
 
 If the above commands result in a ``KeyError``, or they fail on a
 ``.pyc`` file with the message, ``You can only have one Python script per
@@ -91,9 +92,13 @@ following from the Keystone root project directory:
 Database Schema Migrations
 --------------------------
 
-Keystone uses SQLAlchemy-migrate_ to migrate
-the SQL database between revisions. For core components, the migrations are
-kept in a central repository under ``keystone/common/sql/migrate_repo``.
+Keystone uses SQLAlchemy-migrate_ to migrate the SQL database between
+revisions. For core components, the migrations are kept in a central
+repository under ``keystone/common/sql/migrate_repo/versions``. Each
+SQL migration has a version which can be identified by the name of
+the script, the version is the number before the underline.
+For example, if the script is named ``001_add_X_table.py`` then the
+version of the SQL migration is ``1``.
 
 .. _SQLAlchemy-migrate: http://code.google.com/p/sqlalchemy-migrate/
 
@@ -103,11 +108,13 @@ but should instead have its own repository. This repository must be in the
 extension's directory in ``keystone/contrib/<extension>/migrate_repo``. In
 addition, it needs a subdirectory named ``versions``. For example, if the
 extension name is ``my_extension`` then the directory structure would be
-``keystone/contrib/my_extension/migrate_repo/versions/``. For the migration to
-work, both the ``migrate_repo`` and ``versions`` subdirectories must have
-``__init__.py`` files. SQLAlchemy-migrate will look for a configuration file in
-the ``migrate_repo`` named ``migrate.cfg``. This conforms to a key/value `ini`
-file format. A sample configuration file with the minimal set of values is::
+``keystone/contrib/my_extension/migrate_repo/versions/``.
+
+For the migration to work, both the ``migrate_repo`` and ``versions``
+subdirectories must have ``__init__.py`` files. SQLAlchemy-migrate will look
+for a configuration file in the ``migrate_repo`` named ``migrate.cfg``. This
+conforms to a key/value `ini` file format. A sample configuration file with
+the minimal set of values is::
 
     [db_settings]
     repository_id=my_extension
@@ -117,13 +124,33 @@ file format. A sample configuration file with the minimal set of values is::
 The directory ``keystone/contrib/example`` contains a sample extension
 migration.
 
-Migrations must be explicitly run for each extension individually. To run a
-migration for a specific extension, simply run:
+For core components, to run a migration for upgrade, simply run:
+
+.. code-block:: bash
+
+    $ keystone-manage db_sync <version>
+
+.. NOTE::
+
+   If no version is specified, then the most recent migration will be used.
+
+For extensions, migrations must be explicitly run for each extension individually.
+To run a migration for a specific extension, simply run:
 
 .. code-block:: bash
 
     $ keystone-manage db_sync --extension <name>
 
+.. NOTE::
+
+   The meaning of "extension" here has been changed since all of the
+   "extension" are loaded and the migrations are run by default, but
+   the source is maintained in a separate directory.
+
+.. NOTE::
+
+   Schema downgrades are not supported for both core components and extensions.
+
 Initial Sample Data
 -------------------
 
@@ -132,18 +159,24 @@ data for use with keystone:
 
 .. code-block:: bash
 
-    $ OS_SERVICE_TOKEN=ADMIN tools/with_venv.sh tools/sample_data.sh
+    $ OS_TOKEN=ADMIN tools/with_venv.sh tools/sample_data.sh
 
 Notice it requires a service token read from an environment variable for
 authentication.  The default value "ADMIN" is from the ``admin_token``
 option in the ``[DEFAULT]`` section in ``etc/keystone.conf``.
 
 Once run, you can see the sample data that has been created by using the
-`python-keystoneclient`_ command-line interface:
+`openstackclient`_ command-line interface:
+
+.. code-block:: bash
+
+    $ tools/with_venv.sh openstack --os-token ADMIN --os-url http://127.0.0.1:35357/v2.0/ user list
+
+The `openstackclient`_ can be installed using the following:
 
 .. code-block:: bash
 
-    $ tools/with_venv.sh keystone --os-token ADMIN --os-endpoint http://127.0.0.1:35357/v2.0/ user-list
+    $ tools/with_venv.sh pip install python-openstackclient
 
 Filtering responsibilities between controllers and drivers
 ----------------------------------------------------------
@@ -264,7 +297,7 @@ you'll normally only want to run the test that hits your breakpoint:
 
 .. code-block:: bash
 
-    $ tox -e debug keystone.tests.test_auth.AuthWithToken.test_belongs_to
+    $ tox -e debug keystone.tests.unit.test_auth.AuthWithToken.test_belongs_to
 
 For reference, the ``debug`` tox environment implements the instructions
 here: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests
@@ -291,31 +324,29 @@ For example, to discard logging data during a test run:
 Test Structure
 ==============
 
-Not all of the tests in the tests directory are strictly unit tests. Keystone
-intentionally includes tests that run the service locally and drives the entire
-configuration to achieve basic functional testing.
+Not all of the tests in the keystone/tests/unit directory are strictly unit
+tests. Keystone intentionally includes tests that run the service locally and
+drives the entire configuration to achieve basic functional testing.
 
-For the functional tests, an in-memory key-value store is used to keep the
-tests fast.
+For the functional tests, an in-memory key-value store or in-memory sqlite
+database is used to keep the tests fast.
 
-Within the tests directory, the general structure of the tests is a basic
-set of tests represented under a test class, and then subclasses of those
+Within the tests directory, the general structure of the backend tests is a
+basic set of tests represented under a test class, and then subclasses of those
 tests under other classes with different configurations to drive different
 backends through the APIs.
 
 For example, ``test_backend.py`` has a sequence of tests under the class
-``IdentityTests`` that will work with the default drivers as configured in
-this projects etc/ directory. ``test_backend_sql.py`` subclasses those tests,
-changing the configuration by overriding with configuration files stored in
-the tests directory aimed at enabling the SQL backend for the Identity module.
-
-Likewise, ``test_v2_keystoneclient.py`` takes advantage of the tests written
-against ``KeystoneClientTests`` to verify the same tests function through
-different drivers and releases of the Keystone client.
+:class:`~keystone.tests.unit.test_backend.IdentityTests` that will work with
+the default drivers as configured in this project's etc/ directory.
+``test_backend_sql.py`` subclasses those tests, changing the configuration by
+overriding with configuration files stored in the ``tests/unit/config_files``
+directory aimed at enabling the SQL backend for the Identity module.
 
-The class ``CompatTestCase`` does the work of checking out a specific version
-of python-keystoneclient, and then verifying it against a temporarily running
-local instance to explicitly verify basic functional testing across the API.
+:class:`keystone.tests.unit.test_v2_keystoneclient.ClientDrivenTestCase`
+uses the installed python-keystoneclient, verifying it against a temporarily
+running local keystone instance to explicitly verify basic functional testing
+across the API.
 
 Testing Schema Migrations
 =========================
@@ -325,7 +356,8 @@ built-in test runner, one migration at a time.
 
 .. WARNING::
 
-    This may leave your database in an inconsistent state; attempt this in non-production environments only!
+    This may leave your database in an inconsistent state; attempt this in
+    non-production environments only!
 
 This is useful for testing the *next* migration in sequence (both forward &
 backward) in a database under version control:
@@ -344,9 +376,17 @@ of your data during migration.
 Writing Tests
 =============
 
-To add tests covering all drivers, update the relevant base test class
-(``test_backend.py``, ``test_legacy_compat.py``, and
-``test_keystoneclient.py``).
+To add tests covering all drivers, update the base test class in
+``test_backend.py``.
+
+.. NOTE::
+
+    The structure of backend testing is in transition, migrating from having
+    all classes in a single file (test_backend.py) to one where there is a
+    directory structure to reduce the size of the test files. See:
+
+        - :mod:`keystone.tests.unit.backend.role`
+        - :mod:`keystone.tests.unit.backend.domain_config`
 
 To add new drivers, subclass the ``test_backend.py`` (look towards
 ``test_backend_sql.py`` or ``test_backend_kvs.py`` for examples) and update the
@@ -363,9 +403,9 @@ You may also be interested in either the
 `OpenStack Continuous Integration Infrastructure`_ or the
 `OpenStack Integration Testing Project`_.
 
-.. _devstack: http://devstack.org/
-.. _OpenStack Continuous Integration Infrastructure: http://ci.openstack.org
-.. _OpenStack Integration Testing Project: https://github.com/openstack/tempest
+.. _devstack: http://docs.openstack.org/developer/devstack/
+.. _OpenStack Continuous Integration Infrastructure: http://docs.openstack.org/infra/system-config
+.. _OpenStack Integration Testing Project: https://git.openstack.org/cgit/openstack/tempest
 
 
 LDAP Tests
@@ -379,15 +419,16 @@ and set environment variables ``KEYSTONE_IDENTITY_BACKEND=ldap`` and
 ``KEYSTONE_CLEAR_LDAP=yes`` in your ``localrc`` file.
 
 The unit tests can be run against a live server with
-``keystone/tests/test_ldap_livetest.py`` and
-``keystone/tests/test_ldap_pool_livetest.py``. The default password is ``test``
-but if you have installed devstack with a different LDAP password, modify the
-file ``keystone/tests/config_files/backend_liveldap.conf`` and
-``keystone/tests/config_files/backend_pool_liveldap.conf`` to reflect your password.
+``keystone/tests/unit/test_ldap_livetest.py`` and
+``keystone/tests/unit/test_ldap_pool_livetest.py``. The default password is
+``test`` but if you have installed devstack with a different LDAP password,
+modify the file ``keystone/tests/unit/config_files/backend_liveldap.conf`` and
+``keystone/tests/unit/config_files/backend_pool_liveldap.conf`` to reflect your
+password.
 
 .. NOTE::
-    To run the live tests you need to set the environment variable ``ENABLE_LDAP_LIVE_TEST``
-    to a non-negative value.
+    To run the live tests you need to set the environment variable 
+    ``ENABLE_LDAP_LIVE_TEST`` to a non-negative value.
 
 
 "Work in progress" Tests
@@ -405,21 +446,22 @@ including:
   used to catch bug regressions and commit it before any code is
   written.
 
-The ``keystone.tests.util.wip`` decorator can be used to mark a test as
-WIP. A WIP test will always be run. If the test fails then a TestSkipped
+The :func:`keystone.tests.unit.utils.wip` decorator can be used to mark a test
+as WIP. A WIP test will always be run. If the test fails then a TestSkipped
 exception is raised because we expect the test to fail. We do not pass
 the test in this case so that it doesn't count toward the number of
 successfully run tests. If the test passes an AssertionError exception is
 raised so that the developer knows they made the test pass. This is a
 reminder to remove the decorator.
 
-The ``wip`` decorator requires that the author provides a message. This
-message is important because it will tell other developers why this test
-is marked as a work in progress. Reviewers will require that these
-messages are descriptive and accurate.
+The :func:`~keystone.tests.unit.utils.wip` decorator requires that the author
+provides a message. This message is important because it will tell other
+developers why this test is marked as a work in progress. Reviewers will
+require that these messages are descriptive and accurate.
 
 .. NOTE::
-    The ``wip`` decorator is not a replacement for skipping tests.
+    The :func:`~keystone.tests.unit.utils.wip` decorator is not a replacement for
+    skipping tests.
 
 .. code-block:: python
 
@@ -427,6 +469,10 @@ messages are descriptive and accurate.
     def test():
         pass
 
+.. NOTE::
+   Another strategy is to not use the wip decorator and instead show how the
+   code currently incorrectly works. Which strategy is chosen is up to the
+   developer.
 
 Generating Updated Sample Config File
 -------------------------------------
@@ -435,19 +481,23 @@ Keystone's sample configuration file ``etc/keystone.conf.sample`` is automatical
 generated based upon all of the options available within Keystone. These options
 are sourced from the many files around Keystone as well as some external libraries.
 
-If new options are added, primarily located in ``keystone.common.config``, a new
-sample configuration file needs to be generated. Generating a new sample configuration
-to be included in a commit run:
+The sample configuration file is now kept up to date by an infra job that
+generates the config file and if there are any changes will propose a review
+as the OpenStack Proposal Bot. Developers should *NOT* generate the config file
+and propose it as part of their patches since the proposal bot will do this for
+you.
+
+To generate a new sample configuration to see what it looks like, run:
 
 .. code-block:: bash
 
-    $ tox -esample_config -r
+    $ tox -egenconfig -r
 
 The tox command will place an updated sample config in ``etc/keystone.conf.sample``.
 
 If there is a new external library (e.g. ``oslo.messaging``) that utilizes the
 ``oslo.config`` package for configuration, it can be added to the list of libraries
-found in ``tools/config/oslo.config.generator.rc``.
+found in ``config-generator/keystone.conf``.
 
 
 Translated responses
@@ -768,4 +818,4 @@ The documentation is generated with Sphinx using the tox command.  To create HTM
 
     $ tox -e docs
 
-The results are in the docs/build/html and docs/build/man directories respectively.
+The results are in the doc/build/html and doc/build/man directories respectively.
diff --git a/keystone-moon/doc/source/extension_development.rst b/keystone-moon/doc/source/extension_development.rst
index a0248495..0805af40 100644
--- a/keystone-moon/doc/source/extension_development.rst
+++ b/keystone-moon/doc/source/extension_development.rst
@@ -70,7 +70,7 @@ must follow the config file conventions and introduce a dedicated section.
 Example::
 
     [example]
-    driver = keystone.contrib.example.backends.sql.mySQLClass
+    driver = sql
 
     [my_other_extension]
     extension_flag = False
@@ -81,7 +81,7 @@ extensions are disabled.
 Example::
 
     [example]
-    #driver = keystone.contrib.example.backends.sql.mySQLClass
+    #driver = sql
 
     [my_other_extension]
     #extension_flag = False
diff --git a/keystone-moon/doc/source/extensions.rst b/keystone-moon/doc/source/extensions.rst
index f3bade9b..0a6b34a2 100644
--- a/keystone-moon/doc/source/extensions.rst
+++ b/keystone-moon/doc/source/extensions.rst
@@ -86,26 +86,6 @@ a policy ID.
 
 * `API Specification for Endpoint Policy <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`__
 
-----------
-Federation
-----------
-
-The Federation extension provides the ability for users to manage Identity
-Providers (IdPs) and establish a set of rules to map federation protocol
-attributes to Identity API attributes.
-
-.. NOTE:: Support status for Federation
-
-   *Experimental* (Icehouse, Juno)
-   *Stable* (Kilo)
-
-.. toctree::
-   :maxdepth: 1
-
-   extensions/federation.rst
-
-* `API Specification for Federation <http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html>`__
-
 -------
 Inherit
 -------
diff --git a/keystone-moon/doc/source/extensions/endpoint_filter.rst b/keystone-moon/doc/source/extensions/endpoint_filter.rst
index 66198503..4ab194b8 100644
--- a/keystone-moon/doc/source/extensions/endpoint_filter.rst
+++ b/keystone-moon/doc/source/extensions/endpoint_filter.rst
@@ -24,7 +24,7 @@ To enable the endpoint filter extension:
    in ``keystone.conf``. For example::
 
     [catalog]
-    driver = keystone.contrib.endpoint_filter.backends.catalog_sql.EndpointFilterCatalog
+    driver = catalog_sql
 
 2. Add the ``endpoint_filter_extension`` filter to the ``api_v3`` pipeline in
    ``keystone-paste.ini``. This must be added after ``json_body`` and before
diff --git a/keystone-moon/doc/source/extensions/endpoint_policy.rst b/keystone-moon/doc/source/extensions/endpoint_policy.rst
index 86ff2264..ad403d50 100644
--- a/keystone-moon/doc/source/extensions/endpoint_policy.rst
+++ b/keystone-moon/doc/source/extensions/endpoint_policy.rst
@@ -21,7 +21,7 @@ To enable the endpoint policy extension:
    ``[endpoint_policy]`` section in ``keystone.conf``. For example::
 
     [endpoint_policy]
-    driver = keystone.contrib.endpoint_policy.backends.sql.EndpointPolicy
+    driver = sql
 
 2. Add the ``endpoint_policy_extension`` policy to the ``api_v3`` pipeline in
    ``keystone-paste.ini``. This must be added after ``json_body`` and before
diff --git a/keystone-moon/doc/source/extensions/oauth1.rst b/keystone-moon/doc/source/extensions/oauth1.rst
index c89ee126..29955d74 100644
--- a/keystone-moon/doc/source/extensions/oauth1.rst
+++ b/keystone-moon/doc/source/extensions/oauth1.rst
@@ -23,13 +23,12 @@ To enable the OAuth1 extension:
 1. Optionally, add the oauth1 extension driver to the ``[oauth1]`` section in ``keystone.conf``. For example::
 
     [oauth1]
-    driver = keystone.contrib.oauth1.backends.sql.OAuth1
+    driver = sql
 
 2. Add the ``oauth1`` authentication method to the ``[auth]`` section in ``keystone.conf``::
 
     [auth]
     methods = external,password,token,oauth1
-    oauth1 = keystone.auth.plugins.oauth1.OAuth
 
 3. Add the ``oauth1_extension`` filter to the ``api_v3`` pipeline in
    ``keystone-paste.ini``. This must be added after ``json_body`` and before
diff --git a/keystone-moon/doc/source/extensions/revoke.rst b/keystone-moon/doc/source/extensions/revoke.rst
index e8a25ce9..a89e359d 100644
--- a/keystone-moon/doc/source/extensions/revoke.rst
+++ b/keystone-moon/doc/source/extensions/revoke.rst
@@ -27,7 +27,7 @@ Enabling the Revocation Extension
    in ``keystone.conf``. For example::
 
     [revoke]
-    driver = keystone.contrib.revoke.backends.sql.Revoke
+    driver = sql
 
 2. Add the required ``filter`` to the ``pipeline`` in ``keystone-paste.ini``.
    This must be added after ``json_body`` and before the last entry in the
diff --git a/keystone-moon/doc/source/external-auth.rst b/keystone-moon/doc/source/external-auth.rst
index 5f3c9af8..4b545e4f 100644
--- a/keystone-moon/doc/source/external-auth.rst
+++ b/keystone-moon/doc/source/external-auth.rst
@@ -28,15 +28,14 @@ To configure the plugin that should be used set the ``external`` option again
 in the ``auth`` section. There are two external authentication method plugins
 provided by Keystone:
 
-* ``keystone.auth.plugins.external.Default``: This plugin won't take into
-  account the domain information that the external authentication method may
-  pass down to Keystone and will always use the configured default domain. The
-  ``REMOTE_USER`` variable is the username.
-
-* ``keystone.auth.plugins.external.Domain``: This plugin expects that the
-  ``REMOTE_DOMAIN`` variable contains the domain for the user. If this variable
-  is not present, the configured default domain will be used. The
-  ``REMOTE_USER`` variable is the username.
+* ``DefaultDomain``: This plugin won't take into account the domain information
+  that the external authentication method may pass down to Keystone and will
+  always use the configured default domain. The ``REMOTE_USER`` variable is the
+  username. This is the default if no plugin is given.
+
+* ``Domain``: This plugin expects that the ``REMOTE_DOMAIN`` variable contains
+  the domain for the user. If this variable is not present, the configured
+  default domain will be used. The ``REMOTE_USER`` variable is the username.
 
 Using HTTPD authentication
 ==========================
diff --git a/keystone-moon/doc/source/federation/mellon.rst b/keystone-moon/doc/source/federation/mellon.rst
new file mode 100644
index 00000000..9c4675b7
--- /dev/null
+++ b/keystone-moon/doc/source/federation/mellon.rst
@@ -0,0 +1,122 @@
+:orphan:
+
+..
+      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.
+
+==============================
+Setup Mellon (mod_auth_mellon)
+==============================
+
+Configure Apache HTTPD for mod_auth_mellon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow the steps outlined at: `Running Keystone in HTTPD`_.
+
+.. _`Running Keystone in HTTPD`: ../apache-httpd.html
+
+You'll also need to install the Apache module `mod_auth_mellon
+<https://github.com/UNINETT/mod_auth_mellon>`_.  For example:
+
+.. code-block:: bash
+
+    $ apt-get install libapache2-mod-auth-mellon
+
+Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:
+
+Add *WSGIScriptAlias* directive to your vhost configuration::
+
+    WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1
+
+Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Mellon module and
+a *<Location>* directive for each identity provider::
+
+    <Location /v3>
+        MellonEnable "info"
+        MellonSPPrivateKeyFile /etc/httpd/mellon/http_keystone.fqdn.key
+        MellonSPCertFile /etc/httpd/mellon/http_keystone.fqdn.cert
+        MellonSPMetadataFile /etc/httpd/mellon/http_keystone.fqdn.xml
+        MellonIdPMetadataFile /etc/httpd/mellon/idp-metadata.xml
+        MellonEndpointPath /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon
+        MellonIdP "IDP"
+    </Location>
+
+    <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth>
+        AuthType "Mellon"
+        MellonEnable "auth"
+    </Location>
+
+.. NOTE::
+    * See below for information about how to generate the values for the
+      `MellonSPMetadataFile`, etc. directives.
+    * ``saml2`` may be different in your deployment, but do not use a wildcard value.
+      Otherwise *every* federated protocol will be handled by Mellon.
+    * ``idp_1`` has to be replaced with the name associated with the IdP in Keystone.
+    * You are advised to carefully examine `mod_auth_mellon Apache
+      configuration documentation
+      <https://github.com/UNINETT/mod_auth_mellon>`_
+
+Enable the Keystone virtual host, for example:
+
+.. code-block:: bash
+
+    $ a2ensite wsgi-keystone.conf
+
+Enable the ``ssl`` and ``auth_mellon`` modules, for example:
+
+.. code-block:: bash
+
+    $ a2enmod ssl
+    $ a2enmod auth_mellon
+
+Restart the Apache instance that is serving Keystone, for example:
+
+.. code-block:: bash
+
+    $ service apache2 restart
+
+Configuring the Mellon SP Metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mellon provides a script called ``mellon_create_metadata.sh`` which generates the
+values for the config directives `MellonSPPrivateKeyFile`, `MellonSPCertFile`,
+and `MellonSPMetadataFile`.  It is run like this:
+
+.. code-block:: bash
+
+    $ mellon_create_metadata.sh http://keystone.fqdn:5000 \
+      http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon
+
+The first parameter is used as the entity ID, a unique identifier for this
+Keystone SP.  You do not have to use the URL, but it is an easy way to uniquely
+identify each Keystone SP.  The second parameter is the full URL for the
+endpoint path corresponding to the parameter `MellonEndpointPath`.
+
+Fetch your Service Provider's Metadata file.  This corresponds to the value of
+the `MellonIdPMetadataFile` directive above. For example:
+
+.. code-block:: bash
+
+    $ wget --cacert /path/to/ca.crt -O /etc/httpd/mellon/idp-metadata.xml \
+      https://idp.fqdn/idp/saml2/metadata
+
+Upload your Service Provider's Metadata file to your Identity Provider.  This
+is the file used as the value of the `MellonSPMetadataFile` in the config,
+generated by the `mellon_create_metadata.sh` script.  The IdP may provide a
+webpage where you can upload the file, or you may be required to submit the
+file using `wget` or `curl`.  Please check your IdP documentation for details.
+
+Once you are done, restart the Apache instance that is serving Keystone, for example:
+
+.. code-block:: bash
+
+    $ service apache2 restart
diff --git a/keystone-moon/doc/source/federation/openidc.rst b/keystone-moon/doc/source/federation/openidc.rst
new file mode 100644
index 00000000..ece82d3a
--- /dev/null
+++ b/keystone-moon/doc/source/federation/openidc.rst
@@ -0,0 +1,94 @@
+:orphan:
+
+..
+      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.
+
+====================
+Setup OpenID Connect
+====================
+
+Configuring mod_auth_openidc
+============================
+
+Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_)
+
+.. _`mod_auth_openidc`: https://github.com/pingidentity/mod_auth_openidc
+
+To install `mod_auth_openidc` on Ubuntu, perform the following:
+
+.. code-block:: bash
+
+  sudo apt-get install libapache2-mod-auth-openidc
+
+This module is available for other distributions (Fedora/CentOS/Red Hat) from:
+https://github.com/pingidentity/mod_auth_openidc/releases
+
+In the keystone Apache site file, add the following as a top level option, to
+load the `mod_auth_openidc` module:
+
+.. code-block:: xml
+
+  LoadModule auth_openidc_module /usr/lib/apache2/modules/mod_auth_openidc.so
+
+Also within the same file, locate the virtual host entry and add the following
+entries for OpenID Connect:
+
+.. code-block:: xml
+
+  <VirtualHost *:5000>
+
+      ...
+
+      OIDCClaimPrefix "OIDC-"
+      OIDCResponseType "id_token"
+      OIDCScope "openid email profile"
+      OIDCProviderMetadataURL <url_of_provider_metadata>
+      OIDCClientID <openid_client_id>
+      OIDCClientSecret <openid_client_secret>
+      OIDCCryptoPassphrase openstack
+      OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/oidc/auth/redirect
+
+      <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/oidc/auth>
+        AuthType openid-connect
+        Require valid-user
+        LogLevel debug
+      </LocationMatch>
+  </VirtualHost>
+
+Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration
+If not using `OIDCProviderMetadataURL`, then the following attributes
+must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`,
+`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`,
+`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri`
+
+Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix`
+must be specified to have only alphanumerics or a dash ("-"). This is because
+mod_wsgi blocks headers that do not fit this criteria. See http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed
+for more details
+
+Once you are done, restart your Apache daemon:
+
+.. code-block:: bash
+
+    $ service apache2 restart
+
+Tips
+====
+
+1. When creating a mapping, note that the 'remote' attributes will be prefixed,
+   with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a
+   typical remote value to check for is: `HTTP_OIDC_ISS`.
+
+2. Don't forget to add oidc as an [auth] plugin in keystone.conf, see `Step 2`_
+
+.. _`Step 2`: federation/federation.html
diff --git a/keystone-moon/doc/source/federation/shibboleth.rst b/keystone-moon/doc/source/federation/shibboleth.rst
new file mode 100644
index 00000000..d67cfa1a
--- /dev/null
+++ b/keystone-moon/doc/source/federation/shibboleth.rst
@@ -0,0 +1,279 @@
+:orphan:
+
+..
+      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.
+
+================
+Setup Shibboleth
+================
+
+Configure Apache HTTPD for mod_shibboleth
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow the steps outlined at: `Running Keystone in HTTPD`_.
+
+.. _`Running Keystone in HTTPD`: ../apache-httpd.html
+
+You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for
+example:
+
+.. code-block:: bash
+
+    $ apt-get install libapache2-mod-shib2
+
+Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:
+
+Add *WSGIScriptAlias* directive to your vhost configuration::
+
+    WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1
+
+Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Shibboleth module and
+a *<Location>* directive for each identity provider::
+
+    <Location /Shibboleth.sso>
+        SetHandler shib
+    </Location>
+
+    <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth>
+        ShibRequestSetting requireSession 1
+        ShibRequestSetting applicationId idp_1
+        AuthType shibboleth
+        ShibRequireAll On
+        ShibRequireSession On
+        ShibExportAssertion Off
+        Require valid-user
+    </Location>
+
+.. NOTE::
+    * ``saml2`` may be different in your deployment, but do not use a wildcard value.
+      Otherwise *every* federated protocol will be handled by Shibboleth.
+    * ``idp_1`` has to be replaced with the name associated with the idp in Keystone.
+      The same name is used inside the shibboleth2.xml configuration file but they could
+      be different.
+    * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in
+      Apache 2.4+ and should be dropped in that specific setup.
+    * You are advised to carefully examine `Shibboleth Apache configuration
+      documentation
+      <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_
+
+Enable the Keystone virtual host, for example:
+
+.. code-block:: bash
+
+    $ a2ensite wsgi-keystone.conf
+
+Enable the ``ssl`` and ``shib2`` modules, for example:
+
+.. code-block:: bash
+
+    $ a2enmod ssl
+    $ a2enmod shib2
+
+Restart Apache, for example:
+
+.. code-block:: bash
+
+    $ service apache2 restart
+
+Configuring shibboleth2.xml
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have your Keystone vhost (virtual host) ready, it's then time to
+configure Shibboleth and upload your Metadata to the Identity Provider.
+
+If new certificates are required, they can be easily created by executing:
+
+.. code-block:: bash
+
+    $ shib-keygen -y <number of years>
+
+The newly created file will be stored under ``/etc/shibboleth/sp-key.pem``
+
+You should fetch your Service Provider's Metadata file. Typically this can be
+achieved by simply fetching a Metadata file, for example:
+
+.. code-block:: bash
+
+    $ wget --no-check-certificate -O <name of the file> https://service.example.org/Shibboleth.sso/Metadata
+
+Upload your Service Provider's Metadata file to your Identity Provider.
+This step depends on your Identity Provider choice and is not covered here.
+
+Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml``
+file. You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
+
+An example of your ``/etc/shibboleth/shibboleth2.xml`` may look like
+(The example shown below is for reference only, not to be used in a production
+environment):
+
+.. code-block:: xml
+
+    <!--
+    File configuration courtesy of http://testshib.org
+
+    More  information:
+    https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration
+    -->
+
+    <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
+    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="1800 ">
+
+        <!-- The entityID is the name TestShib made for your SP. -->
+        <ApplicationDefaults entityID="https://<yourhosthere>/shibboleth">
+
+            <!--
+            You should use secure cookies if at all possible.
+            See cookieProps in this Wiki article.
+            -->
+            <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions  -->
+            <Sessions lifetime="28800" timeout="3600" checkAddress="false"
+            relayState="ss:mem" handlerSSL="false">
+
+                <!-- Triggers a login request directly to the TestShib IdP. -->
+                <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO -->
+                <SSO entityID="https://<idp-url>/idp/shibboleth" ECP="true">
+                    SAML2 SAML1
+                </SSO>
+
+                <!-- SAML and local-only logout. -->
+                <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceLogout -->
+                <Logout>SAML2 Local</Logout>
+
+                <!--
+                Handlers allow you to interact with the SP and gather
+                more information. Try them out!
+                Attribute value s received by the SP through SAML
+                will be visible at:
+                http://<yourhosthere>/Shibboleth.sso/Session
+                -->
+
+                <!--
+                Extension service that generates "approximate" metadata
+                based on SP configuration.
+                -->
+                <Handler type="MetadataGenerator" Location="/Metadata"
+                signing="false"/>
+
+                <!-- Status reporting service. -->
+                <Handler type="Status" Location="/Status"
+                acl="127.0.0.1"/>
+
+                <!-- Session diagnostic service. -->
+                <Handler type="Session" Location="/Session"
+                showAttributeValues="true"/>
+                <!-- JSON feed of discovery information. -->
+                <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
+            </Sessions>
+
+            <!--
+            Error pages to display to yourself if
+            something goes horribly wrong.
+            -->
+            <Errors supportContact  ="<admin_email_address>"
+                logoLocation="/shibboleth-sp/logo.jpg"
+                styleSheet="/shibboleth-sp/main.css"/>
+
+            <!--
+            Loads and trusts a metadata file that describes only one IdP
+            and  how to communicate with it.
+            -->
+            <MetadataProvider type="XML" uri="<idp-metadata-file>"
+                 backingFilePath="<local idp metadata>"
+                 reloadInterval="180000" />
+
+            <!-- Attribute and trust options you shouldn't need to change. -->
+            <AttributeExtractor type="XML" validate="true"
+            path="attribute-map.xml"/>
+            <AttributeResolver type="Query" subjectMatch="true"/>
+            <AttributeFilter type="XML" validate="true"
+            path="attribute-policy.xml"/>
+
+            <!--
+            Your SP generated these credentials.
+            They're used to talk to IdP's.
+            -->
+            <CredentialResolver type="File" key="sp-key.pem"
+            certificate="sp-cert.pem"/>
+
+            <ApplicationOverride id="idp_1" entityID="https://<yourhosthere>/shibboleth">
+               <Sessions lifetime="28800" timeout="3600" checkAddress="false"
+               relayState="ss:mem" handlerSSL="false">
+
+                <!-- Triggers a login request directly to the TestShib IdP. -->
+                <SSO entityID="https://<idp_1-url>/idp/shibboleth" ECP="true">
+                    SAML2 SAML1
+                </SSO>
+
+                <Logout>SAML2 Local</Logout>
+               </Sessions>
+
+               <MetadataProvider type="XML" uri="<idp_1-metadata-file>"
+                 backingFilePath="<local idp_1 metadata>"
+                 reloadInterval="180000" />
+
+            </ApplicationOverride>
+
+            <ApplicationOverride id="idp_2" entityID="https://<yourhosthere>/shibboleth">
+               <Sessions lifetime="28800" timeout="3600" checkAddress="false"
+               relayState="ss:mem" handlerSSL="false">
+
+                <!-- Triggers a login request directly to the TestShib IdP. -->
+                <SSO entityID="https://<idp_2-url>/idp/shibboleth" ECP="true">
+                    SAML2 SAML1
+                </SSO>
+
+                <Logout>SAML2 Local</Logout>
+               </Sessions>
+
+               <MetadataProvider type="XML" uri="<idp_2-metadata-file>"
+                 backingFilePath="<local idp_2 metadata>"
+                 reloadInterval="180000" />
+
+            </ApplicationOverride>
+
+        </ApplicationDefaults>
+
+        <!--
+        Security policies you shouldn't change unless you
+        know what you're doing.
+        -->
+        <SecurityPolicyProvider type="XML" validate="true"
+        path="security-policy.xml"/>
+
+        <!--
+        Low-level configuration about protocols and bindings
+        available for use.
+        -->
+        <ProtocolProvider type="XML" validate="true" reloadChanges="false"
+        path="protocols.xml"/>
+
+    </SPConfig>
+
+Keystone enforces `external authentication`_ when the ``REMOTE_USER``
+environment variable is present so make sure Shibboleth doesn't set the
+``REMOTE_USER`` environment variable.  To do so, scan through the
+``/etc/shibboleth/shibboleth2.xml`` configuration file and remove the
+``REMOTE_USER`` directives.
+
+Examine your attributes map file ``/etc/shibboleth/attributes-map.xml`` and adjust
+your requirements if needed. For more information see
+`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_
+
+Once you are done, restart your Shibboleth daemon:
+
+.. _`external authentication`: ../external-auth.html
+
+.. code-block:: bash
+
+    $ service shibd restart
+    $ service apache2 restart
diff --git a/keystone-moon/doc/source/federation/websso.rst b/keystone-moon/doc/source/federation/websso.rst
new file mode 100644
index 00000000..4ada0a4c
--- /dev/null
+++ b/keystone-moon/doc/source/federation/websso.rst
@@ -0,0 +1,239 @@
+:orphan:
+
+..
+      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 Federation and Horizon
+===============================
+
+Keystone Changes
+================
+
+1. Update `trusted_dashboard` in keystone.conf.
+
+Specify URLs of trusted horizon servers. This value may be repeated
+multiple times. This setting ensures that keystone only sends token data back
+to trusted servers. This is performed as a precaution, specifically to
+prevent man-in-the-middle (MITM) attacks.
+
+.. code-block:: ini
+
+  [federation]
+  trusted_dashboard = http://acme.horizon.com/auth/websso/
+  trusted_dashboard = http://beta.horizon.com/auth/websso/
+
+2. Update httpd vhost file with websso information.
+
+The `/v3/auth/OS-FEDERATION/websso/<protocol>` route must be protected by the
+chosen httpd module. This is performed so the request that originates from
+horizon will use the same identity provider that is configured in keystone.
+
+If `mod_shib` is used, then use the following as an example:
+
+.. code-block:: xml
+
+  <VirtualHost *:5000>
+
+      ...
+
+      <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
+        AuthType shibboleth
+        Require valid-user
+        ...
+      </Location>
+  </VirtualHost>
+
+If `mod_auth_openidc` is used, then use the following as an example:
+
+.. code-block:: xml
+
+  <VirtualHost *:5000>
+
+      OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/websso/redirect
+
+      ...
+
+      <Location ~ "/v3/auth/OS-FEDERATION/websso/oidc">
+        AuthType openid-connect
+        Require valid-user
+        ...
+      </Location>
+  </VirtualHost>
+
+If `mod_auth_kerb` is used, then use the following as an example:
+
+.. code-block:: xml
+
+  <VirtualHost *:5000>
+
+      ...
+
+      <Location ~ "/v3/auth/OS-FEDERATION/websso/kerberos">
+        AuthType Kerberos
+        AuthName "Acme Corporation"
+        KrbMethodNegotiate on
+        KrbMethodK5Passwd off
+        Krb5Keytab /etc/apache2/http.keytab
+        ...
+      </Location>
+  </VirtualHost>
+
+If `mod_auth_mellon` is used, then use the following as an example:
+
+.. code-block:: xml
+
+  <VirtualHost *:5000>
+
+      ...
+
+      <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2">
+        AuthType Mellon
+        MellonEnable auth
+        Require valid-user
+        ...
+      </Location>
+  </VirtualHost>
+
+.. NOTE::
+    If you are also using SSO via the API, don't forget to make the Location
+    settings match your configuration used for the keystone identity provider
+    location:
+    `/v3/OS-FEDERATION/identity_providers/<idp>/protocols/<protocol>/auth`
+
+3. Update `remote_id_attribute` in keystone.conf.
+
+A remote id attribute indicates the header to retrieve from the WSGI
+environment. This header contains information about the identity
+of the identity provider. For `mod_shib` this would be
+``Shib-Identity-Provider``, for `mod_auth_openidc`, this could be
+``HTTP_OIDC_ISS``.  For `mod_auth_mellon`, this could be ``MELLON_IDP``.
+
+It is recommended that this option be set on a per-protocol basis.
+
+.. code-block:: ini
+
+  [saml2]
+  remote_id_attribute = Shib-Identity-Provider
+  [oidc]
+  remote_id_attribute = HTTP_OIDC_ISS
+
+Alternatively, a generic option may be set at the `[federation]` level.
+
+.. code-block:: ini
+
+  [federation]
+  remote_id_attribute = HTTP_OIDC_ISS
+
+4. Set `remote_ids` for a keystone identity provider using the API or CLI.
+
+A keystone identity provider may have multiple `remote_ids` specified, this
+allows the same *keystone* identity provider resource to be used with multiple
+external identity providers. For example, an identity provider resource
+``university-idp``, may have the following `remote_ids`:
+``['university-x', 'university-y', 'university-z']``.
+This removes the need to configure N identity providers in keystone.
+
+This can be performed using the `OS-FEDERATION API`_:
+``PATCH /OS-FEDERATION/identity_providers/{idp_id}``
+
+Or by using the `OpenStackClient CLI`_:
+
+.. code-block:: bash
+
+    $ openstack identity provider set --remote-id <remote-id>  <idp-id>
+
+.. NOTE::
+
+    Remote IDs are globally unique. Two identity providers cannot be
+    associated with the same remote ID. Once authenticated with the external
+    identity provider, keystone will determine which identity provider
+    and mapping to use based on the protocol and the value returned from the
+    `remote_id_attribute` key.
+
+    For example, if our identity provider is ``google``, the mapping used is
+    ``google_mapping`` and the protocol is ``oidc``. The identity provider's
+    remote IDs  would be: [``accounts.google.com``].
+    The `remote_id_attribute` value may be set to ``HTTP_OIDC_ISS``, since
+    this value will always be ``accounts.google.com``.
+
+    The motivation for this approach is that there will always be some data
+    sent by the identity provider (in the assertion or claim) that uniquely
+    identifies the identity provider. This removes the requirement for horizon
+    to list all the identity providers that are trusted by keystone.
+
+.. _`OpenStackClient CLI`: http://docs.openstack.org/developer/python-openstackclient/command-objects/identity-provider.html#identity-provider-set
+.. _`OS-FEDERATION API`: http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#update-identity-provider
+
+Horizon Changes
+===============
+
+.. NOTE::
+
+    Django OpenStack Auth version 1.2.0 or higher is required for these steps.
+
+1. Set the Identity Service version to 3
+
+Ensure the `OPENSTACK_API_VERSIONS` option in horizon's local_settings.py has
+been updated to indicate that the `identity` version to use is `3`.
+
+.. code-block:: python
+
+  OPENSTACK_API_VERSIONS = {
+    "identity": 3,
+  }
+
+2. Authenticate against Identity Server v3.
+
+Ensure the `OPENSTACK_KEYSTONE_URL` option in horizon's local_settings.py has
+been updated to point to a v3 URL.
+
+.. code-block:: python
+
+  OPENSTACK_KEYSTONE_URL = "http://localhost:5000/v3"
+
+3. Set the `WEBSSO_ENABLED` option.
+
+Ensure the `WEBSSO_ENABLED` option is set to True in horizon's local_settings.py file,
+this will provide users with an updated login screen for horizon.
+
+.. code-block:: python
+
+  WEBSSO_ENABLED = True
+
+4. (Optional) Create a list of authentication methods with the
+   `WEBSSO_CHOICES` option.
+
+Within horizon's settings.py file, a list of supported authentication methods
+can be specified. The entries in the list map to keystone federation protocols,
+with the exception of ``credentials`` which is reserved by horizon, and maps to
+the user name and password used by keystone's identity backend.
+
+.. code-block:: python
+
+  WEBSSO_CHOICES = (
+        ("credentials", _("Keystone Credentials")),
+        ("oidc", _("OpenID Connect")),
+        ("saml2", _("Security Assertion Markup Language"))
+      )
+
+5. (Optional) Specify an initial choice with the `WEBSSO_INITIAL_CHOICE`
+   option.
+
+The list set by the `WEBSSO_CHOICES` option will be generated in a drop-down
+menu in the login screen. The setting `WEBSSO_INITIAL_CHOICE` will
+automatically set that choice to be highlighted by default.
+
+.. code-block:: python
+
+  WEBSSO_INITIAL_CHOICE = "credentials"
diff --git a/keystone-moon/doc/source/http-api.rst b/keystone-moon/doc/source/http-api.rst
index a104ce3f..a31b5e69 100644
--- a/keystone-moon/doc/source/http-api.rst
+++ b/keystone-moon/doc/source/http-api.rst
@@ -26,8 +26,8 @@ The original source of truth for the v2.0 API is defined by a set of WADL and
 XSD files. The original source of truth for the v3 API is defined by
 documentation.
 
-.. _`Identity API v2.0`: https://github.com/openstack/identity-api/tree/master/v2.0/src
-.. _`Identity API v3`: https://github.com/openstack/identity-api/tree/master/v3/src/markdown
+.. _`Identity API v2.0`: http://specs.openstack.org/openstack/keystone-specs/#v2-0-api
+.. _`Identity API v3`: http://specs.openstack.org/openstack/keystone-specs/#v3-api
 
 History
 =======
@@ -125,7 +125,7 @@ Keystone clients can use to automatically detect available API versions.
 With unversioned ``identity`` endpoints in the service catalog, you should be
 able to `authenticate with keystoneclient`_ successfully.
 
-.. _`latest sample configuration`: https://github.com/openstack/keystone/blob/master/etc/keystone-paste.ini
+.. _`latest sample configuration`: https://git.openstack.org/cgit/openstack/keystone/tree/etc/keystone-paste.ini
 .. _`authenticate with keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/using-api-v3.html#authenticating
 
 I have a Python client
@@ -148,7 +148,7 @@ I have a non-Python client
 You'll likely need to heavily reference our `API documentation`_ to port your
 application to Identity API v3.
 
-.. _`API documentation`: https://github.com/openstack/identity-api/blob/master/v3/src/markdown/identity-api-v3.md
+.. _`API documentation`: https://git.openstack.org/cgit/openstack-attic/identity-api/tree/v3/src/markdown/identity-api-v3.md
 
 The most common operation would be password-based authentication including a
 tenant name (i.e. project name) to specify an authorization scope. In Identity
diff --git a/keystone-moon/doc/source/index.rst b/keystone-moon/doc/source/index.rst
index 48129a80..c77d7738 100644
--- a/keystone-moon/doc/source/index.rst
+++ b/keystone-moon/doc/source/index.rst
@@ -50,7 +50,10 @@ Getting Started
     setup
     installing
     configuration
+    policy_mapping
     configure_federation
+    mapping_combinations
+    mapping_schema
     configuringservices
     extensions
     key_terms
diff --git a/keystone-moon/doc/source/installing.rst b/keystone-moon/doc/source/installing.rst
index 0492da7b..e38663b7 100644
--- a/keystone-moon/doc/source/installing.rst
+++ b/keystone-moon/doc/source/installing.rst
@@ -42,7 +42,7 @@ Clone the Keystone repository:
 
 .. code-block:: bash
 
-    $ git clone http://github.com/openstack/keystone.git
+    $ git clone https://git.openstack.org/openstack/keystone.git
     $ cd keystone
 
 Install the Keystone web service:
@@ -82,12 +82,12 @@ An excellent reference implementation of setting up Keystone is DEVSTACK_,
 most commonly used for development and testing setup of not only Keystone,
 but all of the core OpenStack projects.
 
-.. _DEVSTACK: http://devstack.org/
+.. _DEVSTACK: http://docs.openstack.org/developer/devstack/
 
 The script with the latest examples of initializing data in Keystone is a
-bash script called keystone_data.sh_
+bash script called `lib/keystone`_
 
-.. _keystone_data.sh: https://github.com/openstack-dev/devstack/blob/master/files/keystone_data.sh
+.. _lib/keystone: https://git.openstack.org/cgit/openstack-dev/devstack/tree/lib/keystone
 
 Installing from packages: Ubuntu
 --------------------------------
@@ -111,15 +111,16 @@ find described in :doc:`configuringservices`.
 Installing from packages: Fedora
 --------------------------------
 
-Installing Keystone with Fedora 17 is documented at
-http://fedoraproject.org/wiki/Getting_started_with_OpenStack_on_Fedora_17.
+To install Keystone on Fedora refer to the steps found in the `OpenStack
+Install Guide`_.
 
 To install the packages:
 
 .. code-block:: bash
 
-    $ sudo yum install --enablerepo=updates-testing openstack-keystone
+    $ sudo yum install openstack-keystone
 
-Once installed, you can configure Keystone based on the instructions at:
+Once installed, you still need to initialize data in Keystone, which you can
+find described in :doc:`configuringservices`.
 
-http://fedoraproject.org/wiki/Getting_started_with_OpenStack_on_Fedora_17#Configuring_Keystone_for_authentication
+.. _`OpenStack Install Guide`: http://docs.openstack.org/juno/install-guide/install/yum/content/keystone-install.html
diff --git a/keystone-moon/doc/source/man/keystone-all.rst b/keystone-moon/doc/source/man/keystone-all.rst
index 328b0c4e..ea958fe0 100644
--- a/keystone-moon/doc/source/man/keystone-all.rst
+++ b/keystone-moon/doc/source/man/keystone-all.rst
@@ -108,5 +108,5 @@ SEE ALSO
 SOURCE
 ======
 
-* Keystone source is managed in GitHub `Keystone <http://github.com/openstack/keystone>`__
+* Keystone source is managed in Gerrit git `Keystone <https://git.openstack.org/cgit/openstack/keystone>`__
 * Keystone bugs are managed at Launchpad `Keystone <https://bugs.launchpad.net/keystone>`__
diff --git a/keystone-moon/doc/source/man/keystone-manage.rst b/keystone-moon/doc/source/man/keystone-manage.rst
index b2ea3924..21a3ca4a 100644
--- a/keystone-moon/doc/source/man/keystone-manage.rst
+++ b/keystone-moon/doc/source/man/keystone-manage.rst
@@ -7,9 +7,9 @@ Keystone Management Utility
 ---------------------------
 
 :Author: openstack@lists.openstack.org
-:Date:   2014-10-16
+:Date:   2015-4-7
 :Copyright: OpenStack Foundation
-:Version: 2014.2
+:Version: 2015.1
 :Manual section: 1
 :Manual group: cloud computing
 
@@ -42,7 +42,11 @@ Available commands:
 
 * ``db_sync``: Sync the database.
 * ``db_version``: Print the current migration version of the database.
+* ``domain_config_upload``: Upload domain configuration file.
+* ``fernet_rotate``: Rotate keys in the Fernet key repository.
+* ``fernet_setup``: Setup a Fernet key repository.
 * ``mapping_purge``: Purge the identity mapping table.
+* ``mapping_engine``: Test your federation mapping rules.
 * ``pki_setup``: Initialize the certificates used to sign tokens.
 * ``saml_idp_metadata``: Generate identity provider metadata.
 * ``ssl_setup``: Generate certificates for SSL.
@@ -121,5 +125,5 @@ SEE ALSO
 SOURCE
 ======
 
-* Keystone is sourced in GitHub `Keystone <http://github.com/openstack/keystone>`__
+* Keystone is sourced in Gerrit git `Keystone <https://git.openstack.org/cgit/openstack/keystone>`__
 * Keystone bugs are managed at Launchpad `Keystone <https://bugs.launchpad.net/keystone>`__
diff --git a/keystone-moon/doc/source/mapping_combinations.rst b/keystone-moon/doc/source/mapping_combinations.rst
new file mode 100644
index 00000000..9aa411ad
--- /dev/null
+++ b/keystone-moon/doc/source/mapping_combinations.rst
@@ -0,0 +1,597 @@
+..
+    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.
+
+===================================
+Mapping Combinations for Federation
+===================================
+
+-----------
+Description
+-----------
+
+Mapping adds a set of rules to map federation attributes to Keystone users and/or
+groups. An Identity Provider has exactly one mapping specified per protocol.
+
+Mapping objects can be used multiple times by different combinations of Identity
+Provider and Protocol.
+
+-----------
+Definitions
+-----------
+
+A rule hierarchy looks as follows:
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "<user> or <group>"
+                    }
+                ],
+                "remote": [
+                    {
+                        "<condition>"
+                    }
+                ]
+            }
+        ]
+    }
+
+* `rules`: top-level list of rules.
+* `local`: a rule containing information on what local attributes will be mapped.
+* `remote`: a rule containing information on what remote attributes will be mapped.
+* `<condition>`: contains information on conditions that allow a rule, can only
+  be set in a `remote` rule.
+
+-------------
+Mapping Rules
+-------------
+
+Mapping Engine
+--------------
+
+The mapping engine can be tested before creating a federated setup. It can be
+tested with the ``keystone-manage mapping_engine`` command:
+
+.. code-block:: bash
+
+    $ keystone-manage mapping_engine --rules <file> --input <file>
+
+Mapping Conditions
+------------------
+
+Mappings support 5 different types of conditions:
+
+``empty``: The rule is matched to all claims containing the remote attribute type.
+This condition does not need to be specified.
+
+``any_one_of``: The rule is matched only if any of the specified strings appear
+in the remote attribute type. Condition result is boolean, not the argument that
+is passed as input.
+
+``not_any_of``: The rule is not matched if any of the specified strings appear
+in the remote attribute type. Condition result is boolean, not the argument that
+is passed as input.
+
+``blacklist``: The rule allows all except a specified set of groups. Condition
+result is the argument(s) passed as input minus what was matched in the
+blacklist.
+
+``whitelist``: The rules allows a specified set of groups. Condition result is
+the argument(s) passed as input and is/are also present in the whitelist.
+
+.. NOTE::
+
+    ``empty``, ``blacklist`` and ``whitelist`` are the only conditions that can
+    be used in direct mapping ({0}, {1}, etc.)
+
+You can combine multiple conditions in a single rule. The schema that needs to be
+followed for the mapping rules can be seen in the :doc:`mapping_schema` page.
+
+Mappings Examples
+-----------------
+
+The following are all examples of mapping rule types.
+
+empty condition
+~~~~~~~~~~~~~~~
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0} {1}",
+                            "email": "{2}"
+                        },
+                        "group": {
+                            "name": "{3}"
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                        "type": "FirstName"
+                    },
+                    {
+                        "type": "LastName"
+                    },
+                    {
+                        "type": "Email"
+                    },
+                    {
+                        "type": "OIDC_GROUPS"
+                    }
+                ]
+            }
+        ]
+    }
+
+.. NOTE::
+
+    The numbers in braces {} are indices, they map in order. For example::
+
+        - Mapping to user with the name matching the value in remote attribute FirstName
+        - Mapping to user with the name matching the value in remote attribute LastName
+        - Mapping to user with the email matching value in remote attribute Email
+        - Mapping to a group(s) with the name matching the value(s) in remote attribute OIDC_GROUPS
+
+
+
+Groups can have multiple values. Each value must be separated by a `;`
+Example: OIDC_GROUPS=developers;testers
+
+
+other conditions
+~~~~~~~~~~~~~~~~
+
+In ``<other_condition>`` shown below, please supply one of the following:
+``any_one_of``, or ``not_any_of``.
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        },
+                        "group": {
+                            "id": "0cd5e9"
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                    "type": "UserName"
+                    },
+                    {
+                        "type": "HTTP_OIDC_GROUPIDS",
+                        "<other_condition>": [
+                            "HTTP_OIDC_EMAIL"
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+
+In ``<other_condition>`` shown below, please supply one of the following:
+``blacklist``, or ``whitelist``.
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        },
+                        "groups": {
+                            "name": "{1}",
+                            "domain": {
+                                "id": "0cd5e9"
+                            }
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                    "type": "UserName"
+                    },
+                    {
+                        "type": "HTTP_OIDC_GROUPIDS",
+                        "<other_condition>": [
+                            "me@example.com"
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+
+.. NOTE::
+
+    If the user id and name are not specified in the mapping, the server tries to
+    directly map ``REMOTE_USER`` environment variable. If this variable is also
+    unavailable the server returns an HTTP 401 Unauthorized error.
+
+Group ids and names can be provided in the local section:
+
+.. code-block:: javascript
+
+    {
+        "local": [
+            {
+                "group": {
+                    "id":"0cd5e9"
+                }
+            }
+        ]
+    }
+
+.. code-block:: javascript
+
+    {
+        "local": [
+            {
+                "group": {
+                    "name": "developer_group",
+                    "domain": {
+                        "id": "abc1234"
+                    }
+                }
+            }
+        ]
+    }
+
+.. code-block:: javascript
+
+    {
+        "local": [
+            {
+                "group": {
+                    "name": "developer_group",
+                    "domain": {
+                        "name": "private_cloud"
+                    }
+                }
+            }
+        ]
+    }
+
+
+Output
+------
+
+If a mapping is valid you will receive the following output:
+
+.. code-block:: javascript
+
+    {
+        "group_ids": "[<group-ids>]",
+        "user":
+            {
+            "domain":
+                {
+                    "id": "Federated" or "<local-domain-id>"
+                },
+            "type": "ephemeral" or "local",
+            "name": "<local-user-name>",
+            "id": "<local-user-id>"
+            },
+        "group_names":
+            [
+                {
+                    "domain":
+                        {
+                            "name": "<domain-name>"
+                        },
+                    "name":
+                        {
+                            "name": "[<groups-names>]"
+                        }
+                }
+                {
+                    "domain":
+                        {
+                            "name": "<domain-name>"
+                        },
+                    "name":
+                        {
+                            "name": "[<groups-names>]"
+                        }
+                }
+            ]
+    }
+
+The ``type`` parameter specifies the type of user being mapped. The 2 possible
+user types are ``local`` and ``ephemeral``.``local`` is displayed if the user
+has a domain specified. The user is treated as existing in the backend, hence
+the server will fetch user details (id, name, roles, groups).``ephemeral`` is
+displayed for a user that does not exist in the backend.
+
+The ``id`` parameter in the service domain specifies the domain a user belongs
+to. ``Federated`` will be displayed if no domain is specified in the local rule.
+User is deemed ephemeral and becomes a member of service domain named ``Federated``.
+If the domain is specified the local domain's id will be displayed.
+If the mapped user is local, mapping engine will discard further group
+assigning and return set of roles configured for the user.
+
+.. NOTE::
+    Domain ``Federated`` is a service domain - it cannot be listed, displayed,
+    added or deleted.  There is no need to perform any operation on it prior to
+    federation configuration.
+
+Regular Expressions
+-------------------
+
+Regular expressions can be used in a mapping by specifying the ``regex`` key, and
+setting it to ``true``.
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        },
+                        "group": {
+                            "id": "0cd5e9"
+                        }
+                    },
+                ],
+                "remote": [
+                    {
+                    "type": "UserName"
+                    },
+                    {
+                        "type": "HTTP_OIDC_GROUPIDS",
+                        "any_one_of": [
+                            ".*@yeah.com$"
+                        ]
+                        "regex": true
+                    }
+                ]
+            }
+        ]
+    }
+
+This allows any user with a claim containing a key with any value in
+``HTTP_OIDC_GROUPIDS`` to be mapped to group with id ``0cd5e9``.
+
+Condition Combinations
+----------------------
+
+Combinations of mappings conditions can also be done.
+
+``empty``, ``any_one_of``, and ``not_any_of`` can all be used in the same rule,
+but cannot be repeated within the same condition. ``any_one_of`` and
+``not_any_of`` are mutually exclusive within a condition's scope. So are
+``whitelist`` and ``blacklist``.
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        },
+                        "group": {
+                            "id": "0cd5e9"
+                        }
+                    },
+                ],
+                "remote": [
+                    {
+                    "type": "UserName"
+                    },
+                    {
+                        "type": "cn=IBM_Canada_Lab",
+                        "not_any_of": [
+                            ".*@naww.com$"
+                        ],
+                        "regex": true
+                    },
+                    {
+                        "type": "cn=IBM_USA_Lab",
+                        "any_one_of": [
+                            ".*@yeah.com$"
+                        ]
+                        "regex": true
+                    }
+                ]
+            }
+        ]
+    }
+
+As before group names and users can also be provided in the local section.
+
+This allows any user with the following claim information to be mapped to
+group with id 0cd5e9.
+
+.. code-block:: javascript
+
+     {"UserName":"<any_name>@yeah.com"}
+     {"cn=IBM_USA_Lab":"<any_name>@yeah.com"}
+     {"cn=IBM_Canada_Lab":"<any_name>@yeah.com"}
+
+The following claims will be mapped:
+
+- any claim containing the key UserName.
+- any claim containing key cn=IBM_Canada_Lab that doesn't have the value <any_name>@naww.com.
+- any claim containing key cn=IBM_USA_Lab that has value <any_name>@yeah.com.
+
+Multiple Rules
+--------------
+
+Multiple rules can also be utilized in a mapping.
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        },
+                        "group": {
+                            "name": "non-contractors",
+                            "domain": {
+                                "id": "abc1234"
+                            }
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                    "type": "UserName"
+                    },
+                    {
+                        "type": "orgPersonType",
+                        "not_any_of": [
+                            "Contractor",
+                            "SubContractor"
+                        ]
+                    }
+                ]
+            },
+            {
+                "local": [
+                    {
+                        "user": {
+                            "name": "{0}"
+                        },
+                        "group": {
+                            "name": "contractors",
+                            "domain": {
+                                "id": "abc1234"
+                            }
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                    "type": "UserName"
+                    },
+                    {
+                        "type": "orgPersonType",
+                        "any_one_of": [
+                            "Contractor",
+                            "SubContractor"
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+
+
+The above assigns groups membership basing on ``orgPersonType`` values:
+
+- neither ``Contractor`` nor ``SubContractor`` will belong to the ``non-contractors`` group.
+- either ``Contractor or ``SubContractor`` will belong to the ``contractors`` group.
+
+Rules are additive, so permissions will only be granted for the rules that
+succeed.  All the remote conditions of a rule must be valid.
+
+When using multiple rules you can specify more than one effective user
+identification, but only the first match will be considered and the others
+ignored ordered from top to bottom.
+
+Since rules are additive one can specify one user identification and this will
+also work. The best practice for multiple rules is to create a rule for just
+user and another rule for just groups. Below is rules example repeated but with
+global username mapping.
+
+
+.. code-block:: javascript
+
+    {
+        "rules": [
+            {
+                "local": [
+                    "user": {
+                        "id": "{0}"
+                    }
+                ],
+                "remote": [
+                    {
+                        "type": "UserType"
+                    }
+                ]
+            },
+            {
+                "local": [
+                    {
+                        "group": {
+                            "name": "non-contractors",
+                            "domain": {
+                                "id": "abc1234"
+                            }
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                        "type": "orgPersonType",
+                        "not_any_of": [
+                            "Contractor",
+                            "SubContractor"
+                        ]
+                    }
+                ]
+            },
+            {
+                "local": [
+                    {
+                        "group": {
+                            "name": "contractors",
+                            "domain": {
+                                "id": "abc1234"
+                            }
+                        }
+                    }
+                ],
+                "remote": [
+                    {
+                        "type": "orgPersonType",
+                        "any_one_of": [
+                            "Contractor",
+                            "SubContractor"
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+
+
diff --git a/keystone-moon/doc/source/mapping_schema.rst b/keystone-moon/doc/source/mapping_schema.rst
new file mode 100644
index 00000000..a020178b
--- /dev/null
+++ b/keystone-moon/doc/source/mapping_schema.rst
@@ -0,0 +1,160 @@
+..
+    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.
+
+=============================
+Mapping Schema for Federation
+=============================
+
+Description
+-----------
+
+The schema for mapping is a description of how a mapping should be created.
+It shows all the requirements and possibilities for a JSON to be used for mapping.
+
+Mapping schema is validated with `JSON Schema
+<http://http://json-schema.org/documentation.html>`__
+
+Mapping Schema
+--------------
+
+The rules supported must use the following schema:
+
+.. code-block:: javascript
+
+    {
+        "type": "object",
+        "required": ['rules'],
+        "properties": {
+            "rules": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": ['local', 'remote'],
+                    "additionalProperties": False,
+                    "properties": {
+                        "local": {
+                            "type": "array"
+                        },
+                        "remote": {
+                            "minItems": 1,
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "oneOf": [
+                                    {"$ref": "#/definitions/empty"},
+                                    {"$ref": "#/definitions/any_one_of"},
+                                    {"$ref": "#/definitions/not_any_of"},
+                                    {"$ref": "#/definitions/blacklist"},
+                                    {"$ref": "#/definitions/whitelist"}
+                                ],
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "definitions": {
+            "empty": {
+                "type": "object",
+                "required": ['type'],
+                "properties": {
+                    "type": {
+                        "type": "string"
+                    },
+                },
+                "additionalProperties": False,
+            },
+            "any_one_of": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ['type', 'any_one_of'],
+                "properties": {
+                    "type": {
+                        "type": "string"
+                    },
+                    "any_one_of": {
+                        "type": "array"
+                    },
+                    "regex": {
+                        "type": "boolean"
+                    }
+                }
+            },
+            "not_any_of": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ['type', 'not_any_of'],
+                "properties": {
+                    "type": {
+                        "type": "string"
+                    },
+                    "not_any_of": {
+                        "type": "array"
+                    },
+                    "regex": {
+                        "type": "boolean"
+                    }
+                }
+            },
+            "blacklist": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ['type', 'blacklist'],
+                "properties": {
+                    "type": {
+                        "type": "string"
+                    },
+                    "blacklist": {
+                        "type": "array"
+                    }
+                }
+            },
+            "whitelist": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ['type', 'whitelist'],
+                "properties": {
+                    "type": {
+                        "type": "string"
+                    },
+                    "whitelist": {
+                        "type": "array"
+                    }
+                }
+            }
+        }
+    }
+
+.. NOTE::
+
+    ``"additionalProperties": False``, shows that only the properties shown can be displayed.
+
+    .. code-block:: javascript
+
+        "whitelist": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ['type', 'whitelist'],
+                "properties": {
+                    "type": {
+                        "type": "string"
+                    },
+                    "whitelist": {
+                        "type": "array"
+                    }
+                }
+            }
+
+    Keystone will not accept any other keys in the JSON mapping other than ``type``, and
+    ``whitelist``.
diff --git a/keystone-moon/doc/source/policy_mapping.rst b/keystone-moon/doc/source/policy_mapping.rst
new file mode 100644
index 00000000..9b11efd6
--- /dev/null
+++ b/keystone-moon/doc/source/policy_mapping.rst
@@ -0,0 +1,213 @@
+===============================
+Mapping of policy target to API
+===============================
+
+The following table shows the target in the policy.json file for each API.
+
+=========================================================  ===
+Target                                                     API
+=========================================================  ===
+identity:get_region                                        GET /v3/regions/{region_id}
+identity:list_regions                                      GET /v3/regions
+identity:create_region                                     POST /v3/regions
+identity:update_region                                     PATCH /v3/regions/{region_id}
+identity:delete_region                                     DELETE /v3/regions/{region_id}
+
+identity:get_service                                       GET /v3/services/{service_id}
+identity:list_services                                     GET /v3/services
+identity:create_service                                    POST /v3/services
+identity:update_service                                    PATCH /v3/services/{service__id}
+identity:delete_service                                    DELETE /v3/services/{service__id}
+
+identity:get_endpoint                                      GET /v3/endpoints/{endpoint_id}
+identity:list_endpoints                                    GET /v3/endpoints
+identity:create_endpoint                                   POST /v3/endpoints
+identity:update_endpoint                                   PATCH /v3/endpoints/{endpoint_id}
+identity:delete_endpoint                                   DELETE /v3/endpoints/{endpoint_id}
+
+identity:get_domain                                        GET /v3/domains/{domain_id}
+identity:list_domains                                      GET /v3/domains
+identity:create_domain                                     POST /v3/domains
+identity:update_domain                                     PATCH /v3/domains/{domain_id}
+identity:delete_domain                                     DELETE /v3/domains/{domain_id}
+
+identity:get_project                                       GET /v3/projects/{project_id}
+identity:list_projects                                     GET /v3/projects
+identity:list_user_projects                                GET /v3/users/{user_id}/projects
+identity:create_project                                    POST /v3/projects
+identity:update_project                                    PATCH /v3/projects/{project_id}
+identity:delete_project                                    DELETE /v3/projects/{project_id}
+
+identity:get_user                                          GET /v3/users/{user_id}
+identity:list_users                                        GET /v3/users
+identity:create_user                                       POST /v3/users
+identity:update_user                                       PATCH /v3/users/{user_id}
+identity:delete_user                                       DELETE /v3/users/{user_id}
+identity:change_password                                   POST /v3/users/{user_id}/password
+
+identity:get_group                                         GET /v3/groups/{group_id}
+identity:list_groups                                       GET /v3/groups
+identity:list_groups_for_user                              GET /v3/users/{user_id}/groups
+identity:create_group                                      POST /v3/groups
+identity:update_group                                      PATCH /v3/groups/{group_id}
+identity:delete_group                                      DELETE /v3/groups/{group_id}
+identity:list_users_in_group                               GET /v3/groups/{group_id}/users
+identity:remove_user_from_group                            DELETE /v3/groups/{group_id}/users/{user_id}
+identity:check_user_in_group                               GET /v3/groups/{group_id}/users/{user_id}
+identity:add_user_to_group                                 PUT /v3/groups/{group_id}/users/{user_id}
+
+identity:get_credential                                    GET /v3/credentials/{credential_id}
+identity:list_credentials                                  GET /v3/credentials
+identity:create_credential                                 POST /v3/credentials
+identity:update_credential                                 PATCH /v3/credentials/{credential_id}
+identity:delete_credential                                 DELETE /v3/credentials/{credential_id}
+
+identity:ec2_get_credential                                GET /v3/users/{user_id}/credentials/OS-EC2/{credential_id}
+identity:ec2_list_credentials                              GET /v3/users/{user_id}/credentials/OS-EC2
+identity:ec2_create_credential                             POST /v3/users/{user_id}/credentials/OS-EC2
+identity:ec2_delete_credential                             DELETE /v3/users/{user_id}/credentials/OS-EC2/{credential_id}
+
+identity:get_role                                          GET /v3/roles/{role_id}
+identity:list_roles                                        GET /v3/roles
+identity:create_role                                       POST /v3/roles
+identity:update_role                                       PATCH /v3/roles/{role_id}
+identity:delete_role                                       DELETE /v3/roles/{role_id}
+
+identity:check_grant                                       GET `grant_resources`_
+identity:list_grants                                       GET `grant_collections`_
+identity:create_grant                                      PUT `grant_resources`_
+identity:revoke_grant                                      DELETE `grant_resources`_
+
+identity:list_role_assignments                             GET /v3/role_assignments
+
+identity:get_policy                                        GET /v3/policy/{policy_id}
+identity:list_policies                                     GET /v3/policy
+identity:create_policy                                     POST /v3/policy
+identity:update_policy                                     PATCH /v3/policy/{policy_id}
+identity:delete_policy                                     DELETE /v3/policy/{policy_id}
+
+identity:check_token                                       HEAD /v3/auth/tokens
+identity:validate_token                                    - GET /v2.0/tokens/{token_id}
+                                                           - GET /v3/auth/tokens
+identity:validate_token_head                               HEAD /v2.0/tokens/{token_id}
+identity:revocation_list                                   - GET /v2.0/tokens/revoked
+                                                           - GET /v3/auth/tokens/OS-PKI/revoked
+identity:revoke_token                                      DELETE /v3/auth/tokens
+identity:create_trust                                      POST /v3/OS-TRUST/trusts
+identity:list_trusts                                       GET /v3/OS-TRUST/trusts
+identity:list_roles_for_trust                              GET /v3/OS-TRUST/trusts/{trust_id}/roles
+identity:get_role_for_trust                                GET /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id}
+identity:delete_trust                                      DELETE /v3/OS-TRUST/trusts/{trust_id}
+
+identity:create_consumer                                   POST /v3/OS-OAUTH1/consumers
+identity:get_consumer                                      GET /v3/OS-OAUTH1/consumers/{consumer_id}
+identity:list_consumers                                    GET /v3/OS-OAUTH1/consumers
+identity:delete_consumer                                   DELETE /v3/OS-OAUTH1/consumers/{consumer_id}
+identity:update_consumer                                   PATCH /v3/OS-OAUTH1/consumers/{consumer_id}
+
+identity:authorize_request_token                           PUT /v3/OS-OAUTH1/authorize/{request_token_id}
+identity:list_access_token_roles                           GET /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}/roles
+identity:get_access_token_role                             GET /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}/roles/{role_id}
+identity:list_access_tokens                                GET /v3/users/{user_id}/OS-OAUTH1/access_tokens
+identity:get_access_token                                  GET /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}
+identity:delete_access_token                               DELETE /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}
+
+identity:list_projects_for_endpoint                        GET /v3/OS-EP-FILTER/endpoints/{endpoint_id}/projects
+identity:add_endpoint_to_project                           PUT /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}
+identity:check_endpoint_in_project                         GET /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}
+identity:list_endpoints_for_project                        GET /v3/OS-EP-FILTER/projects/{project_id}/endpoints
+identity:remove_endpoint_from_project                      DELETE /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id}
+
+identity:create_endpoint_group                             POST /v3/OS-EP-FILTER/endpoint_groups
+identity:list_endpoint_groups                              GET /v3/OS-EP-FILTER/endpoint_groups
+identity:get_endpoint_group                                GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}
+identity:update_endpoint_group                             PATCH /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}
+identity:delete_endpoint_group                             DELETE /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}
+identity:list_projects_associated_with_endpoint_group      GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects
+identity:list_endpoints_associated_with_endpoint_group     GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/endpoints
+identity:get_endpoint_group_in_project                     GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}
+identity:list_endpoint_groups_for_project                  GET /v3/OS-EP-FILTER/projects/{project_id}/endpoint_groups
+identity:add_endpoint_group_to_project                     PUT /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}
+identity:remove_endpoint_group_from_project                DELETE /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id}
+
+identity:create_identity_provider                          PUT /v3/OS-FEDERATION/identity_providers/{idp_id}
+identity:list_identity_providers                           GET /v3/OS-FEDERATION/identity_providers
+identity:get_identity_providers                            GET /v3/OS-FEDERATION/identity_providers/{idp_id}
+identity:update_identity_provider                          PATCH /v3/OS-FEDERATION/identity_providers/{idp_id}
+identity:delete_identity_provider                          DELETE /v3/OS-FEDERATION/identity_providers/{idp_id}
+
+identity:create_protocol                                   PUT /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
+identity:update_protocol                                   PATCH /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
+identity:get_protocol                                      GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
+identity:list_protocols                                    GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols
+identity:delete_protocol                                   DELETE /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
+
+identity:create_mapping                                    PUT /v3/OS-FEDERATION/mappings/{mapping_id}
+identity:get_mapping                                       GET /v3/OS-FEDERATION/mappings/{mapping_id}
+identity:list_mappings                                     GET /v3/OS-FEDERATION/mappings
+identity:delete_mapping                                    DELETE /v3/OS-FEDERATION/mappings/{mapping_id}
+identity:update_mapping                                    PATCH /v3/OS-FEDERATION/mappings/{mapping_id}
+
+identity:create_service_provider                           PUT /v3/OS-FEDERATION/service_providers/{sp_id}
+identity:list_service_providers                            GET /v3/OS-FEDERATION/service_providers
+identity:get_service_provider                              GET /v3/OS-FEDERATION/service_providers/{sp_id}
+identity:update_service_provider                           PATCH /v3/OS-FEDERATION/service_providers/{sp_id}
+identity:delete_service_provider                           DELETE /v3/OS-FEDERATION/service_providers/{sp_id}
+
+identity:get_auth_catalog                                  GET /v3/auth/catalog
+identity:get_auth_projects                                 GET /v3/auth/projects
+identity:get_auth_domains                                  GET /v3/auth/domains
+
+identity:list_projects_for_groups                          GET /v3/OS-FEDERATION/projects
+identity:list_domains_for_groups                           GET /v3/OS-FEDERATION/domains
+
+identity:list_revoke_events                                GET /v3/OS-REVOKE/events
+
+identity:create_policy_association_for_endpoint            PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}
+identity:check_policy_association_for_endpoint             GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}
+identity:delete_policy_association_for_endpoint            DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}
+identity:create_policy_association_for_service             PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}
+identity:check_policy_association_for_service              GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}
+identity:delete_policy_association_for_service             DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}
+identity:create_policy_association_for_region_and_service  PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id}
+identity:check_policy_association_for_region_and_service   GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id}
+identity:delete_policy_association_for_region_and_service  DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id}
+identity:get_policy_for_endpoint                           GET /v3/endpoints/{endpoint_id}/OS-ENDPOINT-POLICY/policy
+identity:list_endpoints_for_policy                         GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints
+
+identity:create_domain_config                              PUT /v3/domains/{domain_id}/config
+identity:get_domain_config                                 - GET /v3/domains/{domain_id}/config
+                                                           - GET /v3/domains/{domain_id}/config/{group}
+                                                           - GET /v3/domains/{domain_id}/config/{group}/{option}
+identity:update_domain_config                              - PATCH /v3/domains/{domain_id}/config
+                                                           - PATCH /v3/domains/{domain_id}/config/{group}
+                                                           - PATCH /v3/domains/{domain_id}/config/{group}/{option}
+identity:delete_domain_config                              - DELETE /v3/domains/{domain_id}/config
+                                                           - DELETE /v3/domains/{domain_id}/config/{group}
+                                                           - DELETE /v3/domains/{domain_id}/config/{group}/{option}
+
+=========================================================  ===
+
+.. _grant_resources:
+
+*grant_resources* are:
+
+- /v3/projects/{project_id}/users/{user_id}/roles/{role_id}
+- /v3/projects/{project_id}/groups/{group_id}/roles/{role_id}
+- /v3/domains/{domain_id}/users/{user_id}/roles/{role_id}
+- /v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}
+- /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+- /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+- /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+- /v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+.. _grant_collections:
+
+*grant_collections* are:
+
+- /v3/projects/{project_id}/users/{user_id}/roles
+- /v3/projects/{project_id}/groups/{group_id}/roles
+- /v3/domains/{domain_id}/users/{user_id}/roles
+- /v3/domains/{domain_id}/groups/{group_id}/role
+- /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/inherited_to_projects
+- /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/inherited_to_projects
diff --git a/keystone-moon/doc/source/setup.rst b/keystone-moon/doc/source/setup.rst
index f919dccc..d1ce8f4c 100644
--- a/keystone-moon/doc/source/setup.rst
+++ b/keystone-moon/doc/source/setup.rst
@@ -18,27 +18,23 @@
 Setting up a Keystone development environment
 =============================================
 
-This document describes getting the source from keystone's `GitHub repository`_
+This document describes getting the source from keystone's `Git repository`_
 for development purposes.
 
 To install Keystone from packaging, refer instead to Keystone's `User
 Documentation`_.
 
-.. _`GitHub Repository`: http://github.com/openstack/keystone
+.. _`Git Repository`: http://git.openstack.org/cgit/openstack/keystone
 .. _`User Documentation`: http://docs.openstack.org/
 
 Prerequisites
 =============
 
-This document assumes you are using:
-
-- Ubuntu, Fedora or openSUSE (SLE)
-- `Python 2.7`_
-
-.. _`Python 2.7`: http://www.python.org/
+This document assumes you are using Ubuntu, Fedora or openSUSE (SLE)
 
 And that you have the following tools available on your system:
 
+- Python_ 2.7 and 3.4
 - git_
 - setuptools_
 - pip_
@@ -48,17 +44,18 @@ And that you have the following tools available on your system:
 **Reminder**: If you're successfully using a different platform, or a
 different version of the above, please document your configuration here!
 
+.. _Python: http://www.python.org/
 .. _git: http://git-scm.com/
 .. _setuptools: http://pypi.python.org/pypi/setuptools
 
 Getting the latest code
 =======================
 
-Make a clone of the code from our `Github repository`:
+Make a clone of the code from our `Git repository`:
 
 .. code-block:: bash
 
-    $ git clone https://github.com/openstack/keystone.git
+    $ git clone https://git.openstack.org/openstack/keystone.git
 
 When that is complete, you can:
 
@@ -86,18 +83,19 @@ extension, PyPi) cannot satisfy. These dependencies should be installed
 prior to using `pip`, and the installation method may vary depending on
 your platform.
 
-Ubuntu 12.04:
+Ubuntu 14.04:
 
 .. code-block:: bash
 
-    $ sudo apt-get install python-dev libxml2-dev libxslt1-dev libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev
+    $ sudo apt-get install python-dev python3-dev libxml2-dev libxslt1-dev \
+        libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev
 
 
 Fedora 19+:
 
 .. code-block:: bash
 
-    $ sudo yum install python-sqlite2 python-lxml python-greenlet-devel python-ldap sqlite-devel openldap-devel python-devel libxslt-devel openssl-devel
+    $ sudo yum install python-lxml python-greenlet-devel python-ldap sqlite-devel openldap-devel python-devel libxslt-devel openssl-devel libffi-devel
 
 openSUSE 13.2 (SLE 12):
 
@@ -137,7 +135,7 @@ see virtualenv_.
 .. _virtualenv: http://www.virtualenv.org/
 
 If you want to run Keystone outside of a virtualenv, you can install the
-dependencies directly into your system from the requires files:
+dependencies directly into your system from the requirements files:
 
 .. code-block:: bash
 
@@ -161,15 +159,12 @@ forget to activate it:
 .. code-block:: bash
 
     $ source .venv/bin/activate
-    $ python
 
-You should then be able to `import keystone` from your Python shell
-without issue:
+You should then be able to `import keystone` using Python without issue:
 
-.. code-block:: python
+.. code-block:: bash
 
-    >>> import keystone
-    >>>
+    $ python -c "import keystone"
 
-If you can import Keystone successfully, you should be ready to move on to
-:doc:`developing`.
+If you can import Keystone without a traceback, you should be ready to move on
+to :doc:`developing`.