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
This commit is contained in:
parent
fc3dcc8071
commit
3d6930e171
|
@ -450,14 +450,17 @@ packaging system (for instance apt or yum)
|
||||||
``/identity`` (for example), take this into account in your own
|
``/identity`` (for example), take this into account in your own
|
||||||
configuration.
|
configuration.
|
||||||
|
|
||||||
Configuration Options
|
Configuring Metadata
|
||||||
---------------------
|
--------------------
|
||||||
|
|
||||||
There are certain settings in ``keystone.conf`` that must be setup, prior to
|
Since keystone is acting as a SAML Identity Provider, its metadata must be
|
||||||
attempting to federate multiple keystone deployments.
|
configured in the ``[saml]`` section of ``keystone.conf`` so that it can served
|
||||||
|
by the `metadata API`_.
|
||||||
|
|
||||||
Within ``keystone.conf``, assign values to the ``[saml]`` related fields, for
|
.. _metadata API: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#retrieve-metadata-properties
|
||||||
example:
|
|
||||||
|
The two parameters that **must** be set in order for keystone to generate
|
||||||
|
metadata are ``idp_entity_id`` and ``idp_sso_endpoint``:
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
|
@ -465,34 +468,24 @@ example:
|
||||||
idp_entity_id=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/idp
|
idp_entity_id=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/idp
|
||||||
idp_sso_endpoint=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/sso
|
idp_sso_endpoint=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/sso
|
||||||
|
|
||||||
``idp_entity_id`` is the unique identifier for the Identity Provider. It
|
``idp_entity_id`` sets the Identity Provider entity ID, which is a string of
|
||||||
usually takes the form of a URI but it does not have to resolve to anything.
|
your choosing that uniquely identifies the Identity Provider to any Service
|
||||||
``idp_sso_endpoint`` is required to generate valid metadata but its value is
|
Provider.
|
||||||
not important, though it may be in the future.
|
|
||||||
|
|
||||||
Note the ``certfile``, ``keyfile``, and ``idp_metadata_path`` settings and adjust them if
|
``idp_sso_endpoint`` is required to generate valid metadata, but its value is
|
||||||
necessary:
|
currently not used because keystone as an Identity Provider does not support the
|
||||||
|
SAML2.0 WebSSO auth profile. This may change in the future which is why there is
|
||||||
|
no default value provided and must be set by the operator.
|
||||||
|
|
||||||
.. code-block:: ini
|
For completeness, the following Organization and Contact configuration options
|
||||||
|
should also be updated to reflect your organization and administrator contact
|
||||||
certfile=/etc/keystone/ssl/certs/signing_cert.pem
|
details.
|
||||||
keyfile=/etc/keystone/ssl/private/signing_key.pem
|
|
||||||
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
|
|
||||||
|
|
||||||
Though not necessary, the follow Organization configuration options should
|
|
||||||
also be setup. It is recommended that these values be URL safe.
|
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
idp_organization_name=example_company
|
idp_organization_name=example_company
|
||||||
idp_organization_display_name=Example Corp.
|
idp_organization_display_name=Example Corp.
|
||||||
idp_organization_url=example.com
|
idp_organization_url=example.com
|
||||||
|
|
||||||
As with the Organization options, the Contact options, are not necessary, but
|
|
||||||
it's advisable to set these values too.
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
idp_contact_company=example_company
|
idp_contact_company=example_company
|
||||||
idp_contact_name=John
|
idp_contact_name=John
|
||||||
idp_contact_surname=Smith
|
idp_contact_surname=Smith
|
||||||
|
@ -500,20 +493,22 @@ it's advisable to set these values too.
|
||||||
idp_contact_telephone=555-555-5555
|
idp_contact_telephone=555-555-5555
|
||||||
idp_contact_type=technical
|
idp_contact_type=technical
|
||||||
|
|
||||||
Generate Metadata
|
It is important to take note of the default ``certfile`` and ``keyfile``
|
||||||
-----------------
|
options, and adjust them if necessary:
|
||||||
|
|
||||||
In order to create a trust between the IdP and SP, metadata must be exchanged.
|
.. code-block:: ini
|
||||||
|
|
||||||
First, if you haven't already generated a PKI key pair, you need to do so and
|
certfile=/etc/keystone/ssl/certs/signing_cert.pem
|
||||||
copy those files the locations designated by ``certfile`` and ``keyfile``
|
keyfile=/etc/keystone/ssl/private/signing_key.pem
|
||||||
options that were assigned in the previous section. Ensure that your apache
|
|
||||||
vhost has SSL enabled and is using that keypair by adding the following to the
|
|
||||||
vhost::
|
|
||||||
|
|
||||||
SSLEngine on
|
You must generate a PKI key pair and copy the files to these paths. You can use
|
||||||
SSLCertificateFile /etc/keystone/ssl/certs/signing_cert.pem
|
the ``openssl`` tool to do so. Keystone does not provide a utility for this.
|
||||||
SSLCertificateKeyFile /etc/keystone/ssl/private/signing_key.pem
|
|
||||||
|
Check the ``idp_metadata_path`` setting and adjust it if necessary:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
|
||||||
|
|
||||||
To create metadata for your keystone IdP, run the ``keystone-manage`` command
|
To create metadata for your keystone IdP, run the ``keystone-manage`` command
|
||||||
and redirect the output to a file. For example:
|
and redirect the output to a file. For example:
|
||||||
|
@ -522,27 +517,38 @@ and redirect the output to a file. For example:
|
||||||
|
|
||||||
# keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
|
# keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
|
||||||
|
|
||||||
.. NOTE::
|
Finally, restart the keystone WSGI service or the web server frontend:
|
||||||
The file location should match the value of the configuration option
|
|
||||||
``idp_metadata_path`` that was assigned in the previous section.
|
|
||||||
|
|
||||||
Finally, restart apache.
|
|
||||||
|
|
||||||
Create a Service Provider (SP)
|
|
||||||
------------------------------
|
|
||||||
|
|
||||||
In this example we are creating a new Service Provider with an ID of ``mysp``,
|
|
||||||
a ``sp_url`` of ``https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP`` and a
|
|
||||||
``auth_url`` of ``https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth``
|
|
||||||
. The ``sp_url`` will be used when creating a SAML assertion for ``mysp`` and
|
|
||||||
signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
|
|
||||||
token for ``mysp`` once the SAML assertion is sent.
|
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
$ openstack service provider create \
|
# systemctl restart apache2
|
||||||
--service-provider-url 'https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP' \
|
|
||||||
--auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth mysp
|
Creating a Service Provider Resource
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
Create a Service Provider resource to represent your Service Provider as an
|
||||||
|
object in keystone:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ openstack service provider create keystonesp \
|
||||||
|
--service-provider-url https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP
|
||||||
|
--auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/keystoneidp/protocols/saml2/auth
|
||||||
|
|
||||||
|
The ``--auth-url`` is the `federated auth endpoint`_ for a specific Identity
|
||||||
|
Provider and protocol name, here named ``keystoneidp`` and ``saml2``.
|
||||||
|
|
||||||
|
The ``--service-provider-url`` is the
|
||||||
|
``urn:oasis:names:tc:SAML:2.0:bindings:PAOS`` binding for the Assertion Consumer
|
||||||
|
Service of the Service Provider. It can be obtained from the Service Provider
|
||||||
|
metadata:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ curl -s https://sp.keystone.example.org/Shibboleth.sso/Metadata | grep urn:oasis:names:tc:SAML:2.0:bindings:PAOS
|
||||||
|
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP" index="4"/>
|
||||||
|
|
||||||
|
.. _federated auth endpoint: https://developer.openstack.org/api-ref/identity/v3-ext/index.html#request-an-unscoped-os-federation-token
|
||||||
|
|
||||||
Authenticating
|
Authenticating
|
||||||
--------------
|
--------------
|
||||||
|
|
Loading…
Reference in New Issue