diff --git a/doc/source/install-guide/configure-federation-idp-adfs.rst b/doc/source/install-guide/configure-federation-idp-adfs.rst new file mode 100644 index 0000000000..5873c5c71a --- /dev/null +++ b/doc/source/install-guide/configure-federation-idp-adfs.rst @@ -0,0 +1,42 @@ +`Home `__ OpenStack Ansible Installation Guide + +Configure Active Directory Federation Services (ADFS) 3.0 as an identity provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To install ADFS: + +* `Prerequisites for ADFS from Microsoft Technet `_ +* `ADFS installation procedure from Microsoft Technet `_ + +Configuring ADFS +---------------- + +#. The ADFS Server must already trust the service provider's (SP) keystone + certificate. It is recommended to have the ADFS CA (or a + public CA) sign a certificate request for the keystone service. +#. In the ADFS Management Console, choose ``Add Relying Party Trust``. +#. Select ``Import data about the relying party published online or on a + local network`` and enter the URL for the SP Metadata ( + for example, ``https://:5000/Shibboleth.sso/Metadata``) + + .. note:: + ADFS may give a warning message that some of the content gathered from metadata + was skipped because is not supported by ADFS. + +#. Continuing the wizard, select ``Permit all users to access this + relying party``. +#. In the ``Add Transform Claim Rule Wizard``, select ``Pass Through or + Filter an Incoming Claim``. +#. Name the rule (for example, ``Pass Through UPN``) and select the ``UPN`` + Incoming claim type. +#. Click :guilabel:`OK` to apply the rule and finalize the setup. + +References +---------- +* http://blogs.technet.com/b/rmilne/archive/2014/04/28/how-to-install-adfs-2012-r2-for-office-365.aspx +* http://blog.kloud.com.au/2013/08/14/powershell-deployment-of-web-application-proxy-and-adfs-in-under-10-minutes/ +* https://ethernuno.wordpress.com/2014/04/20/install-adds-on-windows-server-2012-r2-with-powershell/ + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation-idp.rst b/doc/source/install-guide/configure-federation-idp.rst new file mode 100644 index 0000000000..8215badafb --- /dev/null +++ b/doc/source/install-guide/configure-federation-idp.rst @@ -0,0 +1,77 @@ +`Home `__ OpenStack Ansible Installation Guide + +Configure Identity Service (keystone) as a federated identity provider +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The identity provider (IdP) configuration for Keystone must be provided in a +dictionary attribute with the key ``keystone_idp``. The following is a +complete example:: + + keystone_idp: + certfile: "/etc/keystone/ssl/idp_signing_cert.pem" + keyfile: "/etc/keystone/ssl/idp_signing_key.pem" + self_signed_cert_subject: "/C=US/ST=Texas/L=San Antonio/O=IT/CN={{ external_lb_vip_address }}" + regen_cert: false + idp_entity_id: "{{ keystone_service_publicurl_v3 }}/OS-FEDERATION/saml2/idp" + idp_sso_endpoint: "{{ keystone_service_publicurl_v3 }}/OS-FEDERATION/saml2/sso" + idp_metadata_path: /etc/keystone/saml2_idp_metadata.xml + service_providers: + - id: "sp_1" + auth_url: https://example.com:5000/v3/OS-FEDERATION/identity_providers/idp/protocols/saml2/auth + sp_url: https://example.com:5000/Shibboleth.sso/SAML2/ECP + organization_name: example_company + organization_display_name: Example Corp. + organization_url: example.com + contact_company: example_company + contact_name: John + contact_surname: Smith + contact_email: jsmith@example.com + contact_telephone: 555-55-5555 + contact_type: technical + +The following list is a reference of all the allowed settings: + +* ``certfile`` defines the location and filename of the SSL certificate that + the IdP uses to sign assertions. This file must be in a location that is + accessible to the keystone system user. + +* ``keyfile`` defines the location and filename of the SSL private key that + the IdP uses to sign assertions. This file must be in a location that is + accessible to the keystone system user. + +* ``self_signed_cert_subject`` is the subject used in the SSL signing + certificate. It is important to note that the common name of the certificate + must match the hostname that is configured in the service provider(s) for + this IdP. + +* ``regen_cert`` should normally be set to ``False``. When set to ``True``, + the existing signing certificate will be replaced with a new one. This + setting is added as a convenience mechanism to renew a certificate when it + is close to its expiration date. + +* ``idp_entity_id`` is the entity ID. The service providers will + use this as a unique identifier for each IdP. The recommended value for this + setting is ``/OS-FEDERATION/saml2/idp`` + +* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP. The + recommended value for this setting is + ``/OS-FEDERATION/saml2/sso>`` + +* ``idp_metadata_path`` is the location and filename where the metadata for + this IdP will be cached. The keystone system user must have access to this + location. + +* ``service_providers`` is a list of the known service providers that will be + using this keystone instance as identity provider. For each SP there are + three values that need to be provided: ``id`` is a unique identifier, + ``auth_url`` is the authentication endpoint of the SP, and ``sp_url`` is the + endpoint where SAML2 assertions need to be posted. + +* ``organization_name``, ``organization_display_name``, ``organization_url``, + ``contact_company``, ``contact_name``, ``contact_surname``, + ``contact_email``, ``contact_telephone`` and ``contact_type`` are all + settings that describe the identity provider. These settings are all optional. + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation-mapping.rst b/doc/source/install-guide/configure-federation-mapping.rst new file mode 100644 index 0000000000..1337089eb2 --- /dev/null +++ b/doc/source/install-guide/configure-federation-mapping.rst @@ -0,0 +1,168 @@ +`Home `__ OpenStack Ansible Installation Guide + +Configure Identity Service (keystone) Domain-Project-Group-Role mappings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following is an example service provider (SP) mapping configuration +for an ADFS identity provider (IdP): + +.. code-block:: yaml + + federated_identities: + - domain: Default + project: fedproject + group: fedgroup + role: _member_ + +Each IdP trusted by an SP must have the following configuration: + +#. ``project``: The project which federated users will have access to. + If the project does not already exist then it is created in the + domain with the name specified by ``domain``. + +#. ``group``: The Identity (keystone) group to which the federated users + will belong. If the group does not already exist then it is created in + the domain with the name specified by ``domain``. + +#. ``role``: The role which federated users will assume in that project. + If the role does not already exist, it is created. + +#. ``domain``: The domain in which the ``project`` lives, and in + which the role is assigned. If the domain does not already exist, + it will be created. + +With the above information, Ansible implements the equivalent of the +following OpenStack CLI commands: + +.. code-block:: shell + + # if the domain does not already exist + openstack domain create Default + + # if the group does not already exist + openstack group create fedgroup --domain Default + + # if the role does not already exist + openstack role create _member_ + + # if the project does not already exist + openstack project create --domain Default fedproject + + # map the role to the project and user group in the domain + openstack role add --project fedproject --group fedgroup _member_ + +If the deployer wants to add more mappings, additional options can be added to +the list, for example: + +.. code-block:: yaml + + federated_identities: + - domain: Default + project: fedproject + group: fedgroup + role: _member_ + - domain: Default + project: fedproject2 + group: fedgroup2 + role: _member_ + +Identity Service federation attribute mapping +--------------------------------------------- + +Attribute mapping adds a set of rules to map federation attributes to keystone +users and/or groups. An IdP has exactly one mapping specified per +protocol. + +Mapping objects can be used multiple times by different combinations of +IdP and protocol. + +The details of how the mapping engine works, the schema and various rule +examples are in the `keystone developer documentation `_. + +Consider an example SP attribute mapping configuration for an ADFS IdP: + +.. code-block:: yaml + + mapping: + name: adfs-IdP-mapping + rules: + - remote: + - type: upn + local: + - group: + name: fedgroup + domain: + name: Default + - user: + name: '{0}' + attributes: + - name: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn' + id: upn + +Each IdP for an SP needs to be set up with a mapping. This tells the SP how +to interpret the attributes provided to the SP from the IdP. + +In this particular case the IdP is publishing the ``upn`` attribute. As this +is not in the standard Shibboleth attribute attribute map (see +``/etc/shibboleth/attribute-map.xml`` in the keystone containers), this IdP +has been configured with the extra mapping through the ``attributes`` +dictionary. + +The ``mapping`` dictionary is a yaml representation very similar to the +keystone mapping property which Ansible uploads. The above mapping +produces the following in keystone. + +.. code-block:: shell + + root@aio1_keystone_container-783aa4c0:~# openstack mapping list + +------------------+ + | ID | + +------------------+ + | adfs-IdP-mapping | + +------------------+ + + root@aio1_keystone_container-783aa4c0:~# openstack mapping show adfs-IdP-mapping + +-------+---------------------------------------------------------------------------------------------------------------------------------------+ + | Field | Value | + +-------+---------------------------------------------------------------------------------------------------------------------------------------+ + | id | adfs-IdP-mapping | + | rules | [{"remote": [{"type": "upn"}], "local": [{"group": {"domain": {"name": "Default"}, "name": "fedgroup"}}, {"user": {"name": "{0}"}}]}] | + +-------+---------------------------------------------------------------------------------------------------------------------------------------+ + + root@aio1_keystone_container-783aa4c0:~# openstack mapping show adfs-IdP-mapping | awk -F\| '/rules/ {print $3}' | python -mjson.tool + [ + { + "remote": [ + { + "type": "upn" + } + ], + "local": [ + { + "group": { + "domain": { + "name": "Default" + }, + "name": "fedgroup" + } + }, + { + "user": { + "name": "{0}" + } + } + ] + } + ] + +The interpretation of the above mapping rule is that any federated user +authenticated by the IdP is mapped to an ``ephemeral`` (non-existant) user in +keystone. The user is a member of a group named ``fedgroup``, which in turn is +in a domain called ``Default``. The user's ID and Name (federation always uses +the same value for both properties) for all OpenStack services will be +the value of ``upn``. + + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation-sp-overview.rst b/doc/source/install-guide/configure-federation-sp-overview.rst new file mode 100644 index 0000000000..7e2aa4f8af --- /dev/null +++ b/doc/source/install-guide/configure-federation-sp-overview.rst @@ -0,0 +1,60 @@ +`Home `__ OpenStack Ansible Installation Guide + +Identity Service (keystone) service provider background +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In openstack-ansible (OSA) the Identity Service (keystone) is set up to +use Apache with mod_wsgi. The additional configuration of +keystone as a federation service provider adds Apache mod_shib +and configures it to respond to specific locations requests +from a client. + +.. note:: + There are alternative methods of implementing + federation, but at this time only SAML2-based federation using + the Shibboleth SP is instrumented in OA. + +When requests are sent to those locations, Apache hands off the +request to the ``shibd`` service. Only requests pertaining to +authentication are handed off. + +The ``shibd`` service configuration is primarily handled through +the following files in ``/etc/shibboleth/`` within the keystone +containers: + +* ``sp-cert.pem``, ``sp-key.pem``: These files are generated on the + first keystone container and replicated to the other keystone + containers by the ``os-keystone-install.yml`` playbook. They are + used as signing credentials in communications between the SP + and the IdP. +* ``shibboleth2.xml``: This file's contents are written by the + ``os-keystone-install.yml`` playbook based on the configuration + of the ``keystone_sp`` structured attribute in the + ``/etc/openstack_deploy/user_variables.yml`` file. It contains + the list of trusted IdP's, the entityID by which the SP will + be known and some other facilitating configuration. +* ``attribute-map.xml``: This file's contents are written by the + ``os-keystone-install.yml`` playbook based on the configuration + of the ``keystone_sp`` structured attribute in the + ``/etc/openstack_deploy/user_variables.yml`` file. It contains + some default attribute mappings which will work for any basic + Shibboleth-type IDP setup, but also contains any additional + attribute mappings which were set out in the ``keystone_sp`` + structured attribute. +* ``shibd.logger``: This file is left alone by Ansible, but is useful + when troubleshooting issues with federated authentication or + when trying to discover what attributes published by an IdP + are not currently being understood by your SP's attribute map. + To enable debug logging, change ``log4j.rootCategory=INFO`` to + ``log4j.rootCategory=DEBUG`` at the top of the file. The + log file is output to ``/var/log/shibboleth/shibd.log``. + +References +---------- +* http://docs.openstack.org/developer/keystone/configure_federation.html +* http://docs.openstack.org/developer/keystone/extensions/shibboleth.html +* https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation-sp.rst b/doc/source/install-guide/configure-federation-sp.rst new file mode 100644 index 0000000000..a3b1e46093 --- /dev/null +++ b/doc/source/install-guide/configure-federation-sp.rst @@ -0,0 +1,134 @@ +`Home `__ OpenStack Ansible Installation Guide + +Configure Identity Service (keystone) as a federated service provider +--------------------------------------------------------------------- + +The following settings must be set to configure a service provider (SP): + +#. ``keystone_public_endpoint`` automatically set by default + to the public endpoint's URI. This ensures that + the redirections performed and token references all refer to the + public endpoint which is accessible to clients and the trusted + IDP. + +#. ``horizon_keystone_endpoint`` automatically set by default + to the public v3 API endpoint URL for keystone. Web-based single + sign-on for horizon requires the use of the keystone v3 API. + The value for this must use the same DNS name or IP address which + is registered in the SSL certificate used for the endpoint. + +#. If ADFS is to be used as the IdP, the keystone endpoint is + **required** to have an HTTPS public endpoint. The endpoint may + either be provided by keystone itself, or by an SSL offloading + load balancer. + +#. ``keystone_service_publicuri_proto`` must be set to https in order + to ensure that the public endpoint is registered with https in the + URL, to ensure that keystone publishes https in its references + and to ensure that Shibboleth is configured to know that it should + expect SSL URL's in the assertions (otherwise it will invalidate + the assertions). + +#. ADFS **requires** that a trusted SP have a trusted certificate that + is not self-signed. This means that the certificate used for + keystone must either be signed by a public CA, or an enterprise CA. + +#. When using SSL for the keystone endpoint, the endpoint URI and the + certificate must match. For example, if the certificate does not have + the IP address of the endpoint, then the endpoint must be published with + the appropriate name registered on the certificate. When + using a DNS name for the keystone endpoint, both + ``keystone_public_endpoint`` and ``horizon_keystone_endpoint`` must + be set to use the DNS name. + +#. At this time, `fernet tokens do not fully support + federation `_. + The following settings are therefore required to be set in the + ``user_variables.yml`` file: + + .. code-block:: yaml + + keystone_token_provider: "keystone.token.providers.uuid.Provider" + keystone_token_driver: "keystone.token.persistence.backends.sql.Token" + +#. ``horizon_endpoint_type`` must be set to ``publicURL`` to ensure that + Horizon makes use of the public endpoint for all its references and + queries. + +#. ``keystone_sp`` is a dictionary attribute which contains various + settings that describe both the SP and the IDP's it trusts. For example: + + .. code-block:: yaml + + keystone_sp: + cert_duration_years: 5 + trusted_dashboard_list: + - "https://{{ external_lb_vip_address }}/auth/websso/" + trusted_idp_list: + - name: 'testshib-idp' + entity_ids: + - 'https://idp.testshib.org/idp/shibboleth' + metadata_uri: 'http://www.testshib.org/metadata/testshib-providers.xml' + metadata_file: 'metadata-testshib-idp.xml' + metadata_reload: 1800 + federated_identities: + - domain: Default + project: fedproject + group: fedgroup + role: _member_ + protocols: + - name: saml2 + mapping: + name: testshib-idp-mapping + rules: + - remote: + - type: eppn + local: + - group: + name: fedgroup + domain: + name: Default + - user: + name: '{0}' + +#. ``cert_duration_years`` designates the valid duration for the SP's + signing certificate (for example, ``/etc/shibboleth/sp-key.pem``). + +#. ``trusted_dashboard_list`` designates the list of trusted URLs from which + keystone will accept redirects for Web Single-Sign. This + list should contain all URLs that horizon is presented on, + suffixed by ``/auth/websso/`` which is the path for horizon's WebSSO + component. + +#. ``trusted_idp_list`` is a dictionary attribute containing the list + of settings which pertain to each trusted IdP for the SP. + +#. ``trusted_idp_list.name`` is the name by which the IDP is known, is + configured in keystone and is listed in horizon's login selection. + +#. ``entity_ids`` is a list of reference entity IDs which specify where + the login request to the SP will be redirected to in order to + authenticate to the IdP. + +#. ``metadata_uri`` is the location of the IdP's metadata which provides + the SP with the signing key and all the IdP's supported endpoints. + +#. ``metadata_file`` is the file name of the local cached version of + the metadata which will be stored in ``/var/cache/shibboleth/``. + +#. ``metadata_reload`` is the number of seconds between metadata + refresh polls. + +#. ``federated_identities`` is a list of domain, project, group and users + which are to be mapped. See `Configure Identity Service (keystone) Domain-Project-Group-Role mappings `_ for more information. + +#. ``protocols`` is a list of protocols supported for the IdP and the set + of mappings and attributes for each protocol. Only the protocol with the + name ``saml2`` is supported at this time. + +#. ``mapping`` is the local to remote mapping configuration for federated + users. For more information, see `Configure Identity Service (keystone) Domain-Project-Group-Role mappings. `_ + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation-use-case.rst b/doc/source/install-guide/configure-federation-use-case.rst new file mode 100644 index 0000000000..8aa11f0ddf --- /dev/null +++ b/doc/source/install-guide/configure-federation-use-case.rst @@ -0,0 +1,298 @@ +`Home `__ OpenStack Ansible Installation Guide + +Identity Service to Identity Service federation example use-case +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This document describes the configuration steps necessary to reproduce the +federation scenario described below: + +* Federate Cloud 1 and Cloud 2. +* Create mappings between Cloud 1 Group A and Cloud 2 Project X and Role R. +* Create mappings between Cloud 1 Group B and Cloud 2 Project Y and Role S. +* Create User U in Cloud 1, assign to Group A. +* Authenticate with Cloud 2 and confirm scope to Role R in Project X. +* Assign User U to Group B, confirm scope to Role S in Project Y. + +Keystone identity provider (IdP) configuration +---------------------------------------------- + +The configuration for the keystone IdP instance is as follows:: + + keystone_idp: + certfile: "/etc/keystone/ssl/idp_signing_cert.pem" + keyfile: "/etc/keystone/ssl/idp_signing_key.pem" + self_signed_cert_subject: "/C=US/ST=Texas/L=San Antonio/O=IT/CN={{ external_lb_vip_address }}" + regen_cert: false + idp_entity_id: "{{ keystone_service_publicurl_v3 }}/OS-FEDERATION/saml2/idp" + idp_sso_endpoint: "{{ keystone_service_publicurl_v3 }}/OS-FEDERATION/saml2/sso" + idp_metadata_path: /etc/keystone/saml2_idp_metadata.xml + service_providers: + - id: "cloud2" + auth_url: https://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/cloud1/protocols/saml2/auth + sp_url: https://cloud2.com:5000/Shibboleth.sso/SAML2/ECP + +In the above example, only the last three lines are specific to a particular +installation, as they reference the service provider cloud (referred to as +"Cloud 2" in the original scenario). In the example, it is assumed that this +cloud is located at https://cloud2.com, and the unique ID for this cloud +is "cloud2". + +Also note that in the ``auth_url`` there is a reference to the IdP cloud (or +"Cloud 1"), as known by the service provider (SP). The ID used for the IdP +cloud in this example is "cloud1". + +Keystone SP configuration +------------------------- + +The configuration for the Keystone SP is more complex, as it needs to define +the remote-to-local user mappings. The complete configuration is as follows:: + + keystone_sp: + cert_duration_years: 5 + trusted_dashboard_list: + - "https://{{ external_lb_vip_address }}/auth/websso/" + trusted_idp_list: + - name: "cloud1" + entity_ids: + - 'https://cloud1.com:5000/v3/OS-FEDERATION/saml2/idp' + metadata_uri: 'https://cloud1.com:5000/v3/OS-FEDERATION/saml2/metadata' + metadata_file: 'metadata-cloud1.xml' + metadata_reload: 1800 + federated_identities: + - domain: Default + project: X + role: R + group: federated_group_1 + - domain: Default + project: Y + role: S + group: federated_group_2 + protocols: + - name: saml2 + mapping: + name: cloud1-mapping + rules: + - remote: + - any_one_of: + - A + type: openstack_project + local: + - group: + name: federated_group_1 + domain: + name: Default + - remote: + - any_one_of: + - B + type: openstack_project + local: + - group: + name: federated_group_2 + domain: + name: Default + attributes: + - name: openstack_user + id: openstack_user + - name: openstack_roles + id: openstack_roles + - name: openstack_project + id: openstack_project + - name: openstack_user_domain + id: openstack_user_domain + - name: openstack_project_domain + id: openstack_project_domain + +The ``cert_duration_years`` is used for the self-signed certificate used by +Shibboleth. The ``trusted_dashboard_list`` is only necessary if Horizon SSO +login is going to be implemented. When given, it works as a security measure, +as keystone will only redirect to these URLs. + +The ``trusted_idp_list`` is where the IdPs known to the SP are configured. In +this example there is only one IdP, the "Cloud 1", which is configured with +the ID "cloud1", matching the reference in the IdP configuration shown in the +previous section. + +The ``entity_ids`` is given the unique URL that represents the "Cloud 1" IdP, +which for this example is assumed to be hosted at https://cloud1.com. + +The three metadata values that follow configure the access to the IdP +metadata. The ``metadata_file`` needs to be different for each IdP, as this is +a filename in the keystone containers of the SP cloud that will hold cached +metadata for each registered IdP. + +The ``federated_identities`` list defines the sets of identities that will be +used for federated users. In this example there are two sets, Project X/Role R +and Project Y/Role S. To keep things organized, a user group is created +for each set. + +The ``protocols`` section is where the federation protocols are specified. At +this time the only supported protocol is ``saml2``. + +The ``mapping`` dictionary is where the actual assignments of remote to local +users is defined. A keystone mapping is given a ``name`` and a set of +``rules`` that keystone applies to determine how to map a given user. Each +mapping rule has a ``remote`` and a ``local`` component. + +The ``remote`` part of the mapping rule specifies the criteria for the remote +user, based on the attributes exposed by the IdP in the SAML2 assertion. The +use case for this scenario calls for mapping users in "Group A" and "Group B", +but the group or groups a user belongs to are not exported in the SAML2 +assertion. To make the example work, the groups A and B in the use case have +been assumed to be projects, so there are projects A and B, which are exported +in the assertion under the ``openstack_project`` attribute. The two rules +defined above select the corresponding project using the ``any_one_of`` +selector. + +The ``local`` part of the mapping rule specifies how keystone should represent +the remote user in the local SP cloud. Since the two federated identities were +configured with their own user group, this part simply maps the user to the +corresponding group, which in turn will expose the correct domain, project and +role. Note that a user name is not specified, so keystone creates an +ephemeral user in the specified group. + +The final setting of the configuration defines the SAML2 ``attributes`` that +are exported by the IdP. For a keystone IdP these are the five attributes +shown above. The attributes given in this section are configured into the +Shibboleth service, making them available to use in the mappings. + +Reviewing or modifying the configuration with the Openstack client +------------------------------------------------------------------ + +Use OpenStack command line client to review or make modifications to an +existing federation configuration. The following commands can be used for +the previous configuration. + +Service providers on the identity provider +------------------------------------------ + +To see the list of known SPs:: + + $ openstack service provider list + +--------+---------+-------------+-----------------------------------------------------------------------------------------+ + | ID | Enabled | Description | Auth URL | + +--------+---------+-------------+-----------------------------------------------------------------------------------------+ + | cloud2 | True | None | https://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/cloud1/protocols/saml2/auth | + +--------+---------+-------------+-----------------------------------------------------------------------------------------+ + +To view the information for a specific SP:: + + $ openstack service provider show cloud2 + +--------------------+----------------------------------------------------------------------------------------------+ + | Field | Value | + +--------------------+----------------------------------------------------------------------------------------------+ + | auth_url | http://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/keystone-idp/protocols/saml2/auth | + | description | None | + | enabled | True | + | id | cloud2 | + | relay_state_prefix | ss:mem: | + | sp_url | http://cloud2.com:5000/Shibboleth.sso/SAML2/ECP | + +--------------------+----------------------------------------------------------------------------------------------+ + +To make modifications, the ``set`` command is used. Below are the available +options for this command:: + + $ openstack service provider set + usage: openstack service provider set [-h] [--auth-url ] + [--description ] + [--service-provider-url ] + [--enable | --disable] + + +Identity providers on the service provider +------------------------------------------ + +To see the list of known IdPs:: + + $ openstack identity provider list + +----------------+---------+-------------+ + | ID | Enabled | Description | + +----------------+---------+-------------+ + | cloud1 | True | None | + +----------------+---------+-------------+ + +To view the information for a specific IdP:: + + $ openstack identity provider show keystone-idp + +-------------+--------------------------------------------------------+ + | Field | Value | + +-------------+--------------------------------------------------------+ + | description | None | + | enabled | True | + | id | cloud1 | + | remote_ids | [u'http://cloud1.com:5000/v3/OS-FEDERATION/saml2/idp'] | + +-------------+--------------------------------------------------------+ + +To make modifications, the ``set`` command is used. Below are the available +options for this command:: + + $ openstack identity provider set + usage: openstack identity provider set [-h] + [--remote-id | --remote-id-file ] + [--enable | --disable] + + +Federated identities on the service provider +-------------------------------------------- + +The domain, project, role, group and user entities created for the purpose of +federation are regular keystone entities that can be viewed or modified with +the OpenStack command client. For example:: + + $ openstack domain list + $ openstack project list + $ openstack role list + $ openstack group list + $ openstack user list + +When using a domain other than the default, the ``--domain`` option must be +added to all the commands above except the first. The ``set`` option is used +to modify these entities. + +Federation mappings +------------------- + +To view the list of mappings:: + + $ openstack mapping list + +------------------+ + | ID | + +------------------+ + | cloud1-mapping | + +------------------+ + +To view a mapping in detail:: + + $ openstack mapping show cloud1-mapping + +-------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | Field | Value | + +-------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | id | keystone-idp-mapping-2 | + | rules | [{"remote": [{"type": "openstack_project", "any_one_of": ["A"]}], "local": [{"group": {"domain": {"name": "Default"}, "name": | + | | "federated_group_1"}}]}, {"remote": [{"type": "openstack_project", "any_one_of": ["B"]}], "local": [{"group": {"domain": {"name": "Default"}, | + | | "name": "federated_group_2"}}]}] | + +-------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + +To edit a mapping, use an auxiliary file. Save the JSON mapping shown above +and make the necessary modifications, then use the``set`` command to trigger +an update. For example: + + $ openstack mapping show cloud1-mapping -c rules -f value | python -m json.tool > rules.json + $ vi rules.json # <--- make any necessary changes + $ openstack mapping set cloud1-mapping --rules rules.json + +Federation protocols +-------------------- + +It is also possible to view or change the association between a federation +protocol and a mapping:: + + $ openstack federation protocol list --identity-provider keystone-idp + +-------+----------------+ + | id | mapping | + +-------+----------------+ + | saml2 | cloud1-mapping | + +-------+----------------+ + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation-wrapper.rst b/doc/source/install-guide/configure-federation-wrapper.rst new file mode 100644 index 0000000000..1837bd0c1a --- /dev/null +++ b/doc/source/install-guide/configure-federation-wrapper.rst @@ -0,0 +1,78 @@ +`Home `__ OpenStack Ansible Installation Guide + +Using Identity Service to Identity Service federation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Identity Service (keystone) to Identity Service (keystone) +federation (K2K) the identity provider (IdP) and service provider (SP) +keystone instances exchange information securely to enable a user on +the IdP cloud to access resources of the SP cloud. + +This section applies only to federation between Identity Service IdP +and Identity Service SP. It does not apply to non-keystone IdP. + +.. note:: + For the Kilo release of OpenStack, K2K is only partially supported. + It is possible to perform a federated login using command line clients and + scripting, but Horizon does not support this functionality. + +The K2K authentication flow involves the following steps: + +#. The client logs in to the IdP with his credentials. +#. The client sends a request to the IdP to generate an assertion for a given + SP. An assertion is a cryptographically signed XML document that identifies + the user to the SP. +#. The client submits the assertion to the SP on the configured ``sp_url`` + endpoint. The Shibboleth service running on the SP receives the assertion + and verifies it. If it is valid, it starts a session with the client and + returns the session ID in a cookie. +#. The client now connects to the SP on the configured ``auth_url`` endpoint, + providing the Shibboleth cookie with the session ID. The SP responds with + an unscoped token that the client can use to access the SP. +#. The client connects to the keystone service on the SP with the unscoped + token, and the desired domain and/or project, and receives a scoped token + and the service catalog. +#. The client, now in possession of a token, can make API requests to the + endpoints in the catalog. + +Identity Service to Identity Service federation authentication wrapper +---------------------------------------------------------------------- + +Unfortunately, many of the steps above involve manually sending API requests. +The infrastructure for the command line utilities to perform all these steps +for the user does not yet exist. + +To simplify the task of obtaining access to a SP cloud, OpenStack Ansible provides a script that wraps the above steps. The script is called ``federated-login.sh`` and is +used as follows:: + + ./federated-login.sh -p project [-d domain] sp_id + +Where ``project`` is the project in the SP cloud that the user wants to access, +``domain`` is the domain in which the project lives (the default domain is +used if this argument is not given) and ``sp_id`` is the unique ID of the SP, +as given in the IdP configuration. + +The script outputs the results of all the steps in the authentication flow to +the console, and at the end prints the available endpoints from the catalog +and the scoped token provided by the SP. + +The endpoints and token can be used with the openstack command line client as +follows:: + + $ openstack --os-token= --os-url= [options] + +or alternatively:: + + $ export OS_TOKEN= + $ export OS_URL= + $ openstack [options] + +The user must select the appropriate endpoint for the desired +operation. For example, if the user wants to work with servers, the ``OS_URL`` +argument must be set to the compute endpoint. At this time the openstack +client is unable to find endpoints in the service catalog when using a +federated login. This is likely to be supported in the near future. + +-------------- + +.. include:: navigation.txt diff --git a/doc/source/install-guide/configure-federation.rst b/doc/source/install-guide/configure-federation.rst new file mode 100644 index 0000000000..899fa11eef --- /dev/null +++ b/doc/source/install-guide/configure-federation.rst @@ -0,0 +1,49 @@ +`Home `__ OpenStack Ansible Installation Guide + +Configuring Identity Service federation (optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + + configure-federation-wrapper + configure-federation-sp-overview.rst + configure-federation-sp.rst + configure-federation-idp.rst + configure-federation-idp-adfs.rst + configure-federation-mapping.rst + configure-federation-use-case.rst + +In Identity Service federation, the identity provider (IdP) and service +provider (SP) exchange information securely to enable a user on the IdP cloud +to access resources of the SP cloud. + +.. note:: + For the Kilo release of OpenStack, federation is only partially supported. + It is possible to perform a federated login using command line clients and + scripting, but Dashboard (horizon) does not support this functionality. + +The following procedure describes how set up federation. + +#. `Configure Identity Service (keystone) service providers. `_ + +#. Configure the identity provider: + + * `Configure Identity Service (keystone) as an identity provider. `_ + * `Configure Active Directory Federation Services (ADFS) 3.0 as an identity provider. `_ + +#. Configure the service provider: + + * `Configure Identity Service (keystone) as a federated service provider. `_ + * `Configure Identity Service (keystone) Domain-Project-Group-Role mappings. `_ + +#. `Run the authentication wrapper to use Identity Service to Identity Service federation. `_ + + For examples of how to set up Identity Service to Identity + Service federation, see the `Identity Service to Identity Service + federation example use-case. `_ + +-------------- + +.. include:: navigation.txt + + diff --git a/doc/source/install-guide/configure.rst b/doc/source/install-guide/configure.rst index 3f83ebca23..3f09893525 100644 --- a/doc/source/install-guide/configure.rst +++ b/doc/source/install-guide/configure.rst @@ -21,6 +21,7 @@ Chapter 5. Deployment configuration configure-openstack.rst configure-sslcertificates.rst configure-configurationintegrity.rst + configure-federation.rst **Figure 5.1. Installation work flow**