From 40e0f5d976d6b5172a408bdd548937e24361db35 Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Fri, 21 Dec 2018 10:50:35 -0800 Subject: [PATCH] Bring SP/IdP URLs closer to style guide guidance The documentation style guide recommends using example URLs for OpenStack services that look like `http://.openstack.example.org`. This patch changes the URLs for hypothetical keystone Service Providers to use HTTPS endpoints to set a good example of security, to use the example.org domain instead of localhost or example.com, to include keystone in the name for clarity of what the service is, and to use a consistent URL path and port. It doesn't include 'openstack' in the domain name because that becomes a bit long. [1] https://docs.openstack.org/doc-contrib-guide/writing-style/urls.html Partial-bug: #1793374 Change-Id: I8e12edaa589be3c8e71b10d0609c057fd2bfb247 --- .../admin/federation/configure_federation.rst | 38 ++++++++++++++----- doc/source/admin/federation/mellon.rst | 12 +++--- doc/source/admin/federation/openidc.rst | 2 +- doc/source/admin/federation/shibboleth.rst | 6 +-- doc/source/admin/federation/websso.rst | 4 +- 5 files changed, 41 insertions(+), 21 deletions(-) diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst index 3055720818..9f495036b8 100644 --- a/doc/source/admin/federation/configure_federation.rst +++ b/doc/source/admin/federation/configure_federation.rst @@ -46,6 +46,15 @@ To enable federation, you'll need to: 2. `Configure Apache to use a federation capable authentication method`_. 3. `Configure Federation in Keystone`_. +.. note:: + + In this guide, the keystone Service Provider is configured on a host called + sp.keystone.example.org listening on the standard HTTPS port. All keystone + paths will start with the keystone version prefix, ``/v3``. If you have + configured keystone to listen on port 5000, or to respond on the path + ``/identity`` (for example), take this into account in your own + configuration. + .. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server @@ -349,7 +358,7 @@ SAML authentication procedure. .. code-block:: bash - $ curl -X GET -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth + $ curl -X GET -D - https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth Determine accessible resources ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -371,7 +380,7 @@ Example $ export OS_IDENTITY_API_VERSION=3 $ export OS_TOKEN= - $ export OS_URL=http://localhost:5000/v3 + $ export OS_URL=https://sp.keystone.example.org/v3 $ openstack federation project list or @@ -380,7 +389,7 @@ or $ export OS_IDENTITY_API_VERSION=3 $ export OS_TOKEN= - $ export OS_URL=http://localhost:5000/v3 + $ export OS_URL=https://sp.keystone.example.org/v3 $ openstack federation domain list Get a scoped token @@ -402,7 +411,7 @@ Example $ export OS_AUTH_TYPE=token $ export OS_IDENTITY_API_VERSION=3 $ export OS_TOKEN= - $ export OS_AUTH_URL=http://localhost:5000/v3 + $ export OS_AUTH_URL=https://sp.keystone.example.org/v3 $ export OS_PROJECT_DOMAIN_NAME=federated_domain $ export OS_PROJECT_NAME=federated_project $ openstack token issue @@ -428,6 +437,15 @@ Keystone as an Identity Provider (IdP) $ apt-get install xmlsec1 +.. note:: + + In this guide, the keystone Identity Provider is configured on a host called + idp.keystone.example.org listening on the standard HTTPS port. All keystone + paths will start with the keystone version prefix, ``/v3``. If you have + configured keystone to listen on port 5000, or to respond on the path + ``/identity`` (for example), take this into account in your own + configuration. + Configuration Options --------------------- @@ -440,8 +458,8 @@ example: .. code-block:: ini [saml] - idp_entity_id=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp - idp_sso_endpoint=https://myidp.example.com/v3/OS-FEDERATION/saml2/sso + 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_entity_id`` is the unique identifier for the Identity Provider. It usually takes the form of a URI but it does not have to resolve to anything. @@ -510,8 +528,8 @@ Create a Service Provider (SP) ------------------------------ In this example we are creating a new Service Provider with an ID of ``mysp``, -a ``sp_url`` of ``http://mysp.example.com/Shibboleth.sso/SAML2/ECP`` and a -``auth_url`` of ``http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth`` +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/myidp/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. The auth_url has the format @@ -519,7 +537,9 @@ described in `Get an unscoped token`_. .. code-block:: bash - $ openstack service provider create --service-provider-url 'http://mysp.example.com/Shibboleth.sso/SAML2/ECP' --auth-url http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth mysp + $ openstack service provider create \ + --service-provider-url 'https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP' \ + --auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth mysp Testing it all out ------------------ diff --git a/doc/source/admin/federation/mellon.rst b/doc/source/admin/federation/mellon.rst index bf60f465bc..63329b275d 100644 --- a/doc/source/admin/federation/mellon.rst +++ b/doc/source/admin/federation/mellon.rst @@ -45,9 +45,9 @@ a ** directive for each identity provider MellonEnable "info" - MellonSPPrivateKeyFile /etc/apache2/mellon/http_keystone.fqdn.key - MellonSPCertFile /etc/apache2/mellon/http_keystone.fqdn.cert - MellonSPMetadataFile /etc/apache2/mellon/http_keystone.fqdn.xml + MellonSPPrivateKeyFile /etc/apache2/mellon/sp.keystone.example.org.key + MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert + MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml MellonEndpointPath /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon MellonIdP "IDP" @@ -82,8 +82,8 @@ the values for the config directives `MellonSPPrivateKeyFile`, .. code-block:: bash - $ ./mellon_create_metadata.sh http://keystone.fqdn:5000 \ - http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon + $ ./mellon_create_metadata.sh https://sp.keystone.example.org/mellon\ + https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon The first parameter is used as the entity ID, a unique identifier for this Keystone SP. You do not have to use the URL, but it is an easy way to uniquely @@ -110,7 +110,7 @@ by the `MellonIdPMetadataFile` directive above. For example: .. code-block:: bash $ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \ - https://idp.fqdn/idp/saml2/metadata + https://myidp.example.com/idp/saml2/metadata Once you are done, restart the Apache instance that is serving Keystone, for example: diff --git a/doc/source/admin/federation/openidc.rst b/doc/source/admin/federation/openidc.rst index 32ea749da7..fdab1b74b8 100644 --- a/doc/source/admin/federation/openidc.rst +++ b/doc/source/admin/federation/openidc.rst @@ -53,7 +53,7 @@ entries for OpenID Connect: OIDCClientID OIDCClientSecret OIDCCryptoPassphrase openstack - OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers//protocols/openid/auth + OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers//protocols/openid/auth AuthType openid-connect diff --git a/doc/source/admin/federation/shibboleth.rst b/doc/source/admin/federation/shibboleth.rst index 45c6bdb520..3c9204912b 100644 --- a/doc/source/admin/federation/shibboleth.rst +++ b/doc/source/admin/federation/shibboleth.rst @@ -101,7 +101,7 @@ file. You will want to change five settings: .. code-block:: xml - + * Set the IdP entity ID. This value is determined by the IdP. For example, if Keystone is the IdP: @@ -160,7 +160,7 @@ to be used in a production environment): --> - +