Browse Source

Clean up keystone-to-keystone section

Clean up the wording and add clarifications and examples to the guide on
configuring keystone as an IdP.

Partial-bug: #1793374

Change-Id: I5feee2da6b8b8f15e1de2e2f1ba493f31babb35f
tags/15.0.0.0rc1
Colleen Murphy 6 months ago
parent
commit
3d6930e171
1 changed files with 58 additions and 52 deletions
  1. 58
    52
      doc/source/admin/federation/configure_federation.rst

+ 58
- 52
doc/source/admin/federation/configure_federation.rst View File

@@ -450,14 +450,17 @@ packaging system (for instance apt or yum)
450 450
    ``/identity`` (for example), take this into account in your own
451 451
    configuration.
452 452
 
453
-Configuration Options
454
----------------------
453
+Configuring Metadata
454
+--------------------
455 455
 
456
-There are certain settings in ``keystone.conf`` that must be setup, prior to
457
-attempting to federate multiple keystone deployments.
456
+Since keystone is acting as a SAML Identity Provider, its metadata must be
457
+configured in the ``[saml]`` section of ``keystone.conf`` so that it can served
458
+by the `metadata API`_.
458 459
 
459
-Within ``keystone.conf``, assign values to the ``[saml]`` related fields, for
460
-example:
460
+.. _metadata API: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#retrieve-metadata-properties
461
+
462
+The two parameters that **must** be set in order for keystone to generate
463
+metadata are ``idp_entity_id`` and ``idp_sso_endpoint``:
461 464
 
462 465
 .. code-block:: ini
463 466
 
@@ -465,34 +468,24 @@ example:
465 468
    idp_entity_id=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/idp
466 469
    idp_sso_endpoint=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/sso
467 470
 
468
-``idp_entity_id`` is the unique identifier for the Identity Provider. It
469
-usually takes the form of a URI but it does not have to resolve to anything.
470
-``idp_sso_endpoint`` is required to generate valid metadata but its value is
471
-not important, though it may be in the future.
472
-
473
-Note the ``certfile``, ``keyfile``, and ``idp_metadata_path`` settings and adjust them if
474
-necessary:
475
-
476
-.. code-block:: ini
471
+``idp_entity_id`` sets the Identity Provider entity ID, which is a string of
472
+your choosing that uniquely identifies the Identity Provider to any Service
473
+Provider.
477 474
 
478
-   certfile=/etc/keystone/ssl/certs/signing_cert.pem
479
-   keyfile=/etc/keystone/ssl/private/signing_key.pem
480
-   idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
475
+``idp_sso_endpoint`` is required to generate valid metadata, but its value is
476
+currently not used because keystone as an Identity Provider does not support the
477
+SAML2.0 WebSSO auth profile. This may change in the future which is why there is
478
+no default value provided and must be set by the operator.
481 479
 
482
-Though not necessary, the follow Organization configuration options should
483
-also be setup. It is recommended that these values be URL safe.
480
+For completeness, the following Organization and Contact configuration options
481
+should also be updated to reflect your organization and administrator contact
482
+details.
484 483
 
485 484
 .. code-block:: ini
486 485
 
487 486
    idp_organization_name=example_company
488 487
    idp_organization_display_name=Example Corp.
489 488
    idp_organization_url=example.com
490
-
491
-As with the Organization options, the Contact options, are not necessary, but
492
-it's advisable to set these values too.
493
-
494
-.. code-block:: ini
495
-
496 489
    idp_contact_company=example_company
497 490
    idp_contact_name=John
498 491
    idp_contact_surname=Smith
@@ -500,20 +493,22 @@ it's advisable to set these values too.
500 493
    idp_contact_telephone=555-555-5555
501 494
    idp_contact_type=technical
502 495
 
503
-Generate Metadata
504
------------------
496
+It is important to take note of the default ``certfile`` and ``keyfile``
497
+options, and adjust them if necessary:
505 498
 
506
-In order to create a trust between the IdP and SP, metadata must be exchanged.
499
+.. code-block:: ini
507 500
 
508
-First, if you haven't already generated a PKI key pair, you need to do so and
509
-copy those files the locations designated by ``certfile`` and ``keyfile``
510
-options that were assigned in the previous section. Ensure that your apache
511
-vhost has SSL enabled and is using that keypair by adding the following to the
512
-vhost::
501
+   certfile=/etc/keystone/ssl/certs/signing_cert.pem
502
+   keyfile=/etc/keystone/ssl/private/signing_key.pem
513 503
 
514
-    SSLEngine on
515
-    SSLCertificateFile /etc/keystone/ssl/certs/signing_cert.pem
516
-    SSLCertificateKeyFile /etc/keystone/ssl/private/signing_key.pem
504
+You must generate a PKI key pair and copy the files to these paths. You can use
505
+the ``openssl`` tool to do so. Keystone does not provide a utility for this.
506
+
507
+Check the ``idp_metadata_path`` setting and adjust it if necessary:
508
+
509
+.. code-block:: ini
510
+
511
+   idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
517 512
 
518 513
 To create metadata for your keystone IdP, run the ``keystone-manage`` command
519 514
 and redirect the output to a file. For example:
@@ -522,27 +517,38 @@ and redirect the output to a file. For example:
522 517
 
523 518
    # keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
524 519
 
525
-.. NOTE::
526
-    The file location should match the value of the configuration option
527
-    ``idp_metadata_path`` that was assigned in the previous section.
520
+Finally, restart the keystone WSGI service or the web server frontend:
521
+
522
+.. code-block:: console
528 523
 
529
-Finally, restart apache.
524
+   # systemctl restart apache2
530 525
 
531
-Create a Service Provider (SP)
532
-------------------------------
526
+Creating a Service Provider Resource
527
+------------------------------------
533 528
 
534
-In this example we are creating a new Service Provider with an ID of ``mysp``,
535
-a ``sp_url`` of ``https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP`` and a
536
-``auth_url`` of ``https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth``
537
-. The ``sp_url`` will be used when creating a SAML assertion for ``mysp`` and
538
-signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
539
-token for ``mysp`` once the SAML assertion is sent.
529
+Create a Service Provider resource to represent your Service Provider as an
530
+object in keystone:
540 531
 
541 532
 .. code-block:: console
542 533
 
543
-   $ openstack service provider create \
544
-   --service-provider-url 'https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP' \
545
-   --auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth mysp
534
+   $ openstack service provider create keystonesp \
535
+   --service-provider-url https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP
536
+   --auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/keystoneidp/protocols/saml2/auth
537
+
538
+The ``--auth-url`` is the `federated auth endpoint`_ for a specific Identity
539
+Provider and protocol name, here named ``keystoneidp`` and ``saml2``.
540
+
541
+The ``--service-provider-url`` is the
542
+``urn:oasis:names:tc:SAML:2.0:bindings:PAOS`` binding for the Assertion Consumer
543
+Service of the Service Provider. It can be obtained from the Service Provider
544
+metadata:
545
+
546
+.. code-block:: console
547
+
548
+   $ curl -s https://sp.keystone.example.org/Shibboleth.sso/Metadata | grep urn:oasis:names:tc:SAML:2.0:bindings:PAOS
549
+   <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP" index="4"/>
550
+
551
+.. _federated auth endpoint: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#request-an-unscoped-os-federation-token
546 552
 
547 553
 Authenticating
548 554
 --------------

Loading…
Cancel
Save