Browse Source

Reorganize guide on configuring a keystone SP

The federation guide on configuring keystone as a Service Provider is
disjointed and hard to follow. This patch reorganizes it as follows to
improve the flow by first moving the instructions on creating an IdP,
mapping, and protocol in keystone to the beginning, since all other
steps in this guide depend on understanding what these objects are and
deciding on a name for them, and second by consolidating instructions on
creating role assignments into the section on mappings, since these two
concepts are informed by one another and splitting them apart makes
it difficult to mentally connect them. It also cleans up and clarifies
some of the wording and pares down unnecessary tangents.

Partial-bug: #1793374

Change-Id: Ib09f127f47a0897cc1be03428bfae70f3f18e174
tags/15.0.0.0rc1
Colleen Murphy 6 months ago
parent
commit
4d7bc6a36d

+ 151
- 189
doc/source/admin/federation/configure_federation.rst View File

@@ -18,6 +18,8 @@ Configuring Keystone for Federation
18 18
 Keystone as a Service Provider (SP)
19 19
 -----------------------------------
20 20
 
21
+.. _sp-prerequisites:
22
+
21 23
 Prerequisites
22 24
 -------------
23 25
 
@@ -75,170 +77,76 @@ Provider.
75 77
 .. _custom auth method: ../../contributor/auth-plugins
76 78
 .. _register as an external driver: ../../contributor/developing-drivers
77 79
 
78
-Configure Apache to use a federation capable authentication method
79
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
-
81
-There is currently support for two major federation protocols:
82
-
83
-* SAML - Keystone supports the following implementations:
84
-
85
-  * Shibboleth - see `Setup Shibboleth`_.
86
-  * Mellon - see `Setup Mellon`_.
87
-
88
-* OpenID Connect - see `Setup OpenID Connect`_.
89
-
90
-.. _`Setup Shibboleth`: shibboleth.html
91
-.. _`Setup OpenID Connect`: openidc.html
92
-.. _`Setup Mellon`: mellon.html
93
-
94
-Configure keystone and Horizon for Single Sign-On
95
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80
+Creating federation resources in keystone
81
+-----------------------------------------
96 82
 
97
-* To configure horizon to access a federated keystone,
98
-  follow the steps outlined at: `Keystone Federation and Horizon`_.
83
+You need to create three resources via the keystone API to identify the Identity
84
+Provider to keystone and align remote user attributes with keystone objects:
99 85
 
100
-.. _`Keystone Federation and Horizon`: websso.html
86
+* `Create an Identity Provider`_
87
+* `Create a Mapping`_
88
+* `Create a Protocol`_
101 89
 
102
-Configure Federation in Keystone
103
---------------------------------
104
-
105
-Now that the Identity Provider and keystone are communicating we can start to
106
-configure ``federation``.
90
+See also the `keystone federation API reference`_.
107 91
 
108
-1. `Configure authentication drivers in keystone.conf`_
109
-2. `Create keystone groups and assign roles`_
110
-3. `Add Identity Provider(s), Mapping(s), and Protocol(s)`_
92
+.. _keystone federation API reference: https://developer.openstack.org/api-ref/identity/v3-ext/#os-federation-api
111 93
 
112
-Configure authentication drivers in keystone.conf
113
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114
-
115
-Add the authentication methods to the ``[auth]`` section in ``keystone.conf``.
116
-Names should be equal to protocol names added via Identity API v3. Here we use
117
-examples ``saml2`` and ``openid``.
94
+Create an Identity Provider
95
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
118 96
 
119
-.. code-block:: ini
120
-
121
-   [auth]
122
-   methods = external,password,token,saml2,openid
123
-
124
-Create keystone groups and assign roles
125
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126
-
127
-As mentioned earlier, no new users will be added to the Identity backend, but
128
-the Identity Service requires group-based role assignments to authorize
129
-federated users. The federation mapping function will map the user into local
130
-Identity Service groups objects, and hence to local role assignments.
131
-
132
-Thus, it is required to create the necessary Identity Service groups that
133
-correspond to the Identity Provider's groups; additionally, these groups should
134
-be assigned roles on one or more projects or domains.
135
-
136
-You may be interested in more information on `group management
137
-<https://developer.openstack.org/api-ref/identity/v3/#create-group>`_
138
-and `role assignments
139
-<https://developer.openstack.org/api-ref/identity/v3/#assign-role-to-group-on-project>`_,
140
-both of which are exposed to the CLI via `python-openstackclient
141
-<https://pypi.org/project/python-openstackclient/>`_.
142
-
143
-For example, create a new domain and project like this:
144
-
145
-.. code-block:: console
146
-
147
-   $ openstack domain create federated_domain
148
-   $ openstack project create federated_project --domain federated_domain
149
-
150
-And a new group like this:
97
+Create an Identity Provider object in keystone, which represents the Identity
98
+Provider we will use to authenticate end users:
151 99
 
152 100
 .. code-block:: console
153 101
 
154
-   $ openstack group create federated_users
102
+   $ openstack identity provider create --remote-id https://samltest.id/saml/idp samltest
155 103
 
156
-Add the group to the domain and project:
104
+The value for the ``remote-id`` option is the unique identifier provided by the
105
+Identity Provider, called the `entity ID` or the `remote ID`. For a SAML
106
+Identity Provider, it can found by querying its metadata endpoint:
157 107
 
158 108
 .. code-block:: console
159 109
 
160
-   $ openstack role add --group federated_users --domain federated_domain Member
161
-   $ openstack role add --group federated_users --project federated_project Member
110
+   $ curl -s https://samltest.id/saml/idp | grep -o 'entityID=".*"'
111
+   entityID="https://samltest.id/saml/idp"
162 112
 
163
-We'll later add a mapping that makes all federated users a part of this group
164
-and therefore members of the new domain.
113
+For an OpenID Connect IdP, it is the Identity Provider's Issuer Identifier.
114
+A remote ID must be globally unique: two identity providers cannot be associated
115
+with the same remote ID. The remote ID will usually appear as a URN but but need
116
+not be a resolvable URL.
165 117
 
166
-Add Identity Provider(s), Mapping(s), and Protocol(s)
167
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118
+The local name, called ``samltest`` in our example, is decided by you and will
119
+be used by the mapping and protocol, and later for authentication.
168 120
 
169
-To utilize federation the following must be created in the Identity Service:
121
+.. note::
170 122
 
171
-* `Identity Provider`_
172
-* `Mapping`_
173
-* `Protocol`_
123
+   An identity provider keystone object may have multiple ``remote-ids``
124
+   specified, this allows the same *keystone* identity provider resource to be
125
+   used with multiple external identity providers. For example, an identity
126
+   provider resource ``university-idp``, may have the following ``remote_ids``:
127
+   ``['university-x', 'university-y', 'university-z']``.
128
+   This removes the need to configure N identity providers in keystone.
174 129
 
175
-Read more about `federation in keystone
176
-<https://developer.openstack.org/api-ref/identity/v3-ext/#os-federation-api>`__.
130
+See also the `API reference on identity providers`_.
177 131
 
178
-~~~~~~~~~~~~~~~~~
179
-Identity Provider
180
-~~~~~~~~~~~~~~~~~
132
+.. _API reference on identity providers: https://developer.openstack.org/api-ref/identity/v3-ext/#identity-providers
181 133
 
182
-Create an Identity Provider object in keystone, which represents the Identity
183
-Provider we will use to authenticate end users:
134
+Create a Mapping
135
+~~~~~~~~~~~~~~~~
184 136
 
185
-.. code-block:: console
186
-
187
-   $ openstack identity provider create --remote-id https://samltest.id/saml/idp samltest
188
-
189
-The value for the ``remote-id`` option is the unique identifier provided by the
190
-IdP. For a SAML IdP it can found as the EntityDescriptor entityID in the IdP's
191
-provided metadata. If the IdP is a keystone IdP, it is the value set in that
192
-keystone's ``[saml]/idp_entity_id`` option. For an OpenID Connect IdP, it is
193
-the IdP's Issuer Identifier. It will usually appear as a URI but there is no
194
-requirement for it to resolve to anything and may be arbitrarily decided by the
195
-administrator of the IdP. The local name, here called 'samltest', is decided by
196
-you and will be used by the mapping and protocol, and later for authentication.
197
-
198
-A keystone identity provider may have multiple `remote_ids` specified, this
199
-allows the same *keystone* identity provider resource to be used with multiple
200
-external identity providers. For example, an identity provider resource
201
-``university-idp``, may have the following `remote_ids`:
202
-``['university-x', 'university-y', 'university-z']``.
203
-This removes the need to configure N identity providers in keystone.
204
-
205
-.. NOTE::
206
-
207
-    Remote IDs are globally unique. Two identity providers cannot be
208
-    associated with the same remote ID. Once authenticated with the external
209
-    identity provider, keystone will determine which identity provider
210
-    and mapping to use based on the protocol and the value returned from the
211
-    `remote_id_attribute` key.
212
-
213
-    For example, if our identity provider is ``google``, the mapping used is
214
-    ``google_mapping`` and the protocol is ``openid``. The identity provider's
215
-    remote IDs  would be: [``https://accounts.google.com``].
216
-    The `remote_id_attribute` value may be set to ``HTTP_OIDC_ISS``, since
217
-    this value will always be ``https://accounts.google.com``.
218
-
219
-    The motivation for this approach is that there will always be some data
220
-    sent by the identity provider (in the assertion or claim) that uniquely
221
-    identifies the identity provider. This removes the requirement for horizon
222
-    to list all the identity providers that are trusted by keystone.
223
-
224
-Read more about `identity providers
225
-<https://developer.openstack.org/api-ref/identity/v3-ext/#identity-providers>`__.
226
-
227
-~~~~~~~
228
-Mapping
229
-~~~~~~~
230
-A mapping is a list of rules. The only Identity API objects that will support mapping are groups
231
-and users.
232
-
233
-Mapping adds a set of rules to map federation protocol attributes to Identity API objects.
234
-There are many different ways to setup as well as combine these rules. More information on
235
-rules can be found on the :doc:`mapping_combinations` page.
137
+Next, create a mapping. A mapping is a set of rules that link the attributes of
138
+a remote user to user properties that keystone understands. It is especially
139
+useful for granting remote users authorization to keystone resources, either by
140
+associating them with a local keystone group and inheriting its role
141
+assignments, or dynamically provisioning projects within keystone based on these
142
+rules.
236 143
 
237 144
 An Identity Provider has exactly one mapping specified per protocol.
238
-Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol.
145
+Mapping objects can be used multiple times by different combinations of Identity
146
+Provider and Protocol.
239 147
 
240
-As a simple example, if keystone is your IdP, you can map a few known remote
241
-users to the group you already created:
148
+As a simple example, create a mapping with a single rule to map all remote users
149
+to a local user in a single group in keystone:
242 150
 
243 151
 .. code-block:: console
244 152
 
@@ -260,14 +168,7 @@ users to the group you already created:
260 168
            ],
261 169
            "remote": [
262 170
                {
263
-                   "type": "openstack_user"
264
-               },
265
-               {
266
-                   "type": "openstack_user",
267
-                   "any_one_of": [
268
-                       "demo",
269
-                       "alt_demo"
270
-                   ]
171
+                   "type": "REMOTE_USER"
271 172
                }
272 173
            ]
273 174
        }
@@ -275,58 +176,119 @@ users to the group you already created:
275 176
    EOF
276 177
    $ openstack mapping create --rules rules.json samltest_mapping
277 178
 
278
-As another example, if Shibboleth is your IdP, the remote section should use REMOTE_USER as the remote type:
179
+This mapping rule evaluates the ``REMOTE_USER`` variable set by the HTTPD auth
180
+module and uses it to fill in the name of the local user in keystone. It also
181
+ensures all remote users become effective members of the ``federated_users``
182
+group, thereby inheriting the group's role assignments.
183
+
184
+In this example, the ``federated_users`` group must exist in the keystone
185
+Identity backend and must have a role assignment on some project, domain, or
186
+system in order for federated users to have an authorization in keystone. For
187
+example, to create the group:
279 188
 
280 189
 .. code-block:: console
281 190
 
282
-   $ cat > rules.json <<EOF
283
-   [
284
-       {
285
-           "local": [
286
-               {
287
-                   "user": {
288
-                       "name": "{0}"
289
-                   },
290
-                   "group": {
291
-                       "domain": {
292
-                           "name": "Default"
293
-                       },
294
-                       "name": "federated_users"
295
-                   }
296
-               }
297
-           ],
298
-           "remote": [
299
-               {
300
-                   "type": "REMOTE_USER"
301
-               }
302
-           ]
303
-       }
304
-   ]
305
-   EOF
306
-   $ openstack mapping create --rules rules.json samltest_mapping
191
+   $ openstack group create federated_users
192
+
193
+Create a project these users should be assigned to:
194
+
195
+.. code-block:: console
307 196
 
308
-Read more about `mapping
309
-<https://developer.openstack.org/api-ref/identity/v3-ext/#mappings>`__.
197
+   $ openstack project create federated_project
198
+
199
+Assign the group a ``member`` role in the project:
200
+
201
+.. code-block:: console
310 202
 
311
-~~~~~~~~
312
-Protocol
313
-~~~~~~~~
203
+   $ openstack role add --group federated_users --project federated_project member
314 204
 
315
-A protocol contains information that dictates which Mapping rules to use for an incoming
316
-request made by an IdP. An IdP may have multiple supported protocols.
205
+Mappings can be quite complex. A detailed guide can be found on the
206
+:doc:`mapping_combinations` page.
207
+
208
+See also the `API reference on mapping rules`_.
209
+
210
+.. _API reference on mapping rules: https://developer.openstack.org/api-ref/identity/v3-ext/#mappings
211
+
212
+Create a Protocol
213
+~~~~~~~~~~~~~~~~~
214
+
215
+Now create a federation protocol. A federation protocol object links the
216
+Identity Provider to a mapping.
317 217
 
318 218
 You can create a protocol like this:
319 219
 
320 220
 .. code-block:: console
321 221
 
322
-   $ openstack federation protocol create saml2 --mapping samltest_mapping --identity-provider samltest
222
+   $ openstack federation protocol create saml2 \
223
+   --mapping samltest_mapping --identity-provider samltest
224
+
225
+As mentioned in :ref:`sp-prerequisites`, the name you give the protocol is not
226
+arbitrary, it must be a valid auth method.
323 227
 
324
-The name you give the protocol is not arbitrary. It must match the method name
325
-you gave in the ``[auth]/methods`` config option. When authenticating it will be
326
-referred to as the ``protocol_id``.
228
+See also the `API reference for federation protocols`_.
327 229
 
328
-Read more about `federation protocols
329
-<https://developer.openstack.org/api-ref/identity/v3-ext/#protocols>`__
230
+.. _API reference for federation protocols: https://developer.openstack.org/api-ref/identity/v3-ext/#protocols
231
+
232
+Configuring an HTTPD auth module
233
+--------------------------------
234
+
235
+This guide currently only includes examples for the Apache web server, but it
236
+possible to use SAML, OpenIDC, and other auth modules in other web servers. See
237
+the installation guides for running keystone behind Apache for `SUSE`_,
238
+`RedHat`_ or `Ubuntu`_.
239
+
240
+.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
241
+.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
242
+.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
243
+
244
+If your Identity Provider is a SAML IdP, there are two main Apache modules that
245
+can be used as a SAML Service Provider: `mod_shib` and `mod_auth_mellon`. For
246
+an OpenID Connect Identity Provider, `mod_auth_openidc` is used. You can also
247
+use other auth modules such as kerberos, X.509, or others. Check the
248
+documentation for the provider you choose for detailed installation and
249
+configuration guidance.
250
+
251
+Depending on the Service Provider module you've chosen, you will need to install
252
+the applicable Apache module package and follow additional configuration steps.
253
+This guide contains examples for two major federation protocols:
254
+
255
+* SAML2.0 - see guides for the following implementations:
256
+
257
+  * `Set up mod_shib`_.
258
+  * `Set up mod_auth_mellon`_.
259
+
260
+* OpenID Connect: `Set up mod_auth_openidc`_.
261
+
262
+.. _`Set up mod_shib`: shibboleth.html
263
+.. _`Set up mod_auth_openidc`: openidc.html
264
+.. _`Set up mod_auth_mellon`: mellon.html
265
+
266
+
267
+Configuring Keystone
268
+--------------------
269
+
270
+While the Apache module does the majority of the heavy lifting, minor changes
271
+are needed to allow keystone to allow and understand federated authentication.
272
+
273
+Add the Auth Method
274
+~~~~~~~~~~~~~~~~~~~
275
+
276
+Add the authentication methods to the ``[auth]`` section in ``keystone.conf``.
277
+The auth method here must have the same name as the protocol you created in
278
+`Create a Protocol`_. You should also remove ``external`` as an allowable
279
+method.
280
+
281
+.. code-block:: console
282
+
283
+   [auth]
284
+   methods = password,token,saml2,openid
285
+
286
+When finished configuring keystone, restart the keystone WSGI process or the web
287
+server:
288
+
289
+.. code-block:: console
290
+
291
+   # systemctl restart apache2
330 292
 
331 293
 Authenticating
332 294
 --------------
@@ -348,8 +310,8 @@ To use the CLI tool, you must have the name of the Identity Provider
348 310
 resource in keystone, the name of the federation protocol configured in
349 311
 keystone, and the ECP endpoint for the Identity Provider. If you are the cloud
350 312
 administrator, the name of the Identity Provider and protocol was configured in
351
-`Identity Provider`_ and `Protocol`_ respectively. If you are not the
352
-administrator, you must obtain this information from the administrator.
313
+`Create an Identity Provider`_ and `Create a Protocol`_ respectively. If you are
314
+not the administrator, you must obtain this information from the administrator.
353 315
 
354 316
 The ECP endpoint for the Identity Provider can be obtained from its metadata
355 317
 without involving an administrator. This endpoint is the

+ 5
- 3
doc/source/admin/federation/introduction.rst View File

@@ -76,9 +76,11 @@ Glossary
76 76
 **Entity ID or Remote ID**
77 77
   An Entity ID or a Remote ID are both names for a unique identifier string for
78 78
   either a Service Provider or an Identity Provider. It usually takes the form
79
-  of a URN, but the URN does not need to be a resolvable URL. The only
80
-  requirement is that it uniquely identifies the IdP to the SP, or the SP to the
81
-  IdP.
79
+  of a URN, but the URN does not need to be a resolvable URL. Remote IDs are
80
+  globally unique. Two Identity Providers cannot be associated with the same
81
+  remote ID. Keystone uses the remote ID retrieved from the HTTPD environment
82
+  variables to match the incoming request with a trusted Identity Provider and
83
+  render the appropriate authorization mapping.
82 84
 
83 85
 **SAML2.0**
84 86
   `SAML2.0`_ is an XML-based federation protocol. It is commonly used in

Loading…
Cancel
Save