diff --git a/README.rst b/README.rst index 17ff901e..156c3693 100644 --- a/README.rst +++ b/README.rst @@ -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: +``_ +The project home is at: +``_ diff --git a/doc/source/configure-federation-idp.rst b/doc/source/configure-federation-idp.rst new file mode 100644 index 00000000..31a188ce --- /dev/null +++ b/doc/source/configure-federation-idp.rst @@ -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. + ``/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 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 `_ +* `ADFS installation procedure from Microsoft Technet `_ + +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://: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. diff --git a/doc/source/configure-federation-mapping.rst b/doc/source/configure-federation-mapping.rst new file mode 100644 index 00000000..d7b15d48 --- /dev/null +++ b/doc/source/configure-federation-mapping.rst @@ -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 +`_. + +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``. diff --git a/doc/source/configure-federation-sp.rst b/doc/source/configure-federation-sp.rst new file mode 100644 index 00000000..38369cb9 --- /dev/null +++ b/doc/source/configure-federation-sp.rst @@ -0,0 +1,170 @@ +================================================== +Configure keystone as a federated Service Provider +================================================== + +In OpenStack-Ansible, 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 Openstack-Ansible. + +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 OpenStack-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``. + +Configure keystone-to-keystone (k2k) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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) 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) mappings`_ + for more information. + +.. _Configure Identity Service (keystone) mappings: configure-federation-mapping.html diff --git a/doc/source/configure-federation-wrapper.rst b/doc/source/configure-federation-wrapper.rst new file mode 100644 index 00000000..48c51167 --- /dev/null +++ b/doc/source/configure-federation-wrapper.rst @@ -0,0 +1,79 @@ +=========================================== +Configuring keystone-to-keystone federation +=========================================== + +In keystone-to-keystone federation (k2k), the IdP and 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. + +The k2k authentication flow involves the following steps: + +#. Log in to the IdP with your credentials. +#. Send a request to the IdP to generate an assertion for a given SP. +#. 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. +#. 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. +#. With your token, you can now make API requests to the endpoints in the + catalog. + +Keystone-to-keystone 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. diff --git a/doc/source/configure-federation.rst b/doc/source/configure-federation.rst new file mode 100644 index 00000000..593370a6 --- /dev/null +++ b/doc/source/configure-federation.rst @@ -0,0 +1,43 @@ +========================================== +Scenario - Configuring keystone federation +========================================== + +Federation for keystone can be utilised in two ways: + +* Supporting keystone as a Service Provider (SP): consuming identity + assertions issued by an external Identity Provider, such as SAML + assertions or OpenID Connect claims. +* Supporting keystone as an Identity Provider (IdP): fulfilling authentication + requests on behalf of Service Providers. + + .. important:: + + It is also possible to have one keystone act as an SP that + consumes Identity from another keystone acting as an IdP. + This will be discussed further in this document. + +In keystone federation, the IdP and SP exchange information securely to +enable a user on the IdP cloud to access resources of the SP cloud. + +The following procedure describes how to set up federation: + +#. Configure keystone SPs. +#. Configure the IdP: + + * Configure keystone as an IdP. + * Configure Active Directory Federation Services (ADFS) 3.0 as an IdP. + +#. Configure the service provider: + + * Configure keystone as a federated service provider. + * Configure keystone mappings. + +#. Run the authentication wrapper to use keystone-as-a-Service-Provider + federation. + +.. toctree:: + + configure-federation-wrapper + configure-federation-sp.rst + configure-federation-idp.rst + configure-federation-mapping.rst diff --git a/doc/source/configure-keystone.rst b/doc/source/configure-keystone.rst new file mode 100644 index 00000000..59c416b8 --- /dev/null +++ b/doc/source/configure-keystone.rst @@ -0,0 +1,116 @@ +====================================================== +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. + +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 diff --git a/doc/source/index.rst b/doc/source/index.rst index a6210d3d..173e82ad 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1 +1,61 @@ -.. include:: ../../README.rst +=================================== +Keystone role for OpenStack-Ansible +=================================== + +.. toctree:: + :maxdepth: 2 + + configure-keystone.rst + configure-federation.rst + configure-federation-wrapper.rst + configure-federation-sp.rst + configure-federation-idp.rst + configure-federation-mapping.rst + +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 +~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/playbook.yml + :language: yaml + +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. diff --git a/examples/playbook.yml b/examples/playbook.yml new file mode 100644 index 00000000..5d16e0bb --- /dev/null +++ b/examples/playbook.yml @@ -0,0 +1,48 @@ + - 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