From 343d9d68a2c63a6cd51d18a3f1fe7653386953f0 Mon Sep 17 00:00:00 2001 From: Alexandra Date: Thu, 11 Aug 2016 10:11:57 -0500 Subject: [PATCH] [DOCS] Remove and move keystone federation documentation Move key fed docs to role docs (delete in this repo) Change-Id: Ie5824185b2dc112de0906e4ab0ab593a616a5955 --- .../configure-federation-idp-adfs.rst | 44 --- .../configure-federation-idp.rst | 81 ----- .../configure-federation-mapping.rst | 164 --------- .../configure-federation-sp-overview.rst | 63 ---- .../configure-federation-sp.rst | 125 ------- .../configure-federation-use-case.rst | 326 ------------------ .../configure-federation-wrapper.rst | 93 ----- .../developer-docs/configure-federation.rst | 50 --- .../developer-docs/configure-keystone.rst | 122 ------- 9 files changed, 1068 deletions(-) delete mode 100644 doc/source/developer-docs/configure-federation-idp-adfs.rst delete mode 100644 doc/source/developer-docs/configure-federation-idp.rst delete mode 100644 doc/source/developer-docs/configure-federation-mapping.rst delete mode 100644 doc/source/developer-docs/configure-federation-sp-overview.rst delete mode 100644 doc/source/developer-docs/configure-federation-sp.rst delete mode 100644 doc/source/developer-docs/configure-federation-use-case.rst delete mode 100644 doc/source/developer-docs/configure-federation-wrapper.rst delete mode 100644 doc/source/developer-docs/configure-federation.rst delete mode 100644 doc/source/developer-docs/configure-keystone.rst diff --git a/doc/source/developer-docs/configure-federation-idp-adfs.rst b/doc/source/developer-docs/configure-federation-idp-adfs.rst deleted file mode 100644 index 6bde2cfc6f..0000000000 --- a/doc/source/developer-docs/configure-federation-idp-adfs.rst +++ /dev/null @@ -1,44 +0,0 @@ -`Home `__ OpenStack-Ansible Installation Guide - -Configuring ADFS 3.0 as an identity provider -============================================ - -To install Active Directory Federation Services (ADFS): - -* `Prerequisites for ADFS from Microsoft Technet `_ -* `ADFS installation procedure from Microsoft Technet `_ - -Configuring ADFS -~~~~~~~~~~~~~~~~ - -#. Ensure the ADFS Server trusts the service provider's (SP) keystone - certificate. We recommend 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. The message states that ADFS skipped - some of the content gathered from metadata because it 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/developer-docs/configure-federation-idp.rst b/doc/source/developer-docs/configure-federation-idp.rst deleted file mode 100644 index e1f6ced999..0000000000 --- a/doc/source/developer-docs/configure-federation-idp.rst +++ /dev/null @@ -1,81 +0,0 @@ -`Home `__ OpenStack-Ansible Installation Guide - -Configure Identity service (keystone) as a federated identity provider -====================================================================== - -The Identity Provider (IdP) configuration for keystone provides a -dictionary attribute with the key ``keystone_idp``. The following is a -complete example: - -.. code:: - - 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 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 in the SSL signing - certificate. The common name of the certificate - must match the hostname configuration in the service provider(s) for - this IdP. - -* ``regen_cert`` by default is set to ``False``. When set to ``True``, the - next Ansible run replaces the existing signing certificate 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 - use this as a unique identifier for each IdP. - ``/OS-FEDERATION/saml2/idp`` is the value we - recommend for this setting. - -* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP. - ``/OS-FEDERATION/saml2/sso>`` is the value - we recommend for this setting. - -* ``idp_metadata_path`` is the location and filename where the metadata for - this IdP is cached. The keystone system user must have access to this - location. - -* ``service_providers`` is a list of the known service providers (SP) that - use the keystone instance as identity provider. For each SP, provide - three values: ``id`` as a unique identifier, - ``auth_url`` as the authentication endpoint of the SP, and ``sp_url`` - endpoint for posting SAML2 assertions. - -* ``organization_name``, ``organization_display_name``, ``organization_url``, - ``contact_company``, ``contact_name``, ``contact_surname``, - ``contact_email``, ``contact_telephone`` and ``contact_type`` are - settings that describe the identity provider. These settings are all - optional. - --------------- - -.. include:: navigation.txt diff --git a/doc/source/developer-docs/configure-federation-mapping.rst b/doc/source/developer-docs/configure-federation-mapping.rst deleted file mode 100644 index 9c1b4a8945..0000000000 --- a/doc/source/developer-docs/configure-federation-mapping.rst +++ /dev/null @@ -1,164 +0,0 @@ -`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 that federation users have access to. - If the project does not already exist, create it in the - domain with the name, ``domain``. - -#. ``group``: The keystone group that federation users - belong. If the group does not already exist, create it in - the domain with the name, ``domain``. - -#. ``role``: The role that federation users use in that project. - Create the role if it does not already exist. - -#. ``domain``: The domain where the ``project`` lives, and where - the you assign roles. Create the domain if it does not already exist. - -Ansible implements the equivalent of the following OpenStack CLI commands: - -.. code-block:: shell-session - - # 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_ - -To add more mappings, add options 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 groups. IdP specifies one mapping per protocol. - -Use mapping objects 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 `_. - -For 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 example, the IdP publishes the ``upn`` attribute. As this -is not in the standard Shibboleth attribute map (see -``/etc/shibboleth/attribute-map.xml`` in the keystone containers), the configuration -of the IdP has extra mapping through the ``attributes`` dictionary. - -The ``mapping`` dictionary is a YAML representation similar to the -keystone mapping property which Ansible uploads. The above mapping -produces the following in keystone. - -.. code-block:: shell-session - - 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 federation user -authenticated by the IdP maps to an ``ephemeral`` (non-existant) user in -keystone. The user is a member of a group named ``fedgroup``. This is -in a domain called ``Default``. The user's ID and Name (federation uses -the same value for both properties) for all OpenStack services is -the value of ``upn``. - - --------------- - -.. include:: navigation.txt diff --git a/doc/source/developer-docs/configure-federation-sp-overview.rst b/doc/source/developer-docs/configure-federation-sp-overview.rst deleted file mode 100644 index b4c25f546b..0000000000 --- a/doc/source/developer-docs/configure-federation-sp-overview.rst +++ /dev/null @@ -1,63 +0,0 @@ -`Home `__ OpenStack-Ansible Installation Guide - -Identity Service (keystone) service provider background -======================================================= - -In OpenStack-Ansible, 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. - -.. note:: - - Handing off happens only with requests pertaining to authentication. - -Handle the ``shibd`` service configuration through -the following files in ``/etc/shibboleth/`` in the keystone -containers: - -* ``sp-cert.pem``, ``sp-key.pem``: The ``os-keystone-install.yml`` playbook - uses these files generated on the first keystone container to replicate - them to the other keystone containers. The SP and the IdP use these files - as signing credentials in communications. -* ``shibboleth2.xml``: The ``os-keystone-install.yml`` playbook writes the - file's contents, basing on the structure of the configuration - of the ``keystone_sp`` attribute in the - ``/etc/openstack_deploy/user_variables.yml`` file. It contains - the list of trusted IdP's, the entityID by which the SP is known, - and other facilitating configurations. -* ``attribute-map.xml``: The ``os-keystone-install.yml`` playbook writes - the file's contents, basing on the structure of the configuration - of the ``keystone_sp`` attribute in the - ``/etc/openstack_deploy/user_variables.yml`` file. It contains - the default attribute mappings that work for any basic - Shibboleth-type IDP setup, but also contains any additional - attribute mappings set out in the structure of the ``keystone_sp`` - attribute. -* ``shibd.logger``: This file is left alone by Ansible. It is useful - when troubleshooting issues with federated authentication, or - when discovering 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/developer-docs/configure-federation-sp.rst b/doc/source/developer-docs/configure-federation-sp.rst deleted file mode 100644 index 4f33bfcab3..0000000000 --- a/doc/source/developer-docs/configure-federation-sp.rst +++ /dev/null @@ -1,125 +0,0 @@ -`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`` is automatically set by default - to the public endpoint's URI. This performs redirections and - ensures token references refer to the public endpoint. - -#. ``horizon_keystone_endpoint`` is 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 - registered in the SSL certificate used for the endpoint. - -#. It is a requirement to have a HTTPS public endpoint for the - keystone endpoint if the IdP is ADFS. - Keystone or an SSL offloading load balancer provides the endpoint. - -#. Set ``keystone_service_publicuri_proto`` to https. - This ensures keystone publishes https in its references - and ensures that Shibboleth is configured to know that it - expects 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. - -#. Ensure the endpoint URI and the certificate match when using SSL for the - keystone endpoint. 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. - -#. ``horizon_endpoint_type`` must be set to ``publicURL`` to ensure that - horizon uses 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 that - keystone accepts redirects for Web Single-Sign. This - list contains all URLs that horizon is presented on, - suffixed by ``/auth/websso/``. This 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 IDP's name. Configure this in - in keystone and list in horizon's login selection. - -#. ``entity_ids`` is a list of reference entity IDs. This specify's the - redirection of the login request to the SP when authenticating to - IdP. - -#. ``metadata_uri`` is the location of the IdP's metadata. This 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 mapping list of domain, project, group, and - users. 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. This only supports protocols - with the name ``saml2``. - -#. ``mapping`` is the local to remote mapping configuration for federated - users. See - `Configure Identity Service (keystone) Domain-Project-Group-Role mappings`_ - for more information. - -.. _Configure Identity Service (keystone) Domain-Project-Group-Role mappings: configure-federation-mapping.html - --------------- - -.. include:: navigation.txt diff --git a/doc/source/developer-docs/configure-federation-use-case.rst b/doc/source/developer-docs/configure-federation-use-case.rst deleted file mode 100644 index df0b10ab47..0000000000 --- a/doc/source/developer-docs/configure-federation-use-case.rst +++ /dev/null @@ -1,326 +0,0 @@ -`Home `__ OpenStack-Ansible Installation Guide - -Identity Service to Identity Service federation example use-case -================================================================ - -The following is 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 following is the configuration for the keystone IdP instance: - -.. code:: - - 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 this example, 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, the -cloud is located at https://cloud2.com, and the unique ID for this cloud -is "cloud2". - -.. note:: - - 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 service provider (SP) configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The configuration for keystone SP needs to define the remote-to-local user -mappings. The following is the complete configuration: - -.. code:: - - 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 - -``cert_duration_years`` is for the self-signed certificate used by -Shibboleth. Only implement the ``trusted_dashboard_list`` if horizon SSO -login is necessary. When given, it works as a security measure, -as keystone will only redirect to these URLs. - -Configure the IdPs known to SP in ``trusted_idp_list``. In -this example there is only one IdP, the "Cloud 1". Configure "Cloud 1" with -the ID "cloud1". This matches 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. -For this example, it is hosted at: https://cloud1.com. - -The ``metadata_file`` needs to be different for each IdP. This is -a filename in the keystone containers of the SP cloud that holds cached -metadata for each registered IdP. - -The ``federated_identities`` list defines the sets of identities in use -for federated users. In this example there are two sets, Project X/Role R -and Project Y/Role S. A user group is created for each set. - -The ``protocols`` section is where the federation protocols are specified. -The only supported protocol is ``saml2``. - -The ``mapping`` dictionary is where the 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 are -projects. Export projects A and B in the assertion under the -``openstack_project`` attribute. The two rules above select the corresponding -project using the ``any_one_of`` selector. - -The ``local`` part of the mapping rule specifies how keystone represents -the remote user in the local SP cloud. Configuring the two federated identities -with their own user group maps the user to the -corresponding group. This exposes the correct domain, project, and -role. - -.. note:: - - Keystone creates a ephemeral user in the specified group as - you cannot specify user names. - -The IdP exports the final setting of the configuration defines the SAML2 -``attributes``. For a keystone IdP, these are the five attributes shown above. -Configure the attributes above into the Shibboleth service. This ensures they -are 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: - -.. code:: - - $ 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: - -.. code:: - - $ 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, use the ``set`` command. The following are the available -options for this command: - -.. code:: - - $ 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: - -.. code:: - - $ openstack identity provider list - +----------------+---------+-------------+ - | ID | Enabled | Description | - +----------------+---------+-------------+ - | cloud1 | True | None | - +----------------+---------+-------------+ - -To view the information for a specific IdP: - -.. code:: - - $ 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, use the ``set`` command. The following are the available -options for this command: - -.. code:: - - $ openstack identity provider set - usage: openstack identity provider set [-h] - [--remote-id | --remote-id-file ] - [--enable | --disable] - - -Federated identities on the service provider --------------------------------------------- - -You can use the OpenStack commandline client to view or modify -the created domain, project, role, group, and user entities for the -purpose of federation as these are regular keystone entities. For example: - -.. code:: - - $ openstack domain list - $ openstack project list - $ openstack role list - $ openstack group list - $ openstack user list - -Add the ``--domain`` option when using a domain other than the default. -Use the ``set`` option to modify these entities. - -Federation mappings -------------------- - -To view the list of mappings: - -.. code:: - - $ openstack mapping list - +------------------+ - | ID | - +------------------+ - | cloud1-mapping | - +------------------+ - -To view a mapping in detail: - -..code:: - - $ 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. Use the``set`` command to trigger -an update. For example: - -.. code:: - - $ 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 --------------------- - -To view or change the association between a federation -protocol and a mapping, use the following command: - -.. code:: - - $ openstack federation protocol list --identity-provider keystone-idp - +-------+----------------+ - | id | mapping | - +-------+----------------+ - | saml2 | cloud1-mapping | - +-------+----------------+ - --------------- - -.. include:: navigation.txt diff --git a/doc/source/developer-docs/configure-federation-wrapper.rst b/doc/source/developer-docs/configure-federation-wrapper.rst deleted file mode 100644 index cf001422dd..0000000000 --- a/doc/source/developer-docs/configure-federation-wrapper.rst +++ /dev/null @@ -1,93 +0,0 @@ -`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. - -.. important:: - - This section applies only to federation between keystone IdP - and keystone 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. However, horizon does not support this functionality. - -The K2K authentication flow involves the following steps: - -#. You log in to the IdP with your credentials. -#. You 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. -#. You submit 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, a session with the client starts and - returns the session ID in a cookie. -#. You now connect 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 you use to access the SP. -#. You connect to the keystone service on the SP with the unscoped - token, and the desired domain and project, and receive a scoped token - and the service catalog. -#. You, now in possession of a token, can make API requests to the - endpoints in the catalog. - -Identity service to Identity service federation authentication wrapper -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following steps above involve manually sending API requests. - -.. note:: - - The infrastructure for the command line utilities that performs these steps - for the user does not exist. - -To obtain 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: - -.. code:: - - # ./scripts/federated-login.sh -p project [-d domain] sp_id - -* ``project`` is the project in the SP cloud that you want to access. -* ``domain`` is the domain in which the project lives (the default domain is - used if this argument is not given). -* ``sp_id`` is the unique ID of the SP. This is given in the IdP configuration. - -The script outputs the results of all the steps in the authentication flow to -the console. At the end, it prints the available endpoints from the catalog -and the scoped token provided by the SP. - -Use the endpoints and token with the openstack command line client as follows: - -.. code:: - - # openstack --os-token= --os-url= [options] - -Or, alternatively: - -.. code:: - - # export OS_TOKEN= - # export OS_URL= - # openstack [options] - -Ensure you select the appropriate endpoint for your operation. -For example, if you want to work with servers, the ``OS_URL`` -argument must be set to the compute endpoint. - -.. note:: - - At this time, the OpenStack client is unable to find endpoints in - the service catalog when using a federated login. - --------------- - -.. include:: navigation.txt diff --git a/doc/source/developer-docs/configure-federation.rst b/doc/source/developer-docs/configure-federation.rst deleted file mode 100644 index 00f23ef76f..0000000000 --- a/doc/source/developer-docs/configure-federation.rst +++ /dev/null @@ -1,50 +0,0 @@ -`Home `__ OpenStack-Ansible Installation Guide - -Configuring Identity service (keystone) 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 keystone 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 to 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 keystone to keystone federation, - see the `Identity Service to Identity Service - federation example use-case. `_ - --------------- - -.. include:: navigation.txt - - diff --git a/doc/source/developer-docs/configure-keystone.rst b/doc/source/developer-docs/configure-keystone.rst deleted file mode 100644 index 9e62f6f5ca..0000000000 --- a/doc/source/developer-docs/configure-keystone.rst +++ /dev/null @@ -1,122 +0,0 @@ -`Home `_ OpenStack-Ansible Installation Guide - -Configuring the Identity service (keystone) (optional) -====================================================== - -Customize your keystone deployment in -``/etc/openstack_deploy/user_variables.yml``. - - -Securing keystone communication with SSL certificates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The OpenStack-Ansible project provides the ability to secure keystone -communications with self-signed or user-provided SSL certificates. By default, -self-signed certificates are in use. However, you can -provide your own certificates by using the following Ansible variables in -``/etc/openstack_deploy/user_variables.yml``: - -.. code-block:: yaml - - keystone_user_ssl_cert: # Path to certificate - keystone_user_ssl_key: # Path to private key - keystone_user_ssl_ca_cert: # Path to CA certificate - -.. note:: - - If you are providing certificates, keys, and CA file for a - CA without chain of trust (or an invalid/self-generated ca), the variables - ``keystone_service_internaluri_insecure`` and - ``keystone_service_adminuri_insecure`` should be set to ``True``. - -Refer to `Securing services with SSL certificates`_ for more information on -these configuration options and how you can provide your own -certificates and keys to use with keystone. - -.. _Securing services with SSL certificates: configure-sslcertificates.html - -Implementing LDAP (or Active Directory) backends -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can use the built-in keystone support for services if you already have -LDAP or Active Directory (AD) infrastructure on your deployment. -Keystone uses the existing users, groups, and user-group relationships to -handle authentication and access control in an OpenStack deployment. - -.. note:: - - We do not recommend configuring the default domain in keystone to use - LDAP or AD identity backends. Create additional domains - in keystone and configure either LDAP or active directory backends for - that domain. - - This is critical in situations where the identity backend cannot - be reached due to network issues or other problems. In those situations, - the administrative users in the default domain would still be able to - authenticate to keystone using the default domain which is not backed by - LDAP or AD. - -You can add domains with LDAP backends by adding variables in -``/etc/openstack_deploy/user_variables.yml``. For example, this dictionary -adds a new keystone domain called ``Users`` that is backed by an LDAP server: - -.. code-block:: yaml - - keystone_ldap: - Users: - url: "ldap://10.10.10.10" - user: "root" - password: "secrete" - -Adding the YAML block above causes the keystone playbook to create a -``/etc/keystone/domains/keystone.Users.conf`` file within each keystone service -container that configures the LDAP-backed domain called ``Users``. - -You can create more complex configurations that use LDAP filtering and -consume LDAP as a read-only resource. The following example shows how to apply -these configurations: - -.. code-block:: yaml - - keystone_ldap: - MyCorporation: - url: "ldaps://ldap.example.com" - user_tree_dn: "ou=Users,o=MyCorporation" - group_tree_dn: "cn=openstack-users,ou=Users,o=MyCorporation" - user_objectclass: "inetOrgPerson" - user_allow_create: "False" - user_allow_update: "False" - user_allow_delete: "False" - group_allow_create: "False" - group_allow_update: "False" - group_allow_delete: "False" - user_id_attribute: "cn" - user_name_attribute: "uid" - user_filter: "(groupMembership=cn=openstack-users,ou=Users,o=MyCorporation)" - -In the `MyCorporation` example above, keystone uses the LDAP server as a -read-only resource. The configuration also ensures that keystone filters the -list of possible users to the ones that exist in the -``cn=openstack-users,ou=Users,o=MyCorporation`` group. - -Horizon offers multi-domain support that can be enabled with an Ansible -variable during deployment: - -.. code-block:: yaml - - horizon_keystone_multidomain_support: True - -Enabling multi-domain support in horizon adds the ``Domain`` input field on -the horizon login page and it adds other domain-specific features in the -keystone section. - -More details regarding valid configuration for the LDAP Identity backend can -be found in the `Keystone Developer Documentation`_ and the -`OpenStack Administrator Guide`_. - -.. _Keystone Developer Documentation: http://docs.openstack.org/developer/keystone/configuration.html#configuring-the-ldap-identity-provider -.. _OpenStack Administrator Guide: http://docs.openstack.org/admin-guide/keystone_integrate_identity_backend_ldap.html - --------------- - -.. include:: navigation.txt