diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst index 9f495036b8..8342fca6e8 100644 --- a/doc/source/admin/federation/configure_federation.rst +++ b/doc/source/admin/federation/configure_federation.rst @@ -100,10 +100,10 @@ Add the authentication methods to the ``[auth]`` section in ``keystone.conf``. Names should be equal to protocol names added via Identity API v3. Here we use examples ``saml2`` and ``openid``. -.. code-block:: bash +.. code-block:: ini - [auth] - methods = external,password,token,saml2,openid + [auth] + methods = external,password,token,saml2,openid Create keystone groups and assign roles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -126,23 +126,23 @@ both of which are exposed to the CLI via `python-openstackclient For example, create a new domain and project like this: -.. code-block:: bash +.. code-block:: console - $ openstack domain create federated_domain - $ openstack project create federated_project --domain federated_domain + $ openstack domain create federated_domain + $ openstack project create federated_project --domain federated_domain And a new group like this: -.. code-block:: bash +.. code-block:: console - $ openstack group create federated_users + $ openstack group create federated_users Add the group to the domain and project: -.. code-block:: bash +.. code-block:: console - $ openstack role add --group federated_users --domain federated_domain Member - $ openstack role add --group federated_users --project federated_project Member + $ openstack role add --group federated_users --domain federated_domain Member + $ openstack role add --group federated_users --project federated_project Member We'll later add a mapping that makes all federated users a part of this group and therefore members of the new domain. @@ -166,9 +166,9 @@ Identity Provider Create an Identity Provider object in keystone, which represents the Identity Provider we will use to authenticate end users: -.. code-block:: bash +.. code-block:: console - $ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp + $ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp The value for the ``remote-id`` option is the unique identifier provided by the IdP. For a SAML IdP it can found as the EntityDescriptor entityID in the IdP's @@ -224,70 +224,70 @@ Mapping objects can be used multiple times by different combinations of Identity As a simple example, if keystone is your IdP, you can map a few known remote users to the group you already created: -.. code-block:: bash +.. code-block:: console - $ cat > rules.json < rules.json < rules.json < rules.json <`__. @@ -301,9 +301,9 @@ request made by an IdP. An IdP may have multiple supported protocols. You can create a protocol like this: -.. code-block:: bash +.. code-block:: console - $ openstack federation protocol create saml2 --mapping myidp_mapping --identity-provider myidp + $ openstack federation protocol create saml2 --mapping myidp_mapping --identity-provider myidp The name you give the protocol is not arbitrary. It must match the method name you gave in the ``[auth]/methods`` config option. When authenticating it will be @@ -356,9 +356,9 @@ considered protected by ``mod_shib`` and Apache, as such a request made to the URL would be redirected to the Identity Provider, to start the SAML authentication procedure. -.. code-block:: bash +.. code-block:: console - $ curl -X GET -D - https://sp.keystone.example.org/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -376,21 +376,21 @@ Read more about `listing resources Example ~~~~~~~ -.. code-block:: bash +.. code-block:: console - $ export OS_IDENTITY_API_VERSION=3 - $ export OS_TOKEN= - $ export OS_URL=https://sp.keystone.example.org/v3 - $ openstack federation project list + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_TOKEN= + $ export OS_URL=https://sp.keystone.example.org/v3 + $ openstack federation project list or -.. code-block:: bash +.. code-block:: console - $ export OS_IDENTITY_API_VERSION=3 - $ export OS_TOKEN= - $ export OS_URL=https://sp.keystone.example.org/v3 - $ openstack federation domain list + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_TOKEN= + $ export OS_URL=https://sp.keystone.example.org/v3 + $ openstack federation domain list Get a scoped token ~~~~~~~~~~~~~~~~~~ @@ -406,15 +406,15 @@ Read more about `getting a scoped token Example ~~~~~~~ -.. code-block:: bash +.. code-block:: console - $ export OS_AUTH_TYPE=token - $ export OS_IDENTITY_API_VERSION=3 - $ export OS_TOKEN= - $ 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 + $ export OS_AUTH_TYPE=token + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_TOKEN= + $ 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 -------------------------------------- Keystone as an Identity Provider (IdP) @@ -433,9 +433,9 @@ Keystone as an Identity Provider (IdP) Example for apt: - .. code-block:: bash + .. code-block:: console - $ apt-get install xmlsec1 + # apt-get install xmlsec1 .. note:: @@ -457,9 +457,9 @@ example: .. code-block:: ini - [saml] - 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 + [saml] + 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. @@ -471,30 +471,30 @@ necessary: .. code-block:: ini - certfile=/etc/keystone/ssl/certs/signing_cert.pem - keyfile=/etc/keystone/ssl/private/signing_key.pem - idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml + certfile=/etc/keystone/ssl/certs/signing_cert.pem + 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 - idp_organization_name=example_company - idp_organization_display_name=Example Corp. - idp_organization_url=example.com + idp_organization_name=example_company + idp_organization_display_name=Example Corp. + 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_name=John - idp_contact_surname=Smith - idp_contact_email=jsmith@example.com - idp_contact_telephone=555-555-5555 - idp_contact_type=technical + idp_contact_company=example_company + idp_contact_name=John + idp_contact_surname=Smith + idp_contact_email=jsmith@example.com + idp_contact_telephone=555-555-5555 + idp_contact_type=technical Generate Metadata ----------------- @@ -514,9 +514,9 @@ vhost:: To create metadata for your keystone IdP, run the ``keystone-manage`` command and redirect the output to a file. For example: -.. code-block:: bash +.. code-block:: console - $ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml + # keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml .. NOTE:: The file location should match the value of the configuration option @@ -535,11 +535,11 @@ 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 described in `Get an unscoped token`_. -.. code-block:: bash +.. code-block:: console - $ 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 + $ 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 ------------------ @@ -551,13 +551,13 @@ scoped token from the SP. ECP stands for Enhanced Client or Proxy, an extension from the SAML2 protocol used in non-browser interfaces, like in the following example. -.. code-block:: bash +.. code-block:: console - $ openstack \ - --os-service-provider mysp \ - --os-remote-project-name federated_project \ - --os-remote-project-domain-name federated_domain \ - token issue + $ openstack \ + --os-service-provider mysp \ + --os-remote-project-name federated_project \ + --os-remote-project-domain-name federated_domain \ + token issue .. include:: openidc.rst diff --git a/doc/source/admin/federation/mapping_combinations.rst b/doc/source/admin/federation/mapping_combinations.rst index 734139ff28..60869d7e75 100644 --- a/doc/source/admin/federation/mapping_combinations.rst +++ b/doc/source/admin/federation/mapping_combinations.rst @@ -43,25 +43,25 @@ A mapping looks as follows: .. code-block:: none - { - "rules": [ - { - "local": [ - { - - [] - [] - } - ], - "remote": [ - { - - [] - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + + [] + [] + } + ], + "remote": [ + { + + [] + } + ] + } + ] + } * `mapping`: a JSON object containing a list of rules. * `rules`: a property in the mapping that contains the list of rules. @@ -114,56 +114,56 @@ the `local` property is collapsed into a single JSON object. For example: .. code-block:: none - { - "local": [ - { - "user": {...} - }, - { - "projects": [...] - }, - ] - } + { + "local": [ + { + "user": {...} + }, + { + "projects": [...] + }, + ] + } becomes: .. code-block:: none - { - "local": { - "user": {...} - "projects": [...] - }, - } + { + "local": { + "user": {...} + "projects": [...] + }, + } when the same property exists in the local multiple times the first occurrence wins: .. code-block:: none - { - "local": [ - { - "user": {#first#} - }, - { - "projects": [...] - }, - { - "user": {#second#} - }, - ] - } + { + "local": [ + { + "user": {#first#} + }, + { + "projects": [...] + }, + { + "user": {#second#} + }, + ] + } becomes: .. code-block:: none - { - "local": { - "user": {#first#} - "projects": [...] - }, - } + { + "local": { + "user": {#first#} + "projects": [...] + }, + } We take this JSON object and then recursively process it in order to apply the direct mappings. This is simply looking for the pattern `{#}` and @@ -180,9 +180,9 @@ Mapping Engine The mapping engine can be tested before creating a federated setup. It can be tested with the ``keystone-manage mapping_engine`` command: -.. code-block:: bash +.. code-block:: console - $ keystone-manage mapping_engine --rules --input + $ keystone-manage mapping_engine --rules --input .. NOTE:: Although the rules file is formatted as JSON, the input file of assertion @@ -232,40 +232,40 @@ empty condition .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0} {1}", - "email": "{2}" - }, - "group": { - "name": "{3}", - "domain": { - "id": "0cd5e9" - } - } - } - ], - "remote": [ - { - "type": "FirstName" - }, - { - "type": "LastName" - }, - { - "type": "Email" - }, - { - "type": "OIDC_GROUPS" - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0} {1}", + "email": "{2}" + }, + "group": { + "name": "{3}", + "domain": { + "id": "0cd5e9" + } + } + } + ], + "remote": [ + { + "type": "FirstName" + }, + { + "type": "LastName" + }, + { + "type": "Email" + }, + { + "type": "OIDC_GROUPS" + } + ] + } + ] + } .. NOTE:: @@ -290,69 +290,69 @@ In ```` shown below, please supply one of the following: .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "id": "0cd5e9" - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "HTTP_OIDC_GROUPIDS", - "": [ - "HTTP_OIDC_EMAIL" - ] - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + }, + "group": { + "id": "0cd5e9" + } + } + ], + "remote": [ + { + "type": "UserName" + }, + { + "type": "HTTP_OIDC_GROUPIDS", + "": [ + "HTTP_OIDC_EMAIL" + ] + } + ] + } + ] + } In ```` shown below, please supply one of the following: ``blacklist``, or ``whitelist``. .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - } - }, - { - "groups": "{1}", - "domain": { - "id": "0cd5e9" - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "HTTP_OIDC_GROUPIDS", - "": [ - "me@example.com" - ] - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + } + }, + { + "groups": "{1}", + "domain": { + "id": "0cd5e9" + } + } + ], + "remote": [ + { + "type": "UserName" + }, + { + "type": "HTTP_OIDC_GROUPIDS", + "": [ + "me@example.com" + ] + } + ] + } + ] + } .. NOTE:: @@ -364,45 +364,45 @@ Group ids and names can be provided in the local section: .. code-block:: json - { - "local": [ - { - "group": { - "id":"0cd5e9" - } - } - ] - } + { + "local": [ + { + "group": { + "id":"0cd5e9" + } + } + ] + } .. code-block:: json - { - "local": [ - { - "group": { - "name": "developer_group", - "domain": { - "id": "abc1234" - } - } - } - ] - } + { + "local": [ + { + "group": { + "name": "developer_group", + "domain": { + "id": "abc1234" + } + } + } + ] + } .. code-block:: json - { - "local": [ - { - "group": { - "name": "developer_group", - "domain": { - "name": "private_cloud" - } - } - } - ] - } + { + "local": [ + { + "group": { + "name": "developer_group", + "domain": { + "name": "private_cloud" + } + } + } + ] + } Users can be mapped to local users that already exist in keystone's identity backend by setting the ``type`` attribute of the user to ``local`` and providing @@ -410,19 +410,19 @@ the domain to which the local user belongs: .. code-block:: json - { - "local": [ - { - "user": { - "name": "local_user", - "type": "local", - "domain": { - "name": "local_domain" - } - } - } - ] - } + { + "local": [ + { + "user": { + "name": "local_user", + "type": "local", + "domain": { + "name": "local_domain" + } + } + } + ] + } The user is then treated as existing in the local identity backend, and the server will attempt to fetch user details (id, name, roles, groups) from the @@ -447,42 +447,42 @@ If a mapping is valid you will receive the following output: .. code-block:: none - { - "group_ids": "[]", - "user": - { - "domain": - { - "id": "Federated" or "" - }, - "type": "ephemeral" or "local", - "name": "", - "id": "" - }, - "group_names": - [ - { - "domain": - { - "name": "" - }, - "name": - { - "name": "[]" - } - } - { - "domain": - { - "name": "" - }, - "name": - { - "name": "[]" - } - } - ] - } + { + "group_ids": "[]", + "user": + { + "domain": + { + "id": "Federated" or "" + }, + "type": "ephemeral" or "local", + "name": "", + "id": "" + }, + "group_names": + [ + { + "domain": + { + "name": "" + }, + "name": + { + "name": "[]" + } + }, + { + "domain": + { + "name": "" + }, + "name": + { + "name": "[]" + } + } + ] + } If the mapped user is local, mapping engine will discard further group assigning and return set of roles configured for the user. @@ -495,34 +495,34 @@ setting it to ``true``. .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "id": "0cd5e9" - } - }, - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "HTTP_OIDC_GROUPIDS", - "any_one_of": [ - ".*@yeah.com$" - ] - "regex": true - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + }, + "group": { + "id": "0cd5e9" + } + }, + ], + "remote": [ + { + "type": "UserName" + }, + { + "type": "HTTP_OIDC_GROUPIDS", + "any_one_of": [ + ".*@yeah.com$" + ] + "regex": true + } + ] + } + ] + } This allows any user with a claim containing a key with any value in ``HTTP_OIDC_GROUPIDS`` to be mapped to group with id ``0cd5e9``. @@ -539,41 +539,41 @@ but cannot be repeated within the same condition. ``any_one_of`` and .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "id": "0cd5e9" - } - }, - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "cn=IBM_Canada_Lab", - "not_any_of": [ - ".*@naww.com$" - ], - "regex": true - }, - { - "type": "cn=IBM_USA_Lab", - "any_one_of": [ - ".*@yeah.com$" - ] - "regex": true - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + }, + "group": { + "id": "0cd5e9" + } + }, + ], + "remote": [ + { + "type": "UserName" + }, + { + "type": "cn=IBM_Canada_Lab", + "not_any_of": [ + ".*@naww.com$" + ], + "regex": true + }, + { + "type": "cn=IBM_USA_Lab", + "any_one_of": [ + ".*@yeah.com$" + ] + "regex": true + } + ] + } + ] + } As before group names and users can also be provided in the local section. @@ -582,9 +582,9 @@ group with id 0cd5e9. .. code-block:: json - {"UserName":"@yeah.com"} - {"cn=IBM_USA_Lab":"@yeah.com"} - {"cn=IBM_Canada_Lab":"@yeah.com"} + {"UserName":"@yeah.com"} + {"cn=IBM_USA_Lab":"@yeah.com"} + {"cn=IBM_Canada_Lab":"@yeah.com"} The following claims will be mapped: @@ -599,64 +599,64 @@ Multiple rules can also be utilized in a mapping. .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "name": "non-contractors", - "domain": { - "id": "abc1234" - } - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "orgPersonType", - "not_any_of": [ - "Contractor", - "SubContractor" - ] - } - ] - }, - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "name": "contractors", - "domain": { - "id": "abc1234" - } - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "orgPersonType", - "any_one_of": [ - "Contractor", - "SubContractor" - ] - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + }, + "group": { + "name": "non-contractors", + "domain": { + "id": "abc1234" + } + } + } + ], + "remote": [ + { + "type": "UserName" + }, + { + "type": "orgPersonType", + "not_any_of": [ + "Contractor", + "SubContractor" + ] + } + ] + }, + { + "local": [ + { + "user": { + "name": "{0}" + }, + "group": { + "name": "contractors", + "domain": { + "id": "abc1234" + } + } + } + ], + "remote": [ + { + "type": "UserName" + }, + { + "type": "orgPersonType", + "any_one_of": [ + "Contractor", + "SubContractor" + ] + } + ] + } + ] + } The above assigns groups membership basing on ``orgPersonType`` values: @@ -738,52 +738,52 @@ For example, consider the following mapping: .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - } - }, - { - "projects": [ - { - "name": "Production", - "roles": [ - { - "name": "reader" - } - ] - }, - { - "name": "Staging", - "roles": [ - { - "name": "member" - } - ] - }, - { - "name": "Project for {0}", - "roles": [ - { - "name": "admin" - } - ] - } - ] - } - ], - "remote": [ - { - "type": "UserName" - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + } + }, + { + "projects": [ + { + "name": "Production", + "roles": [ + { + "name": "reader" + } + ] + }, + { + "name": "Staging", + "roles": [ + { + "name": "member" + } + ] + }, + { + "name": "Project for {0}", + "roles": [ + { + "name": "admin" + } + ] + } + ] + } + ], + "remote": [ + { + "type": "UserName" + } + ] + } + ] + } The semantics of the ``remote`` section have not changed. The difference between this mapping and the other examples is the addition of a ``projects`` @@ -827,52 +827,52 @@ and ``groups``, which allow for direct role assignments and group memberships. .. code-block:: json - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - } - }, - { - "projects": [ - { - "name": "Marketing", - "roles": [ - { - "name": "member" - } - ] - }, - { - "name": "Development project for {0}", - "roles": [ - { - "name": "admin" - } - ] - } - ] - }, - { - "group": { - "name": "Finance", - "domain": { - "id": "6fe767" - } - } - } - ], - "remote": [ - { - "type": "UserName" - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "user": { + "name": "{0}" + } + }, + { + "projects": [ + { + "name": "Marketing", + "roles": [ + { + "name": "member" + } + ] + }, + { + "name": "Development project for {0}", + "roles": [ + { + "name": "admin" + } + ] + } + ] + }, + { + "group": { + "name": "Finance", + "domain": { + "id": "6fe767" + } + } + } + ], + "remote": [ + { + "type": "UserName" + } + ] + } + ] + } In the above example, a federated user will receive direct role assignments on the ``Marketing`` project, as well as a dedicated project specific to the @@ -904,34 +904,34 @@ names we have in the Identity Provider. It will map any user with the name .. code-block:: json - { - "rules": [ - { - "local": [ - { - "group": { - "id": "abc1234" - } - } - ], - "remote": [ - { - "type": "openstack_user", - "any_one_of": [ - "user1", - "admin" - ] - }, - { - "type":"openstack_user_domain", - "any_one_of": [ - "Default" - ] - } - ] - } - ] - } + { + "rules": [ + { + "local": [ + { + "group": { + "id": "abc1234" + } + } + ], + "remote": [ + { + "type": "openstack_user", + "any_one_of": [ + "user1", + "admin" + ] + }, + { + "type":"openstack_user_domain", + "any_one_of": [ + "Default" + ] + } + ] + } + ] + } The possible attributes that can be used in a mapping are `openstack_user`, `openstack_user_domain`, `openstack_roles`, `openstack_project`, and diff --git a/doc/source/admin/federation/mellon.rst b/doc/source/admin/federation/mellon.rst index 63329b275d..e9a89d7c02 100644 --- a/doc/source/admin/federation/mellon.rst +++ b/doc/source/admin/federation/mellon.rst @@ -28,9 +28,9 @@ Configure keystone under Apache, following the steps in the install guide for You'll also need to install the Apache module `mod_auth_mellon `_. For example: -.. code-block:: bash +.. code-block:: console - $ apt-get install libapache2-mod-auth-mellon + # apt-get install libapache2-mod-auth-mellon Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: @@ -41,22 +41,22 @@ Add this *WSGIScriptAlias* directive to your public vhost configuration:: Make sure the *wsgi-keystone.conf* contains a ** directive for the Mellon module and a ** directive for each identity provider -.. code-block:: none +.. code-block:: apache - - MellonEnable "info" - 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" - + + MellonEnable "info" + 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" + - - AuthType "Mellon" - MellonEnable "auth" - + + AuthType "Mellon" + MellonEnable "auth" + .. NOTE:: * See below for information about how to generate the values for the @@ -69,9 +69,9 @@ a ** directive for each identity provider Enable the ``auth_mellon`` module, for example: -.. code-block:: bash +.. code-block:: console - $ a2enmod auth_mellon + # a2enmod auth_mellon Configuring the Mellon SP Metadata ---------------------------------- @@ -80,10 +80,10 @@ Mellon provides a script called `mellon_create_metadata.sh`_ which generates the values for the config directives `MellonSPPrivateKeyFile`, `MellonSPCertFile`, and `MellonSPMetadataFile`. It is run like this: -.. code-block:: bash +.. code-block:: console - $ ./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 + $ ./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 @@ -107,15 +107,15 @@ can upload the file, or you may be required to submit the file using `wget` or Fetch your Identity Provider's Metadata file and copy it to the path specified by the `MellonIdPMetadataFile` directive above. For example: -.. code-block:: bash +.. code-block:: console - $ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \ - https://myidp.example.com/idp/saml2/metadata + $ wget --cacert /path/to/ca.crt -O /etc/apache2/mellon/idp-metadata.xml \ + https://myidp.example.com/idp/saml2/metadata Once you are done, restart the Apache instance that is serving Keystone, for example: -.. code-block:: bash +.. code-block:: console - $ service apache2 restart + # service apache2 restart .. _`mellon_create_metadata.sh`: https://github.com/UNINETT/mod_auth_mellon/blob/master/mellon_create_metadata.sh diff --git a/doc/source/admin/federation/openidc.rst b/doc/source/admin/federation/openidc.rst index fdab1b74b8..ba34027660 100644 --- a/doc/source/admin/federation/openidc.rst +++ b/doc/source/admin/federation/openidc.rst @@ -24,43 +24,43 @@ Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openi To install `mod_auth_openidc` on Ubuntu, perform the following: -.. code-block:: bash +.. code-block:: console - $ sudo apt-get install libapache2-mod-auth-openidc + # apt-get install libapache2-mod-auth-openidc This module is available for other distributions (Fedora/CentOS/Red Hat) from: https://github.com/pingidentity/mod_auth_openidc/releases Enable the auth_openidc module: -.. code-block:: bash +.. code-block:: console - $ sudo a2enmod auth_openidc + # a2enmod auth_openidc In the keystone vhost file, locate the virtual host entry and add the following entries for OpenID Connect: -.. code-block:: none +.. code-block:: apache - + - ... + ... - OIDCClaimPrefix "OIDC-" - OIDCResponseType "id_token" - OIDCScope "openid email profile" - OIDCProviderMetadataURL - OIDCClientID - OIDCClientSecret - OIDCCryptoPassphrase openstack - OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers//protocols/openid/auth + OIDCClaimPrefix "OIDC-" + OIDCResponseType "id_token" + OIDCScope "openid email profile" + OIDCProviderMetadataURL + OIDCClientID + OIDCClientSecret + OIDCCryptoPassphrase openstack + OIDCRedirectURI https://sp.keystone.example.org/v3/OS-FEDERATION/identity_providers//protocols/openid/auth - - AuthType openid-connect - Require valid-user - LogLevel debug - - + + AuthType openid-connect + Require valid-user + LogLevel debug + + Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration If not using `OIDCProviderMetadataURL`, then the following attributes @@ -75,9 +75,9 @@ for more details Once you are done, restart your Apache daemon: -.. code-block:: bash +.. code-block:: console - $ sudo service apache2 restart + # service apache2 restart Tips ---- diff --git a/doc/source/admin/federation/shibboleth.rst b/doc/source/admin/federation/shibboleth.rst index 3c9204912b..28cce95c1a 100644 --- a/doc/source/admin/federation/shibboleth.rst +++ b/doc/source/admin/federation/shibboleth.rst @@ -28,9 +28,9 @@ Configure keystone under Apache, following the steps in the install guide for You'll also need to install `Shibboleth `_, for example: -.. code-block:: bash +.. code-block:: console - $ apt-get install libapache2-mod-shib2 + # apt-get install libapache2-mod-shib2 Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: @@ -39,23 +39,25 @@ Add this *WSGIScriptAliasMatch* directive to your public vhost configuration:: WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /usr/local/bin/keystone-wsgi-public/$1 Make sure the keystone Apache virtual host configuration contains a ** directive for the -Shibboleth module and a ** directive for each identity provider:: +Shibboleth module and a ** directive for each identity provider - - SetHandler shib - +.. code-block:: apache - - ShibRequestSetting requireSession 1 - AuthType shibboleth - ShibExportAssertion Off - Require valid-user + + SetHandler shib + - - ShibRequireSession On - ShibRequireAll On - - + + ShibRequestSetting requireSession 1 + AuthType shibboleth + ShibExportAssertion Off + Require valid-user + + + ShibRequireSession On + ShibRequireAll On + + .. NOTE:: * ``saml2`` is the name of the `protocol that you will configure `_ @@ -68,15 +70,15 @@ Shibboleth module and a ** directive for each identity provider:: Enable the ``shib2`` module, for example: -.. code-block:: bash +.. code-block:: console - $ a2enmod shib2 + # a2enmod shib2 Restart Apache, for example: -.. code-block:: bash +.. code-block:: console - $ service apache2 restart + # service apache2 restart Configuring shibboleth2.xml --------------------------- @@ -86,9 +88,9 @@ configure Shibboleth and upload your Metadata to the Identity Provider. Create a new keypair for Shibboleth with: -.. code-block:: bash +.. code-block:: console - $ shib-keygen -y + # shib-keygen -y The newly created key file will be stored under ``/etc/shibboleth/sp-key.pem``. @@ -101,20 +103,20 @@ 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: .. code-block:: xml - + Example if samltest.id is the IdP: .. code-block:: xml - + * Remove the discoveryURL lines unless you want to enable advanced IdP discovery. @@ -123,13 +125,13 @@ Example if samltest.id is the IdP: .. code-block:: xml - + Example if samltest.id is the IdP: .. code-block:: xml - + You are advised to examine `Shibboleth Service Provider Configuration documentation `_ @@ -138,143 +140,143 @@ to be used in a production environment): .. code-block:: xml - + - + - + For examples with the RequestMap XML syntax instead, see the example-shibboleth2.xml + file, and the https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapHowTo topic. + --> - - + + - - + + - - - SAML2 SAML1 - + + + SAML2 SAML1 + - - SAML2 Local + + SAML2 Local - - + + - - + + - - + + - - - - - + + + + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - + If keystone is your IdP, you will need to examine your attributes map file ``/etc/shibboleth/attribute-map.xml`` and add the following attributes: .. code-block:: xml - - - - - + + + + + For more information see the `attributes documentation `_ Once you are done, restart your Shibboleth daemon and apache: -.. code-block:: bash +.. code-block:: console - $ service shibd restart - $ service apache2 restart + # service shibd restart + # service apache2 restart Check ``/var/log/shibboleth/shibd_warn.log`` for any ERROR or CRIT notices and correct them. @@ -282,9 +284,9 @@ correct them. Upload your Service Provider's metadata file to your Identity Provider. You can fetch it with: -.. code-block:: bash +.. code-block:: console - $ wget https://sp.keystone.example.org/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. diff --git a/doc/source/admin/federation/websso.rst b/doc/source/admin/federation/websso.rst index b7f25bf59e..6111b09153 100644 --- a/doc/source/admin/federation/websso.rst +++ b/doc/source/admin/federation/websso.rst @@ -27,9 +27,9 @@ prevent man-in-the-middle (MITM) attacks. .. code-block:: ini - [federation] - trusted_dashboard = http://acme.horizon.com/auth/websso/ - trusted_dashboard = http://beta.horizon.com/auth/websso/ + [federation] + trusted_dashboard = http://acme.horizon.com/auth/websso/ + trusted_dashboard = http://beta.horizon.com/auth/websso/ 2. Update httpd vhost file with websso information. @@ -47,95 +47,95 @@ is configured in keystone. If `mod_shib` is used, then use the following as an example: -.. code-block:: none +.. code-block:: apache - + - ... + ... - - AuthType shibboleth - Require valid-user - ShibRequestSetting requireSession 1 - ShibRequireSession On - ShibExportAssertion Off - - - AuthType shibboleth - Require valid-user - - + + AuthType shibboleth + Require valid-user + ShibRequestSetting requireSession 1 + ShibRequireSession On + ShibExportAssertion Off + + + AuthType shibboleth + Require valid-user + + If `mod_auth_openidc` is used, then use the following as an example: -.. code-block:: none +.. code-block:: apache - + - OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/websso - OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/websso + OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/websso + OIDCRedirectURI https://sp.keystone.example.org/v3/auth/OS-FEDERATION/identity_providers/myidp/protocols/openid/websso - ... + ... - - AuthType openid-connect - Require valid-user - ... - - - AuthType openid-connect - Require valid-user - ... - - + + AuthType openid-connect + Require valid-user + ... + + + AuthType openid-connect + Require valid-user + ... + + If `mod_auth_kerb` is used, then use the following as an example: -.. code-block:: none +.. code-block:: apache - + - ... + ... - - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - Krb5Keytab /etc/apache2/http.keytab - ... - - - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - Krb5Keytab /etc/apache2/http.keytab - ... - - + + AuthType Kerberos + AuthName "Acme Corporation" + KrbMethodNegotiate on + KrbMethodK5Passwd off + Krb5Keytab /etc/apache2/http.keytab + ... + + + AuthType Kerberos + AuthName "Acme Corporation" + KrbMethodNegotiate on + KrbMethodK5Passwd off + Krb5Keytab /etc/apache2/http.keytab + ... + + If `mod_auth_mellon` is used, then use the following as an example: -.. code-block:: none +.. code-block:: apache - + - ... + ... - - AuthType Mellon - MellonEnable auth - Require valid-user - ... - - - AuthType Mellon - MellonEnable auth - Require valid-user - ... - - + + AuthType Mellon + MellonEnable auth + Require valid-user + ... + + + AuthType Mellon + MellonEnable auth + Require valid-user + ... + + .. NOTE:: If you are also using SSO via the API, don't forget to make the Location @@ -155,17 +155,17 @@ It is recommended that this option be set on a per-protocol basis. .. code-block:: ini - [saml2] - remote_id_attribute = Shib-Identity-Provider - [openid] - remote_id_attribute = HTTP_OIDC_ISS + [saml2] + remote_id_attribute = Shib-Identity-Provider + [openid] + remote_id_attribute = HTTP_OIDC_ISS Alternatively, a generic option may be set at the `[federation]` level. .. code-block:: ini - [federation] - remote_id_attribute = HTTP_OIDC_ISS + [federation] + remote_id_attribute = HTTP_OIDC_ISS 4. Copy the `sso_callback_template.html `__ @@ -188,7 +188,7 @@ this will provide users with an updated login screen for horizon. .. code-block:: python - WEBSSO_ENABLED = True + WEBSSO_ENABLED = True 2. (Optional) Create a list of authentication methods with the `WEBSSO_CHOICES` option. @@ -202,13 +202,13 @@ identity backend. .. code-block:: python - WEBSSO_CHOICES = ( - ("credentials", _("Keystone Credentials")), - ("openid", _("OpenID Connect")), - ("saml2", _("Security Assertion Markup Language")), - ("myidp_openid", "Acme Corporation - OpenID Connect"), - ("myidp_saml2", "Acme Corporation - SAML2") - ) + WEBSSO_CHOICES = ( + ("credentials", _("Keystone Credentials")), + ("openid", _("OpenID Connect")), + ("saml2", _("Security Assertion Markup Language")), + ("myidp_openid", "Acme Corporation - OpenID Connect"), + ("myidp_saml2", "Acme Corporation - SAML2") + ) 3. (Optional) Create a dictionary of specific identity provider and federation protocol combinations. @@ -222,10 +222,10 @@ protocol endpoint. .. code-block:: python - WEBSSO_IDP_MAPPING = { - "myidp_openid": ("myidp", "openid"), - "myidp_saml2": ("myidp", "saml2") - } + WEBSSO_IDP_MAPPING = { + "myidp_openid": ("myidp", "openid"), + "myidp_saml2": ("myidp", "saml2") + } .. NOTE:: @@ -240,10 +240,10 @@ automatically set that choice to be highlighted by default. .. code-block:: python - WEBSSO_INITIAL_CHOICE = "credentials" + WEBSSO_INITIAL_CHOICE = "credentials" 7. Restart your web server: -.. code-block:: bash +.. code-block:: console - $ sudo service apache2 restart + # service apache2 restart