Document websso setup

there are a few extra steps necessary for supporting horizon and
a federated keystone, these need to be documented.

Change-Id: I468e5591de9b77b44de995d855dc9b133bf0e741

2 files changed, 222 insertions, 0 deletions

diff --git a/doc/source/configure_federation.rst b/doc/source/configure_federation.rst
index 2da5f822e..dbbd34c92 100644
--- a/doc/source/configure_federation.rst
+++ b/doc/source/configure_federation.rst
@@ -65,6 +65,14 @@ Using Shibboleth and OpenID Connect are documented so far.
 .. _`Setup Shibboleth`: extensions/shibboleth.html
 .. _`Setup OpenID Connect`: extensions/openidc.html
 
+Configure Keystone and Horizon for Single Sign-On
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* To configure horizon to access a federated keystone,
+  follow the steps outlined at: `Keystone Federation and Horizon`_.
+
+.. _`Keystone Federation and Horizon`: extensions/websso.html
+
 Enable the ``OS-FEDERATION`` extension
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/extensions/websso.rst b/doc/source/extensions/websso.rst
new file mode 100644
index 000000000..9ce6b9a14
--- /dev/null
+++ b/doc/source/extensions/websso.rst
@@ -0,0 +1,214 @@
+: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/` 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
+      </LocationMatch>
+  </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
+      </LocationMatch>
+  </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
+      </LocationMatch>
+  </VirtualHost>
+
+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``.
+
+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_CHOICES = "credentials"