Added Keystone to Keystone mapping sample and doc page

This mapping sample creates a simple sister-projects concept. When
a user comes in through a remote openstack, he is given the
following:
1. a username with the same username
2. a group with the same name as the project the user was scoped to
   in the remote openstack
3. a user and group with no permissions at all if he is the user
   named admin, or any of the openstack service users

To go along with it, a documentation page that describes federation
and points to pages in the keystone documentation was created.

Change-Id: Ic297ec307451f26af0c38d9c7ba6794f46bac4d7

doc/source/identity.rst

@@ -0,0 +1,74 @@
+================================
+Authentication and Authorization
+================================
+
+To perform authentication between service providers, mixmatch uses
+Keystone-to-Keystone. This feature allows federation of identities between
+OpenStack deployments.
+
+For more information on Keystone-to-Keystone federation please visit the
+Keystone documentation_. The rest of this page will assume that you have
+already set up federation.
+
+We will use the word *remote* to refer to where the user is authenticating
+from (identity provider), and *local* to refer to where the user is
+authenticating to (service provider).
+
+.. _documentation: http://docs.openstack.org/developer/keystone/federation/federated_identity.html
+
+Mappings
+========
+
+When a SAML2 assertion is presented to Keystone from the user, Keystone will
+use the attributes in the assertion to determine the user credentials and
+level of authorization to grant to the user. This is done through mappings_.
+
+.. _mappings: http://docs.openstack.org/developer/keystone/federation/mapping_combinations.html
+
+In our reference architecture, a user is given access to a local project of
+the same name as the remote project.
+This is accomplished with the following mapping rules which can be modified
+based on requirements: ::
+
+    [
+        {
+            "local": [
+                {
+                    "user": {
+                        "name": "{0}"
+                    },
+                    "group": {
+                        "name": "{1}",
+                        "domain": { "id": "default" }
+                    }
+                }
+            ],
+            "remote": [
+                {
+                    "type": "openstack_user"
+                },
+                {
+                    "type": "openstack_project"
+                },
+                {
+                    "type": "openstack_user",
+                    "not_any_of": [
+                      "admin",
+                      "nova",
+                      "cinder",
+                      "glance",
+                      "neutron"
+                    ]
+                }
+            ]
+        }
+    ]
+
+
+The above ruleset will map the remote user to a user and group, such
+that:
+
+- Username of the local user is the same as the remote user
+- Group the user is assigned to is named the same way as the the remote
+  project (group must be created ahead of time and granted the appropriate
+  permissions.)

doc/source/index.rst

@@ -14,6 +14,7 @@ Contents:
    readme
    architecture
    installation
+   identity
    contributing
 
 Indices and tables