Browse Source

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
tags/15.0.0.0rc1
Colleen Murphy 5 months ago
parent
commit
40e0f5d976

+ 29
- 9
doc/source/admin/federation/configure_federation.rst View File

@@ -46,6 +46,15 @@ To enable federation, you'll need to:
46 46
 2. `Configure Apache to use a federation capable authentication method`_.
47 47
 3. `Configure Federation in Keystone`_.
48 48
 
49
+.. note::
50
+
51
+   In this guide, the keystone Service Provider is configured on a host called
52
+   sp.keystone.example.org listening on the standard HTTPS port. All keystone
53
+   paths will start with the keystone version prefix, ``/v3``. If you have
54
+   configured keystone to listen on port 5000, or to respond on the path
55
+   ``/identity`` (for example), take this into account in your own
56
+   configuration.
57
+
49 58
 .. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
50 59
 .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
51 60
 .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
@@ -349,7 +358,7 @@ SAML authentication procedure.
349 358
 
350 359
 .. code-block:: bash
351 360
 
352
-    $ curl -X GET -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth
361
+    $ curl -X GET -D - https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth
353 362
 
354 363
 Determine accessible resources
355 364
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -371,7 +380,7 @@ Example
371 380
 
372 381
     $ export OS_IDENTITY_API_VERSION=3
373 382
     $ export OS_TOKEN=<unscoped token>
374
-    $ export OS_URL=http://localhost:5000/v3
383
+    $ export OS_URL=https://sp.keystone.example.org/v3
375 384
     $ openstack federation project list
376 385
 
377 386
 or
@@ -380,7 +389,7 @@ or
380 389
 
381 390
     $ export OS_IDENTITY_API_VERSION=3
382 391
     $ export OS_TOKEN=<unscoped token>
383
-    $ export OS_URL=http://localhost:5000/v3
392
+    $ export OS_URL=https://sp.keystone.example.org/v3
384 393
     $ openstack federation domain list
385 394
 
386 395
 Get a scoped token
@@ -402,7 +411,7 @@ Example
402 411
     $ export OS_AUTH_TYPE=token
403 412
     $ export OS_IDENTITY_API_VERSION=3
404 413
     $ export OS_TOKEN=<unscoped token>
405
-    $ export OS_AUTH_URL=http://localhost:5000/v3
414
+    $ export OS_AUTH_URL=https://sp.keystone.example.org/v3
406 415
     $ export OS_PROJECT_DOMAIN_NAME=federated_domain
407 416
     $ export OS_PROJECT_NAME=federated_project
408 417
     $ openstack token issue
@@ -428,6 +437,15 @@ Keystone as an Identity Provider (IdP)
428 437
 
429 438
             $ apt-get install xmlsec1
430 439
 
440
+.. note::
441
+
442
+   In this guide, the keystone Identity Provider is configured on a host called
443
+   idp.keystone.example.org listening on the standard HTTPS port. All keystone
444
+   paths will start with the keystone version prefix, ``/v3``. If you have
445
+   configured keystone to listen on port 5000, or to respond on the path
446
+   ``/identity`` (for example), take this into account in your own
447
+   configuration.
448
+
431 449
 Configuration Options
432 450
 ---------------------
433 451
 
@@ -440,8 +458,8 @@ example:
440 458
 .. code-block:: ini
441 459
 
442 460
     [saml]
443
-    idp_entity_id=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp
444
-    idp_sso_endpoint=https://myidp.example.com/v3/OS-FEDERATION/saml2/sso
461
+    idp_entity_id=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/idp
462
+    idp_sso_endpoint=https://idp.keystone.example.org/v3/OS-FEDERATION/saml2/sso
445 463
 
446 464
 ``idp_entity_id`` is the unique identifier for the Identity Provider. It
447 465
 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)
510 528
 ------------------------------
511 529
 
512 530
 In this example we are creating a new Service Provider with an ID of ``mysp``,
513
-a ``sp_url`` of ``http://mysp.example.com/Shibboleth.sso/SAML2/ECP`` and a
514
-``auth_url`` of ``http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth``
531
+a ``sp_url`` of ``https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP`` and a
532
+``auth_url`` of ``https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth``
515 533
 . The ``sp_url`` will be used when creating a SAML assertion for ``mysp`` and
516 534
 signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
517 535
 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`_.
519 537
 
520 538
 .. code-block:: bash
521 539
 
522
-    $ 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
540
+    $ openstack service provider create \
541
+    --service-provider-url 'https://sp.keystone.example.org/Shibboleth.sso/SAML2/ECP' \
542
+    --auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth mysp
523 543
 
524 544
 Testing it all out
525 545
 ------------------

+ 6
- 6
doc/source/admin/federation/mellon.rst View File

@@ -45,9 +45,9 @@ a *<Location>* directive for each identity provider
45 45
 
46 46
     <Location /v3>
47 47
         MellonEnable "info"
48
-        MellonSPPrivateKeyFile /etc/apache2/mellon/http_keystone.fqdn.key
49
-        MellonSPCertFile /etc/apache2/mellon/http_keystone.fqdn.cert
50
-        MellonSPMetadataFile /etc/apache2/mellon/http_keystone.fqdn.xml
48
+        MellonSPPrivateKeyFile /etc/apache2/mellon/sp.keystone.example.org.key
49
+        MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert
50
+        MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml
51 51
         MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
52 52
         MellonEndpointPath /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
53 53
         MellonIdP "IDP"
@@ -82,8 +82,8 @@ the values for the config directives `MellonSPPrivateKeyFile`,
82 82
 
83 83
 .. code-block:: bash
84 84
 
85
-    $ ./mellon_create_metadata.sh http://keystone.fqdn:5000 \
86
-      http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
85
+    $ ./mellon_create_metadata.sh  https://sp.keystone.example.org/mellon\
86
+      https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
87 87
 
88 88
 The first parameter is used as the entity ID, a unique identifier for this
89 89
 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:
110 110
 .. code-block:: bash
111 111
 
112 112
     $ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \
113
-      https://idp.fqdn/idp/saml2/metadata
113
+      https://myidp.example.com/idp/saml2/metadata
114 114
 
115 115
 Once you are done, restart the Apache instance that is serving Keystone, for example:
116 116
 

+ 1
- 1
doc/source/admin/federation/openidc.rst View File

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

+ 3
- 3
doc/source/admin/federation/shibboleth.rst View File

@@ -101,7 +101,7 @@ file. You will want to change five settings:
101 101
 
102 102
 .. code-block:: xml
103 103
 
104
-    <ApplicationDefaults entityID="http://mysp.example.com/shibboleth">
104
+    <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
105 105
 
106 106
 * Set the IdP entity ID. This value is determined by the IdP. For example, if
107 107
   Keystone is the IdP:
@@ -160,7 +160,7 @@ to be used in a production environment):
160 160
         -->
161 161
 
162 162
         <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
163
-        <ApplicationDefaults entityID="https://mysp.example.com/shibboleth">
163
+        <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
164 164
 
165 165
             <!--
166 166
             Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
@@ -284,7 +284,7 @@ fetch it with:
284 284
 
285 285
 .. code-block:: bash
286 286
 
287
-    $ wget http://mysp.example.com/Shibboleth.sso/Metadata
287
+    $ wget https://sp.keystone.example.org/Shibboleth.sso/Metadata
288 288
 
289 289
 This step depends on your Identity Provider choice and is not covered here.
290 290
 If keystone is your Identity Provider you do not need to upload this file.

+ 2
- 2
doc/source/admin/federation/websso.rst View File

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

Loading…
Cancel
Save