Bring SP/IdP URLs closer to style guide guidance

The documentation style guide recommends using example URLs for
OpenStack services that look like
`http://<service>.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

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=<unscoped 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=<unscoped 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=<unscoped 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_entity_id=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/idp
-    idp_sso_endpoint=https://myidp.example.com/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
 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
+a ``sp_url`` of ``https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP`` and a
-``auth_url`` of ``http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth``
+``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
 ------------------

doc/source/admin/federation/mellon.rst

@@ -45,9 +45,9 @@ a *<Location>* directive for each identity provider
 
     <Location /v3>
         MellonEnable "info"
-        MellonSPPrivateKeyFile /etc/apache2/mellon/http_keystone.fqdn.key
+        MellonSPPrivateKeyFile /etc/apache2/mellon/sp.keystone.example.org.key
-        MellonSPCertFile /etc/apache2/mellon/http_keystone.fqdn.cert
+        MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert
-        MellonSPMetadataFile /etc/apache2/mellon/http_keystone.fqdn.xml
+        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 \
+    $ ./mellon_create_metadata.sh  https://sp.keystone.example.org/mellon\
-      http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/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:
 

doc/source/admin/federation/openidc.rst

@@ -53,7 +53,7 @@ entries for OpenID Connect:
       OIDCClientID <openid_client_id>
       OIDCClientSecret <openid_client_secret>
       OIDCCryptoPassphrase openstack
-      OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/openid/auth
+      OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/openid/auth
 
       <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/openid/auth>
         AuthType openid-connect

doc/source/admin/federation/shibboleth.rst

@@ -101,7 +101,7 @@ file. You will want to change five settings:
 
 .. code-block:: xml
 
-    <ApplicationDefaults entityID="http://mysp.example.com/shibboleth">
+    <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
 
 * 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):
         -->
 
         <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
-        <ApplicationDefaults entityID="https://mysp.example.com/shibboleth">
+        <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
 
             <!--
             Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
@@ -284,7 +284,7 @@ fetch it with:
 
 .. code-block:: bash
 
-    $ wget http://mysp.example.com/Shibboleth.sso/Metadata
+    $ wget https://sp.keystone.example.org/Shibboleth.sso/Metadata
 
 This step depends on your Identity Provider choice and is not covered here.
 If keystone is your Identity Provider you do not need to upload this file.

doc/source/admin/federation/websso.rst

@@ -72,8 +72,8 @@ If `mod_auth_openidc` is used, then use the following as an example:
 
   <VirtualHost *:5000>
 
-      OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/websso
+      OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/websso
-      OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/websso
+      OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/websso
 
       ...