Browse Source

Delete administrator federation guide

The federated-identity guide in the admin section is out of date
relative to the one in the operator section. It is sort of incoherent
and the information within it that is valuable is already present in the
other guide. Delete this guide in favor of just promoting the operator
guide.

Related-bug: #1793374

Change-Id: I8c0190725d0f7297957bbf10fd9d7184e52ff5f3
tags/15.0.0.0rc1
Colleen Murphy 8 months ago
parent
commit
914885fefd
2 changed files with 0 additions and 504 deletions
  1. 0
    503
      doc/source/admin/federated-identity.rst
  2. 0
    1
      doc/source/admin/index.rst

+ 0
- 503
doc/source/admin/federated-identity.rst View File

@@ -1,503 +0,0 @@
1
-==================
2
-Federated Identity
3
-==================
4
-
5
-You can use federation for the Identity service (keystone) in two ways:
6
-
7
-* Supporting keystone as a :abbr:`SP (Service Provider)`: consuming identity
8
-  assertions issued by an external Identity Provider, such as SAML
9
-  assertions or OpenID Connect claims.
10
-* Supporting keystone as an :abbr:`IdP (Identity Provider)`: fulfilling
11
-  authentication requests on behalf of Service Providers.
12
-
13
-  .. note::
14
-
15
-      It is also possible to have one keystone act as an SP that
16
-      consumes Identity from another keystone acting as an IdP.
17
-
18
-There is currently support for two major federation protocols:
19
-
20
-* `SAML <https://en.wikipedia.org/wiki/SAML_2.0>`_
21
-* `OpenID Connect <https://en.wikipedia.org/wiki/OpenID_Connect>`_
22
-
23
-.. figure:: figures/keystone-federation.png
24
-   :width: 100%
25
-
26
-   Keystone federation
27
-
28
-To enable federation:
29
-
30
-#. Run keystone under Apache. See `Configure the Apache HTTP server
31
-   <https://docs.openstack.org/ocata/install-guide-obs/keystone-install.html>`_
32
-   for more information.
33
-
34
-   .. note::
35
-
36
-      Other application servers, such as `nginx <https://www.nginx.com/resources/wiki>`_,
37
-      have support for federation extensions that may work but are not tested
38
-      by the community.
39
-
40
-#. Configure Apache to use a federation capable module.
41
-   We recommend Shibboleth, see :doc:`the Shibboleth documentation<../advanced-topics/federation/shibboleth>` for more information.
42
-
43
-   .. note::
44
-
45
-      Another option is ``mod_auth_melon``, see `the mod's github repo <https://github.com/UNINETT/mod_auth_mellon>`_
46
-      for more information.
47
-
48
-#. Configure federation in keystone.
49
-
50
-.. note::
51
-
52
-   The external IdP is responsible for authenticating users and communicates
53
-   the result of authentication to keystone using authentication assertions.
54
-   Keystone maps these values to keystone user groups and assignments
55
-   created in keystone.
56
-
57
-Supporting keystone as a SP
58
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
-
60
-To have keystone as an SP, you will need to configure
61
-keystone to accept assertions from external IdPs. Examples of external
62
-IdPs are:
63
-
64
-* :abbr:`ADFS (Active Directory Federation Services)`
65
-* FreeIPA
66
-* Tivoli Access Manager
67
-* Keystone
68
-
69
-Configuring federation in keystone
70
-----------------------------------
71
-
72
-#. Configure authentication drivers in ``keystone.conf`` by adding the
73
-   authentication methods to the ``[auth]`` section in ``keystone.conf``.
74
-   Ensure the names are the same as to the protocol names added via Identity
75
-   API v3.
76
-
77
-   For example:
78
-
79
-   .. code-block:: ini
80
-
81
-      [auth]
82
-      methods = external,password,token,saml2,openid
83
-
84
-   .. note::
85
-
86
-      ``saml2`` and ``openid`` are instances of the ``mapped`` plugin. These
87
-      must match the name of the of the federation protocol created via the
88
-      Identity API. The other names in the example are not related to
89
-      federation.
90
-
91
-#. Create local keystone groups and assign roles.
92
-
93
-   .. important::
94
-
95
-      The keystone requires group-based role assignments to authorize
96
-      federated users. The federation mapping engine maps federated users into
97
-      local user groups, which are the actors in keystone's role assignments.
98
-
99
-#. Create an IdP object in keystone. The object must represent the
100
-   IdP you will use to authenticate end users:
101
-
102
-   .. code:: ini
103
-
104
-      PUT /OS-FEDERATION/identity_providers/{idp_id}
105
-
106
-   More configuration information for IdPs can be found `Register an Identity Provider <https://developer.openstack.org/api-ref/identity/v3-ext/index.html#register-an-identity-provider>`_.
107
-
108
-#. Add mapping rules:
109
-
110
-   .. code:: ini
111
-
112
-      PUT /OS-FEDERATION/mappings/{mapping_id}
113
-
114
-   More configuration information for mapping rules can be found `Create a mapping <https://developer.openstack.org/api-ref/identity/v3-ext/index.html#create-a-mapping>`_.
115
-
116
-   .. note::
117
-
118
-       The only keystone API objects that support mapping are groups and users.
119
-
120
-#. Add a protocol object and specify the mapping ID you want to use with the
121
-   combination of the IdP and protocol:
122
-
123
-   .. code:: ini
124
-
125
-      PUT /OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
126
-
127
-   More configuration information for protocols can be found `Add a protocol and attribute mapping to an identity provider <https://developer.openstack.org/api-ref/identity/v3-ext/index.html#add-a-protocol-and-attribute-mapping-to-an-identity-provider>`_.
128
-
129
-Performing federated authentication
130
------------------------------------
131
-
132
-#. Authenticate externally and generate an unscoped token in keystone:
133
-
134
-   .. note::
135
-
136
-      Unlike other authentication methods in keystone, the user does
137
-      not issue an HTTP POST request with authentication data in the request body.
138
-      To start federated authentication a user must access the dedicated URL with
139
-      IdP's and protocol's identifiers stored within a protected URL.
140
-      The URL has a format of:
141
-      ``/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth``.
142
-
143
-   .. code:: ini
144
-
145
-      GET/POST /OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
146
-
147
-#. Determine accessible resources. By using the previously returned token, the
148
-   user can issue requests to the list projects and domains that are
149
-   accessible.
150
-
151
-   * List projects a federated user can access: GET /OS-FEDERATION/projects
152
-   * List domains a federated user can access: GET /OS-FEDERATION/domains
153
-
154
-   .. code:: ini
155
-
156
-      GET /OS-FEDERATION/projects
157
-
158
-#. Get a scoped token. A federated user can request a scoped token using
159
-   the unscoped token. A project or domain can be specified by either ID or
160
-   name. An ID is sufficient to uniquely identify a project or domain.
161
-
162
-   .. code:: ini
163
-
164
-      POST /auth/tokens
165
-
166
-Supporting keystone as an IdP
167
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168
-
169
-When acting as an IdP, the primary role of keystone is
170
-to issue assertions about users owned by keystone. This is done using PySAML2.
171
-
172
-Configuring federation in keystone
173
-----------------------------------
174
-
175
-There are certain settings in ``keystone.conf`` that must be set up, prior
176
-to attempting to federate multiple keystone deployments.
177
-
178
-#. Within ``keystone.conf``, assign values to the ``[saml]``
179
-   related fields, for example:
180
-
181
-   .. code:: ini
182
-
183
-      [saml]
184
-      certfile=/etc/keystone/ssl/certs/ca.pem
185
-      keyfile=/etc/keystone/ssl/private/cakey.pem
186
-      idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
187
-      idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
188
-      idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
189
-
190
-#. We recommend the following `Organization` configuration options.
191
-   Ensure these values contain not special characters that may cause
192
-   problems as part of a URL:
193
-
194
-   .. code:: ini
195
-
196
-      idp_organization_name=example_company
197
-      idp_organization_display_name=Example Corp.
198
-      idp_organization_url=example.com
199
-
200
-#. As with the `Organization` options, the `Contact` options are not
201
-   necessary, but it is advisable to set these values:
202
-
203
-   .. code:: ini
204
-
205
-      idp_contact_company=example_company
206
-      idp_contact_name=John
207
-      idp_contact_surname=Smith
208
-      idp_contact_email=jsmith@example.com
209
-      idp_contact_telephone=555-55-5555
210
-      idp_contact_type=technical
211
-
212
-Generate metadata
213
------------------
214
-
215
-Metadata must be exchanged to create a trust between the IdP and the SP.
216
-
217
-#. Create metadata for your keystone IdP, run the ``keystone-manage`` command
218
-   and pipe the output to a file. For example:
219
-
220
-   .. code:: console
221
-
222
-      $ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
223
-
224
-   .. note::
225
-
226
-      The file location must match the value of the ``idp_metadata_path``
227
-      configuration option assigned previously.
228
-
229
-Create a SP
230
------------
231
-
232
-To setup keystone-as-a-Service-Provider properly, you will need to
233
-understand what protocols are supported by external IdPs.
234
-For example, keystone as an SP can allow identities to federate in from a
235
-ADFS IdP but it must be configured to understand the SAML v2.0 protocol.
236
-ADFS issues assertions using SAML v2.0. Some examples
237
-of federated protocols include:
238
-
239
-* SAML v2.0
240
-* OpenID Connect
241
-
242
-The following instructions are an example of how you can configure
243
-keystone as an SP.
244
-
245
-#. Create a new SP with an ID of BETA.
246
-
247
-#. Create a ``sp_url`` of `<http://beta.example.com/Shibboleth.sso/SAML2/ECP>`_.
248
-
249
-#. Create a ``auth_url`` of `<http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth>`_.
250
-
251
-   .. note::
252
-
253
-      Use the ``sp_url`` when creating a SAML assertion for BETA and signed by
254
-      the current keystone IdP. Use the ``auth_url`` when retrieving the token
255
-      for BETA once the SAML assertion is sent.
256
-
257
-#. Set the ``enabled`` field to ``true``. It is set to
258
-   ``false`` by default.
259
-
260
-#. Your output should reflect the following example:
261
-
262
-   .. code:: console
263
-
264
-      $ curl -s -X PUT \
265
-     -H "X-Auth-Token: $OS_TOKEN" \
266
-     -H "Content-Type: application/json" \
267
-     -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}}' \
268
-     http://localhost:5000/v3/OS-FEDERATION/service_providers/BETA | python -mjson.tool
269
-
270
-keystone-to-keystone
271
-~~~~~~~~~~~~~~~~~~~~
272
-
273
-Keystone acting as an IdP is known as :abbr:`k2k (keystone-2-keystone)`
274
-or k2k federation, where a keystone somewhere is acting as the SP
275
-and another keystone is acting as the IdP. All IdPs issue
276
-assertions about the identities it owns using a `Protocol`.
277
-
278
-Mapping rules
279
-~~~~~~~~~~~~~
280
-
281
-Mapping adds a set of rules to map federation attributes to keystone users
282
-or groups. An IdP has exactly one mapping specified per protocol.
283
-
284
-A mapping is a translation between assertions provided from an IdP and
285
-the permission and roles applied by an SP. Given an assertion from an IdP, an
286
-SP applies a mapping to translate attributes from the
287
-IdP to known roles. A mapping is typically
288
-owned by an SP.
289
-
290
-Mapping objects can be used multiple times by different combinations
291
-of IdP and protocol.
292
-
293
-A rule hierarchy is as follows:
294
-
295
-.. code:: ini
296
-
297
-   {
298
-        "rules": [
299
-           {
300
-               "local": [
301
-                  {
302
-                       "<user> or <group>"
303
-                   }
304
-               ],
305
-               "remote": [
306
-                   {
307
-                       "<condition>"
308
-                   }
309
-               ]
310
-           }
311
-       ]
312
-   }
313
-
314
-* ``rules``: top-level list of rules.
315
-* ``local``: a rule containing information on what local attributes
316
-  will be mapped.
317
-* ``remote``: a rule containing information on what remote attributes will
318
-  be mapped.
319
-* ``condition``: contains information on conditions that allow a rule, can
320
-  only be set in a remote rule.
321
-
322
-For more information on mapping rules, see `Mapping Rules
323
-<https://docs.openstack.org/keystone/latest/advanced-topics/federation/federated_identity.html#mapping-rules>`_.
324
-
325
-Mapping creation
326
-----------------
327
-
328
-Mapping creation starts with the communication between the IdP and SP.
329
-The IdP usually provides a set of assertions that their users
330
-have in their assertion document. The SP will have to map
331
-those assertions to known groups and roles.
332
-For example:
333
-
334
-.. code:: ini
335
-
336
-   Identity Provider 1:
337
-     name: jsmith
338
-     groups: hacker
339
-     other: <assertion information>
340
-   The Service Provider may have 3 groups:
341
-     Admin Group
342
-     Developer Group
343
-     User Group
344
-
345
-   The mapping created by the Service Provider might look like:
346
-     Local:
347
-     Group: Developer Group
348
-   Remote:
349
-     Groups: hackers
350
-
351
-The ``Developer Group`` may have a role assignment on the
352
-``Developer Project``. When `jsmith` authenticates against IdP 1, it
353
-presents that assertion to the SP.The SP maps the `jsmith` user to the
354
-``Developer Group`` because the assertion says `jsmith` is a member of
355
-the ``hacker`` group.
356
-
357
-Mapping examples
358
-----------------
359
-
360
-A bare bones mapping is sufficient if you would like all federated users to
361
-have the same authorization in the SP cloud. However, mapping is
362
-quite powerful and flexible. You can map different remote
363
-users into different user groups in keystone, limited only by the number of
364
-assertions your IdP makes about each user.
365
-
366
-A mapping is composed of a list of rules, and each rule is further composed of
367
-a list of remote attributes and a list of local attributes. If a rule is
368
-matched, all of the local attributes are applied in the SP. For a
369
-rule to match, all of the remote attributes it defines must match.
370
-
371
-In the base case, a federated user simply needs an assertion containing
372
-an email address to be identified in the SP cloud. To achieve that, only
373
-one rule is needed that requires the presence of one remote attribute:
374
-
375
-.. code:: javascript
376
-
377
-    {
378
-        "rules": [
379
-            {
380
-                "remote": [
381
-                    {
382
-                        "type": "Email"
383
-                    }
384
-                ],
385
-                "local": [
386
-                    {
387
-                        "user": {
388
-                            "name": "{0}"
389
-                        }
390
-                    }
391
-                ]
392
-            }
393
-        ]
394
-    }
395
-
396
-However, that is not particularly useful as the federated user would receive no
397
-authorization. To rectify it, you can map all federated users with email
398
-addresses into a ``federated-users`` group in the ``default`` domain. All
399
-federated users will then be able to consume whatever role assignments that
400
-user group has already received in keystone:
401
-
402
-.. note::
403
-
404
-   In this example, there is only one rule requiring one remote attribute.
405
-
406
-.. code:: javascript
407
-
408
-    {
409
-        "rules": [
410
-            {
411
-                "remote": [
412
-                    {
413
-                        "type": "Email"
414
-                    }
415
-                ],
416
-                "local": [
417
-                    {
418
-                        "user": {
419
-                            "name": "{0}"
420
-                        }
421
-                    },
422
-                    {
423
-                        "group": {
424
-                            "domain": {
425
-                                "id": "0cd5e9"
426
-                            },
427
-                            "name": "federated-users"
428
-                        }
429
-                    }
430
-                ]
431
-            }
432
-        ]
433
-    }
434
-
435
-This example can be expanded by adding a second rule that conveys
436
-additional authorization to only a subset of federated users. Federated users
437
-with a `title` attribute that matches either ``Manager`` or ``Supervisor`` are
438
-admitted to the ``observers`` group which is granted the ``reader`` role on some
439
-project, which would allow the group members to perform any read-only API call
440
-in the project:
441
-
442
-.. code:: javascript
443
-
444
-    {
445
-        "rules": [
446
-            {
447
-                "remote": [
448
-                    {
449
-                        "type": "Email"
450
-                    },
451
-                ],
452
-                "local": [
453
-                    {
454
-                        "user": {
455
-                            "name": "{0}"
456
-                        }
457
-                    },
458
-                    {
459
-                        "group": {
460
-                            "domain": {
461
-                                "id": "default"
462
-                            },
463
-                            "name": "federated-users"
464
-                        }
465
-                    }
466
-                ]
467
-            },
468
-            {
469
-                "remote": [
470
-                    {
471
-                        "type": "Title",
472
-                        "any_one_of": [".*Manager$", "Supervisor"],
473
-                        "regex": "true"
474
-                    },
475
-                ],
476
-                "local": [
477
-                    {
478
-                        "group": {
479
-                            "domain": {
480
-                                "id": "default"
481
-                            },
482
-                            "name": "observers"
483
-                        }
484
-                    }
485
-                ]
486
-            }
487
-        ]
488
-    }
489
-
490
-.. note::
491
-
492
-   ``any_one_of`` and ``regex`` in the rule above map federated users into
493
-   the ``observers`` group when a user's ``Title`` assertion matches any of
494
-   the regular expressions specified in the ``any_one_of`` attribute.
495
-
496
-Keystone also supports the following:
497
-
498
-* ``not_any_of``, matches any assertion that does not include one of
499
-  the specified values
500
-* ``blacklist``, matches all assertions of the specified type except
501
-  those included in the specified value
502
-* ``whitelist`` does not match any assertion except those listed in the
503
-  specified value.

+ 0
- 1
doc/source/admin/index.rst View File

@@ -38,7 +38,6 @@ command-line client.
38 38
    identity-troubleshoot.rst
39 39
    identity-unified-limits.rst
40 40
    token-provider.rst
41
-   federated-identity.rst
42 41
    identity-credential-encryption.rst
43 42
    endpoint-filtering.rst
44 43
    health-check-middleware.rst

Loading…
Cancel
Save