summaryrefslogtreecommitdiffstats
path: root/keystone-moon/doc/source/federation/websso.rst
blob: 4ada0a4cc2422a22be40d563a8e12e1f9df14b46 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
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"