openstack/openstack-ansible
Code Issues Proposed changes

Archive Keystone to Keystone Federation rst content

Browse Source 
This content will be used in a future release to
document Keystone to Keystone federation.
It includes mapping, SP setup, IdP setup, and
ADFS info.

Closes-bug: #1482781

Change-Id: Ia0509cd0f59da659e38db8fe55a19edc49b69b37
This commit is contained in:
Erik Wilson 2015-08-11 15:34:02 -05:00 committed by Jesse Pretorius
parent 8edf7fe90c
commit bc074df9ca
9 changed files with 907 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
doc/source/install-guide/configure-federation-idp-adfs.rst Normal file
View File

@ -0,0 +1,42 @@
`Home <index.html>`__ 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 <https://technet.microsoft.com/library/bf7f9cf4-6170-40e8-83dd-e636cb4f9ecb>`_
* `ADFS installation procedure from Microsoft Technet <https://technet.microsoft.com/en-us/library/dn303423>`_
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://<SP_IP_ADDRESS or DNS_NAME>: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

77
doc/source/install-guide/configure-federation-idp.rst Normal file
View File

@ -0,0 +1,77 @@
`Home <index.html>`__ 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 ``<keystone-public-endpoint>/OS-FEDERATION/saml2/idp``
* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP. The
recommended value for this setting is
``<keystone-public-endpoint>/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

168
doc/source/install-guide/configure-federation-mapping.rst Normal file
View File

@ -0,0 +1,168 @@
`Home <index.html>`__ 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 <http://docs.openstack.org/developer/keystone/mapping_combinations.html>`_.
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

60
doc/source/install-guide/configure-federation-sp-overview.rst Normal file
View File

@ -0,0 +1,60 @@
`Home <index.html>`__ 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

134
doc/source/install-guide/configure-federation-sp.rst Normal file
View File

@ -0,0 +1,134 @@
`Home <index.html>`__ 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 <https://bugs.launchpad.net/keystone/+bug/1471289>`_.
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 <configure-federation-mapping.html>`_ 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. <configure-federation-mapping.html>`_
--------------
.. include:: navigation.txt

298
doc/source/install-guide/configure-federation-use-case.rst Normal file
View File

@ -0,0 +1,298 @@
`Home <index.html>`__ 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 <auth-url>]
[--description <description>]
[--service-provider-url <sp-url>]
[--enable | --disable]
<service-provider>
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> | --remote-id-file <file-name>]
[--enable | --disable]
<identity-provider>
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

78
doc/source/install-guide/configure-federation-wrapper.rst Normal file
View File

@ -0,0 +1,78 @@
`Home <index.html>`__ 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=<token> --os-url=<service-endpoint> [options]
or alternatively::
$ export OS_TOKEN=<token>
$ export OS_URL=<service-endpoint>
$ 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

49
doc/source/install-guide/configure-federation.rst Normal file
View File

@ -0,0 +1,49 @@
`Home <index.html>`__ 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-federation-sp.html>`_
#. Configure the identity provider:
* `Configure Identity Service (keystone) as an identity provider. <configure-federation-idp.html>`_
* `Configure Active Directory Federation Services (ADFS) 3.0 as an identity provider. <configure-federation-idp-adfs.html>`_
#. Configure the service provider:
* `Configure Identity Service (keystone) as a federated service provider. <configure-federation-sp.html>`_
* `Configure Identity Service (keystone) Domain-Project-Group-Role mappings. <configure-federation-mapping.html>`_
#. `Run the authentication wrapper to use Identity Service to Identity Service federation. <configure-federation-wrapper.html>`_
For examples of how to set up Identity Service to Identity
Service federation, see the `Identity Service to Identity Service
federation example use-case. <configure-federation-use-case.html>`_
--------------
.. include:: navigation.txt

1
doc/source/install-guide/configure.rst
View File

@ -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**