Skip to content

Commit

Permalink
[DOCS] Move keystone federation role docs
Browse files Browse the repository at this point in the history 
Also includes clean up of the pre-existing content.

Update the role documentation to match the newly proposed format.  In
the new format, each role project should maintain the configuration
variations for the role project itself.

Change-Id: I68ab9a5e8e305114e023ce23341bc9e11a5dbe7c
  • Loading branch information
Alexandra committed Aug 16, 2016
1 parent 2cb8866 commit c0fa231
Show file tree
Hide file tree
Showing 9 changed files with 790 additions and 98 deletions.
104 changes: 7 additions & 97 deletions README.rst
View file
@@ -1,103 +1,13 @@
OpenStack-Ansible Keystone
##########################
==========================
OpenStack-Ansible keystone
==========================

Ansible role that installs and configures OpenStack Keystone. Keystone is
installed behind the Apache webserver listening on port 5000 and port 35357 by
default.

Default Variables
=================

.. literalinclude:: ../../defaults/main.yml
:language: yaml
:start-after: under the License.


Required Variables
==================

This list is not exhaustive at present. See role internals for further
details.

.. code-block:: yaml
# hostname or IP of load balancer providing external network
# access to Keystone
external_lb_vip_address: 10.100.100.102
# hostname or IP of load balancer providing internal network
# access to Keystone
internal_lb_vip_address: 10.100.100.102
# password used by the keystone service to interact with Galera
keystone_container_mysql_password: "YourPassword"
keystone_auth_admin_password: "SuperSecretePassword"
keystone_service_password: "secrete"
keystone_rabbitmq_password: "secrete"
keystone_container_mysql_password: "SuperSecrete"
Example Playbook
================

.. code-block:: yaml
- name: Installation and setup of Keystone
hosts: keystone_all
user: root
pre_tasks:
- name: Create DB for service
mysql_db:
login_user: "root"
login_password: "secrete"
login_host: "localhost"
name: "{{ keystone_galera_database }}"
state: "present"
delegate_to: "{{ keystone_galera_address }}"
when: inventory_hostname == groups['keystone_all'][0]
- name: Grant access to the DB for the service
mysql_user:
login_user: "root"
login_password: "secrete"
login_host: "localhost"
name: "{{ keystone_galera_database }}"
password: "{{ keystone_container_mysql_password }}"
host: "{{ item }}"
state: "present"
priv: "{{ keystone_galera_database }}.*:ALL"
with_items:
- "localhost"
- "%"
delegate_to: "{{ keystone_galera_address }}"
when: inventory_hostname == groups['keystone_all'][0]
roles:
- { role: "os_keystone", tags: [ "os-keystone" ] }
vars:
external_lb_vip_address: 10.100.100.102
internal_lb_vip_address: 10.100.100.102
keystone_galera_address: 10.100.100.101
keystone_galera_database: keystone
keystone_venv_tag: "testing"
keystone_developer_mode: true
keystone_git_install_branch: master
keystone_auth_admin_password: "SuperSecretePassword"
keystone_service_password: "secrete"
keystone_rabbitmq_password: "secrete"
keystone_container_mysql_password: "SuperSecrete"
keystone_rabbitmq_port: 5671
keystone_rabbitmq_userid: keystone
keystone_rabbitmq_vhost: /keystone
keystone_rabbitmq_servers: 10.100.100.101
keystone_rabbitmq_use_ssl: true
galera_client_drop_config_file: false
Tags
====

This role supports two tags: ``keystone-install`` and ``keystone-config``

The ``keystone-install`` tag can be used to install and upgrade.

The ``keystone-config`` tag can be used to maintain configuration of the
service.
Documentation for the project can be found at:
`<http://docs.openstack.org/developer/openstack-ansible-os_keystone/>`_
The project home is at:
`<http://launchpad.net/openstack-ansible>`_

108 changes: 108 additions & 0 deletions doc/source/configure-federation-idp.rst
View file
@@ -0,0 +1,108 @@
===================================================
Configure keystone as a federated Identity Provider
===================================================

The 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.
``<keystone-public-endpoint>/OS-FEDERATION/saml2/idp`` is the value we
recommend for this setting.

* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP.
``<keystone-public-endpoint>/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 SPs that
use the keystone instance as IdP. 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.

Configuring 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
~~~~~~~~~~~~~~~~

#. Ensure the ADFS server trusts the SP's 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://<SP_IP_ADDRESS or DNS_NAME>: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.
158 changes: 158 additions & 0 deletions doc/source/configure-federation-mapping.rst
View file
@@ -0,0 +1,158 @@
===========================
Configure keystone mappings
===========================

The following is an example SP mapping configuration for an ADFS 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_
Keystone 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
<http://docs.openstack.org/developer/keystone/mapping_combinations.html>`_.

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``.

0 comments on commit c0fa231

Please sign in to comment.