Browse Source

Enhance authn sections in federation guide

Modernize the examples on using the CLI to authenticate with an external
IdP or keystone IdP, add tips on how to get needed information, and add
examples on authenticating with horizon.

Partial-bug: #1793374

Change-Id: Ieec899a1551be69da232196c59b9aeed0e85f5f5
tags/15.0.0.0rc1
Colleen Murphy 6 months ago
parent
commit
fc3dcc8071

BIN
doc/source/_static/horizon-login-idp.png View File


BIN
doc/source/_static/horizon-login-sp.png View File


+ 91
- 95
doc/source/admin/federation/configure_federation.rst View File

@@ -328,109 +328,90 @@ referred to as the ``protocol_id``.
328 328
 Read more about `federation protocols
329 329
 <https://developer.openstack.org/api-ref/identity/v3-ext/#protocols>`__
330 330
 
331
-Performing federated authentication
332
------------------------------------
333
-
334
-.. NOTE::
335
-
336
-    Authentication with keystone-to-keystone federation does not follow these steps.
337
-    See `Testing it all out`_ to authenticate with keystone-to-keystone.
331
+Authenticating
332
+--------------
338 333
 
339
-1. Authenticate externally and generate an unscoped token in keystone
340
-2. Determine accessible resources
341
-3. Get a scoped token
334
+Use the CLI to authenticate with a SAML2.0 Identity Provider
335
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
342 336
 
343
-Get an unscoped token
344
-~~~~~~~~~~~~~~~~~~~~~
345
-
346
-Unlike other authentication methods in the Identity Service, the user does not
347
-issue an HTTP POST request with authentication data in the request body. To
348
-start federated authentication a user must access the dedicated URL with
349
-Identity Provider's and Protocol's identifiers stored within a protected URL.
350
-The URL has a format of:
351
-``/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth``.
337
+.. FIXME(cmurphy): Include examples for OpenID Connect authentication with the CLI
352 338
 
353
-In this instance we follow a standard SAML2 authentication procedure, that is,
354
-the user will be redirected to the Identity Provider's authentication webpage
355
-and be prompted for credentials. After successfully authenticating the user
356
-will be redirected to the Service Provider's endpoint. If using a web browser,
357
-a token will be returned in JSON format, with the ID in the X-Subject-Token
358
-header.
339
+The ``python-openstackclient`` can be used to authenticate a federated user in a
340
+SAML Identity Provider to keystone.
359 341
 
360
-In the returned unscoped token, a list of Identity Service groups the user
361
-belongs to will be included.
342
+.. note::
362 343
 
363
-Read more about `getting an unscoped token
364
-<https://developer.openstack.org/api-ref/identity/v3-ext/#request-an-unscoped-os-federation-token>`__.
344
+   The SAML Identity Provider must be configured to support the ECP
345
+   authentication profile.
365 346
 
366
-~~~~~~~~~~~~
367
-Example cURL
368
-~~~~~~~~~~~~
347
+To use the CLI tool, you must have the name of the Identity Provider
348
+resource in keystone, the name of the federation protocol configured in
349
+keystone, and the ECP endpoint for the Identity Provider. If you are the cloud
350
+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.
369 353
 
370
-Note that the request does not include a body. The following url would be
371
-considered protected by ``mod_shib`` and Apache, as such a request made
372
-to the URL would be redirected to the Identity Provider, to start the
373
-SAML authentication procedure.
354
+The ECP endpoint for the Identity Provider can be obtained from its metadata
355
+without involving an administrator. This endpoint is the
356
+``urn:oasis:names:tc:SAML:2.0:bindings:SOAP`` binding in the metadata document:
374 357
 
375 358
 .. code-block:: console
376 359
 
377
-   $ curl -X GET -D - https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth
378
-
379
-Determine accessible resources
380
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
360
+   $ curl -s https://samltest.id/saml/idp | grep urn:oasis:names:tc:SAML:2.0:bindings:SOAP
361
+        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://samltest.id/idp/profile/SAML2/SOAP/ECP"/>
381 362
 
382
-By using the previously returned token, the user can issue requests to the list
383
-projects and domains that are accessible.
384
-
385
-* List projects a federated user can access: ``GET /OS-FEDERATION/projects``
386
-* List domains a federated user can access: ``GET /OS-FEDERATION/domains``
387
-
388
-Read more about `listing resources
389
-<https://developer.openstack.org/api-ref/identity/v3-ext/#list-projects-a-federated-user-can-access>`__.
390
-
391
-~~~~~~~
392
-Example
393
-~~~~~~~
394
-
395
-.. code-block:: console
396
-
397
-   $ export OS_IDENTITY_API_VERSION=3
398
-   $ export OS_TOKEN=<unscoped token>
399
-   $ export OS_URL=https://sp.keystone.example.org/v3
400
-   $ openstack federation project list
363
+~~~~~~~~~~~~~~~~~~~~~
364
+Find available scopes
365
+~~~~~~~~~~~~~~~~~~~~~
401 366
 
402
-or
367
+If you are a new user and are not aware of what resources you have access to,
368
+you can use an unscoped query to list the projects or domains you have been
369
+granted a role assignment on:
403 370
 
404
-.. code-block:: console
371
+.. code-block:: bash
405 372
 
406
-   $ export OS_IDENTITY_API_VERSION=3
407
-   $ export OS_TOKEN=<unscoped token>
408
-   $ export OS_URL=https://sp.keystone.example.org/v3
409
-   $ openstack federation domain list
373
+   export OS_AUTH_TYPE=v3samlpassword
374
+   export OS_IDENTITY_PROVIDER=samltest
375
+   export OS_IDENTITY_PROVIDER_URL=https://samltest.id/idp/profile/SAML2/SOAP/ECP
376
+   export OS_PROTOCOL=saml2
377
+   export OS_USERNAME=morty
378
+   export OS_PASSWORD=panic
379
+   export OS_AUTH_URL=https://sp.keystone.example.org/v3
380
+   export OS_IDENTITY_API_VERSION=3
381
+   openstack federation project list
382
+   openstack federation domain list
410 383
 
384
+~~~~~~~~~~~~~~~~~~
411 385
 Get a scoped token
412 386
 ~~~~~~~~~~~~~~~~~~
413 387
 
414
-A federated user may request a scoped token, by using the unscoped token. A
415
-project or domain may be specified by either ``id`` or ``name``. An ``id`` is
416
-sufficient to uniquely identify a project or domain.
388
+If you already know the project, domain or system you wish to scope to, you can
389
+directly request a scoped token:
417 390
 
418
-Read more about `getting a scoped token
419
-<https://developer.openstack.org/api-ref/identity/v3-ext/#request-a-scoped-os-federation-token>`__.
391
+.. code-block:: bash
420 392
 
421
-~~~~~~~
422
-Example
423
-~~~~~~~
393
+   export OS_AUTH_TYPE=v3samlpassword
394
+   export OS_IDENTITY_PROVIDER=samltest
395
+   export OS_IDENTITY_PROVIDER_URL=https://samltest.id/idp/profile/SAML2/SOAP/ECP
396
+   export OS_PROTOCOL=saml2
397
+   export OS_USERNAME=morty
398
+   export OS_PASSWORD=panic
399
+   export OS_AUTH_URL=https://sp.keystone.example.org/v3
400
+   export OS_IDENTITY_API_VERSION=3
401
+   export OS_PROJECT_NAME=federated_project
402
+   export OS_PROJECT_DOMAIN_NAME=Default
403
+   openstack token issue
424 404
 
425
-.. code-block:: console
405
+Use horizon to authenticate with an external Identity Provider
406
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
407
+
408
+When horizon is configured to enable WebSSO, a dropdown menu will appear on the
409
+login screen before the user has authenticated. Select an authentication method
410
+from the menu to be redirected to your Identity Provider for authentication.
426 411
 
427
-   $ export OS_AUTH_TYPE=token
428
-   $ export OS_IDENTITY_API_VERSION=3
429
-   $ export OS_TOKEN=<unscoped token>
430
-   $ export OS_AUTH_URL=https://sp.keystone.example.org/v3
431
-   $ export OS_PROJECT_DOMAIN_NAME=federated_domain
432
-   $ export OS_PROJECT_NAME=federated_project
433
-   $ openstack token issue
412
+.. image:: ../../_static/horizon-login-sp.png
413
+   :height: 400px
414
+   :alt: Horizon login screen using external authentication
434 415
 
435 416
 --------------------------------------
436 417
 Keystone as an Identity Provider (IdP)
@@ -555,8 +536,7 @@ a ``sp_url`` of ``https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP`` and
555 536
 ``auth_url`` of ``https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth``
556 537
 . The ``sp_url`` will be used when creating a SAML assertion for ``mysp`` and
557 538
 signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
558
-token for ``mysp`` once the SAML assertion is sent. The auth_url has the format
559
-described in `Get an unscoped token`_.
539
+token for ``mysp`` once the SAML assertion is sent.
560 540
 
561 541
 .. code-block:: console
562 542
 
@@ -564,24 +544,40 @@ described in `Get an unscoped token`_.
564 544
    --service-provider-url 'https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP' \
565 545
    --auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth mysp
566 546
 
567
-Testing it all out
568
-------------------
547
+Authenticating
548
+--------------
549
+
550
+Use the CLI to authenticate with Keystone-to-Keystone
551
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
569 552
 
570 553
 Use ``python-openstackclient`` to authenticate with the IdP and then get a
571 554
 scoped token from the SP.
572 555
 
573
-.. NOTE::
574
-    ECP stands for Enhanced Client or Proxy, an extension from the SAML2
575
-    protocol used in non-browser interfaces, like in the following example.
576
-
577 556
 .. code-block:: console
578 557
 
579
-   $ openstack \
580
-   --os-service-provider mysp \
581
-   --os-remote-project-name federated_project \
582
-   --os-remote-project-domain-name federated_domain \
583
-   token issue
584
-
558
+   export OS_USERNAME=demo
559
+   export OS_PASSWORD=nomoresecret
560
+   export OS_AUTH_URL=https://idp.keystone.example.org/v3
561
+   export OS_IDENTITY_API_VERSION=3
562
+   export OS_PROJECT_NAME=federated_project
563
+   export OS_PROJECT_DOMAIN_NAME=Default
564
+   export OS_SERVICE_PROVIDER=keystonesp
565
+   export OS_REMOTE_PROJECT_NAME=federated_project
566
+   export OS_REMOTE_PROJECT_DOMAIN_NAME=Default
567
+   openstack token issue
568
+
569
+Use Horizon to switch clouds
570
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
571
+
572
+No additional configuration is necessary to enable horizon for
573
+Keystone to Keystone. Log into the horizon instance for the Identity Provider
574
+using your regular local keystone credentials. Once logged in, you will see a
575
+Service Provider dropdown menu which you can use to switch your dashboard view
576
+to another cloud.
577
+
578
+.. image:: ../../_static/horizon-login-idp.png
579
+   :height: 175px
580
+   :alt: Horizon dropdown menu for switching between keystone providers
585 581
 
586 582
 .. include:: openidc.rst
587 583
 .. include:: mellon.rst

Loading…
Cancel
Save