Browse Source

Use samltest.id as an example sandbox IdP

The federation documentation inconsistently references samltest.id
(formerly testshib.org, which is not well maintained) or a keystone IdP
(before keystone-to-keystone is introduced). This change switches the
examples to use samltest.id[1] and renames 'myidp' to 'samltest' where
appropriate. In the case of the WebSSO horizon configuration examples,
it's not appropriate to switch the openid examples to samltest because
samltest.id does not support OpenIDC. The examples are meant to show
that you can pair different protocols to a single IdP, so use 'acme' as
the example.

[1] https://samltest.id

Partial-bug: #1793374

Change-Id: I2633ba460182ed8ed5195a10cdaae663add8b1aa
tags/15.0.0.0rc1
Colleen Murphy 6 months ago
parent
commit
5cc61bb644

+ 17
- 7
doc/source/admin/federation/configure_federation.rst View File

@@ -36,6 +36,15 @@ responsible for authenticating users, and communicates the result of
36 36
 authentication to keystone using identity properties. Keystone maps these
37 37
 values to keystone user groups and assignments created in keystone.
38 38
 
39
+In this section, we will configure keystone as a Service Provider, consuming
40
+identity properties issued by an external Identity Provider, such as SAML
41
+assertions or OpenID Connect claims. For testing purposes, we recommend using
42
+`samltest.id`_  as a SAML Identity Provider, or Google as an OpenID Connect
43
+Identity Provider, and the examples here will references those providers. If you
44
+plan to set up `Keystone as an Identity Provider (IdP)`_, it is easiest to set
45
+up keystone with a dummy SAML provider first and then reconfigure it to point to
46
+the keystone Identity Provider later.
47
+
39 48
 The following configuration steps were performed on a machine running
40 49
 Ubuntu 14.04 and Apache 2.4.7.
41 50
 
@@ -55,6 +64,7 @@ To enable federation, you'll need to:
55 64
    ``/identity`` (for example), take this into account in your own
56 65
    configuration.
57 66
 
67
+.. _samltest.id: https://samltest.id
58 68
 .. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
59 69
 .. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
60 70
 .. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
@@ -168,7 +178,7 @@ Provider we will use to authenticate end users:
168 178
 
169 179
 .. code-block:: console
170 180
 
171
-   $ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp
181
+   $ openstack identity provider create --remote-id https://samltest.id/saml/idp samltest
172 182
 
173 183
 The value for the ``remote-id`` option is the unique identifier provided by the
174 184
 IdP. For a SAML IdP it can found as the EntityDescriptor entityID in the IdP's
@@ -176,7 +186,7 @@ provided metadata. If the IdP is a keystone IdP, it is the value set in that
176 186
 keystone's ``[saml]/idp_entity_id`` option. For an OpenID Connect IdP, it is
177 187
 the IdP's Issuer Identifier. It will usually appear as a URI but there is no
178 188
 requirement for it to resolve to anything and may be arbitrarily decided by the
179
-administrator of the IdP. The local name, here called 'myidp', is decided by
189
+administrator of the IdP. The local name, here called 'samltest', is decided by
180 190
 you and will be used by the mapping and protocol, and later for authentication.
181 191
 
182 192
 A keystone identity provider may have multiple `remote_ids` specified, this
@@ -257,7 +267,7 @@ users to the group you already created:
257 267
        }
258 268
    ]
259 269
    EOF
260
-   $ openstack mapping create --rules rules.json myidp_mapping
270
+   $ openstack mapping create --rules rules.json samltest_mapping
261 271
 
262 272
 As another example, if Shibboleth is your IdP, the remote section should use REMOTE_USER as the remote type:
263 273
 
@@ -287,7 +297,7 @@ As another example, if Shibboleth is your IdP, the remote section should use REM
287 297
        }
288 298
    ]
289 299
    EOF
290
-   $ openstack mapping create --rules rules.json myidp_mapping
300
+   $ openstack mapping create --rules rules.json samltest_mapping
291 301
 
292 302
 Read more about `mapping
293 303
 <https://developer.openstack.org/api-ref/identity/v3-ext/#mappings>`__.
@@ -303,7 +313,7 @@ You can create a protocol like this:
303 313
 
304 314
 .. code-block:: console
305 315
 
306
-   $ openstack federation protocol create saml2 --mapping myidp_mapping --identity-provider myidp
316
+   $ openstack federation protocol create saml2 --mapping samltest_mapping --identity-provider samltest
307 317
 
308 318
 The name you give the protocol is not arbitrary. It must match the method name
309 319
 you gave in the ``[auth]/methods`` config option. When authenticating it will be
@@ -529,7 +539,7 @@ Create a Service Provider (SP)
529 539
 
530 540
 In this example we are creating a new Service Provider with an ID of ``mysp``,
531 541
 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``
542
+``auth_url`` of ``https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth``
533 543
 . The ``sp_url`` will be used when creating a SAML assertion for ``mysp`` and
534 544
 signed by the current keystone IdP. The ``auth_url`` is used to retrieve the
535 545
 token for ``mysp`` once the SAML assertion is sent. The auth_url has the format
@@ -539,7 +549,7 @@ described in `Get an unscoped token`_.
539 549
 
540 550
    $ openstack service provider create \
541 551
    --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
552
+   --auth-url https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth mysp
543 553
 
544 554
 Testing it all out
545 555
 ------------------

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

@@ -49,11 +49,11 @@ a *<Location>* directive for each identity provider
49 49
        MellonSPCertFile /etc/apache2/mellon/sp.keystone.example.org.cert
50 50
        MellonSPMetadataFile /etc/apache2/mellon/sp-metadata.xml
51 51
        MellonIdPMetadataFile /etc/apache2/mellon/idp-metadata.xml
52
-       MellonEndpointPath /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth/mellon
52
+       MellonEndpointPath /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth/mellon
53 53
        MellonIdP "IDP"
54 54
    </Location>
55 55
 
56
-   <Location /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth>
56
+   <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
57 57
        AuthType "Mellon"
58 58
        MellonEnable "auth"
59 59
    </Location>
@@ -62,7 +62,7 @@ a *<Location>* directive for each identity provider
62 62
     * See below for information about how to generate the values for the
63 63
       `MellonSPMetadataFile`, etc. directives.
64 64
     * ``saml2`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_
65
-    * ``myidp`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
65
+    * ``samltest`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
66 66
     * You are advised to carefully examine `mod_auth_mellon Apache
67 67
       configuration documentation
68 68
       <https://github.com/UNINETT/mod_auth_mellon>`_
@@ -83,7 +83,7 @@ the values for the config directives `MellonSPPrivateKeyFile`,
83 83
 .. code-block:: console
84 84
 
85 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
86
+   https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers/samltest/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
@@ -109,8 +109,7 @@ by the `MellonIdPMetadataFile` directive above. For example:
109 109
 
110 110
 .. code-block:: console
111 111
 
112
-   $ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \
113
-   https://myidp.example.com/idp/saml2/metadata
112
+   $ wget -O /etc/apache2/mellon/idp-metadata.xml https://samltest.id/saml/idp
114 113
 
115 114
 Once you are done, restart the Apache instance that is serving Keystone, for example:
116 115
 

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

@@ -47,7 +47,7 @@ Shibboleth module and a *<Location>* directive for each identity provider
47 47
        SetHandler shib
48 48
    </Location>
49 49
 
50
-   <Location /v3/OS-FEDERATION/identity_providers/myidp/protocols/saml2/auth>
50
+   <Location /v3/OS-FEDERATION/identity_providers/samltest/protocols/saml2/auth>
51 51
        ShibRequestSetting requireSession 1
52 52
        AuthType shibboleth
53 53
        ShibExportAssertion Off
@@ -61,7 +61,7 @@ Shibboleth module and a *<Location>* directive for each identity provider
61 61
 
62 62
 .. NOTE::
63 63
     * ``saml2`` is the name of the `protocol that you will configure <configure_federation.html#protocol>`_
64
-    * ``myidp`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
64
+    * ``samltest`` is the name associated with the `IdP in Keystone <configure_federation.html#identity_provider>`_
65 65
     * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in
66 66
       Apache 2.4+.
67 67
     * You are advised to carefully examine `Shibboleth Apache configuration
@@ -105,14 +105,7 @@ file. You will want to change five settings:
105 105
 
106 106
    <ApplicationDefaults entityID="https://sp.keystone.example.org/shibboleth">
107 107
 
108
-* Set the IdP entity ID. This value is determined by the IdP. For example, if
109
-  Keystone is the IdP:
110
-
111
-.. code-block:: xml
112
-
113
-   <SSO entityID="https://myidp.example.com/v3/OS-FEDERATION/saml2/idp">
114
-
115
-Example if samltest.id is the IdP:
108
+* Set the entity ID of the Identity Provider:
116 109
 
117 110
 .. code-block:: xml
118 111
 
@@ -120,18 +113,20 @@ Example if samltest.id is the IdP:
120 113
 
121 114
 * Remove the discoveryURL lines unless you want to enable advanced IdP discovery.
122 115
 
123
-* Add a MetadataProvider block. The URI given here is a real URL that Shibboleth
124
-  will use to fetch metadata from the IdP. For example, if Keystone is the IdP:
116
+* Tell Shibboleth where to find the metadata of the Identity Provider. You could
117
+  either tell it to fetch it from a URI or point it to a local file. For
118
+  example, pointing to a local file:
125 119
 
126 120
 .. code-block:: xml
127 121
 
128
-   <MetadataProvider type="XML" uri="https://myidp.example.com:5000/v3/OS-FEDERATION/saml2/metadata"/>
122
+   <MetadataProvider type="XML" file="/etc/shibboleth/samltest-metadata.xml" />
129 123
 
130
-Example if samltest.id is the IdP:
124
+or pointing to a remote location:
131 125
 
132 126
 .. code-block:: xml
133 127
 
134
-   <MetadataProvider type="XML" uri="https://samltest.id/saml/idp" />
128
+   <MetadataProvider type="XML" url="https://samltest.id/saml/idp"
129
+       backingFile="samltest-metadata.xml" />
135 130
 
136 131
 You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_
137 132
 
@@ -182,7 +177,7 @@ to be used in a production environment):
182 177
                (Set discoveryProtocol to "WAYF" for legacy Shibboleth WAYF support.)
183 178
                You can also override entityID on /Login query string, or in RequestMap/htaccess.
184 179
                -->
185
-               <SSO entityID="https://myidp.example.com/v3/OS-FEDERATION/saml2/idp">
180
+               <SSO entityID="https://samltest.id/saml/idp">
186 181
                  SAML2 SAML1
187 182
                </SSO>
188 183
 
@@ -222,7 +217,7 @@ to be used in a production environment):
222 217
            <!--
223 218
            <MetadataProvider type="XML" file="partner-metadata.xml"/>
224 219
            -->
225
-           <MetadataProvider type="XML" uri="https://myidp.example.com:5000/v3/OS-FEDERATION/saml2/metadata"/>
220
+           <MetadataProvider type="XML" uri="https://samltest.id/saml/idp"/>
226 221
 
227 222
            <!-- Map to extract attributes from SAML assertions. -->
228 223
            <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>

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

@@ -60,7 +60,7 @@ If `mod_shib` is used, then use the following as an example:
60 60
          ShibRequireSession On
61 61
          ShibExportAssertion Off
62 62
        </Location>
63
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/saml2/websso">
63
+       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso">
64 64
          AuthType shibboleth
65 65
          Require valid-user
66 66
        </Location>
@@ -73,7 +73,7 @@ If `mod_auth_openidc` is used, then use the following as an example:
73 73
    <VirtualHost *:5000>
74 74
 
75 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
76
+       OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/openid/websso
77 77
 
78 78
        ...
79 79
 
@@ -82,7 +82,7 @@ If `mod_auth_openidc` is used, then use the following as an example:
82 82
          Require valid-user
83 83
          ...
84 84
        </Location>
85
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/websso">
85
+       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/openid/websso">
86 86
          AuthType openid-connect
87 87
          Require valid-user
88 88
          ...
@@ -105,7 +105,7 @@ If `mod_auth_kerb` is used, then use the following as an example:
105 105
          Krb5Keytab /etc/apache2/http.keytab
106 106
          ...
107 107
        </Location>
108
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/kerberos/websso">
108
+       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/kerberos/websso">
109 109
          AuthType Kerberos
110 110
          AuthName "Acme Corporation"
111 111
          KrbMethodNegotiate on
@@ -129,7 +129,7 @@ If `mod_auth_mellon` is used, then use the following as an example:
129 129
          Require valid-user
130 130
          ...
131 131
        </Location>
132
-       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/saml2/websso">
132
+       <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/samltest/protocols/saml2/websso">
133 133
          AuthType Mellon
134 134
          MellonEnable auth
135 135
          Require valid-user
@@ -206,8 +206,8 @@ identity backend.
206 206
        ("credentials", _("Keystone Credentials")),
207 207
        ("openid", _("OpenID Connect")),
208 208
        ("saml2", _("Security Assertion Markup Language")),
209
-       ("myidp_openid", "Acme Corporation - OpenID Connect"),
210
-       ("myidp_saml2", "Acme Corporation - SAML2")
209
+       ("acme_openid", "Acme Corporation - OpenID Connect"),
210
+       ("acme_saml2", "Acme Corporation - SAML2")
211 211
    )
212 212
 
213 213
 3. (Optional) Create a dictionary of specific identity provider and federation
@@ -223,8 +223,8 @@ protocol endpoint.
223 223
 .. code-block:: python
224 224
 
225 225
    WEBSSO_IDP_MAPPING = {
226
-       "myidp_openid": ("myidp", "openid"),
227
-       "myidp_saml2": ("myidp", "saml2")
226
+       "acme_openid": ("acme", "openid"),
227
+       "acme_saml2": ("acme", "saml2")
228 228
    }
229 229
 
230 230
 .. NOTE::

Loading…
Cancel
Save