Adds Plugin Guide.

Documentation of LDAP plugin for Fuel-9.0 was added.

Change-Id: Ied40e1d731feea6eee8c306b3fdef6487da2038e
This commit is contained in:
Maksym Yatsenko 2016-07-05 20:21:26 +03:00
parent 3227f50ed8
commit 895e53166b
33 changed files with 179 additions and 98 deletions

View File

@ -5,6 +5,5 @@ Appendix
Links
=========================
- `Mirantis OpenStack User Guide <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html>`_
- `Mirantis OpenStack Documentation Center <https://docs.mirantis.com/openstack/fuel/fuel-9.0/>`_
- `Fuel Plugins Catalog <https://www.mirantis.com/products/openstack-drivers-and-plugins/fuel-plugins/>`_
- `Quick Start Guide <https://software.mirantis.com/quick-start/>`_

16
doc/source/changelog.rst Normal file
View File

@ -0,0 +1,16 @@
Release notes / Changelog
=========================
**3.0.0**
* Support of ldap proxy
* Compatibility with MOS 9.0
**2.0.0**
* Support of multi-domains
* Compatibility with MOS 8.0
**1.0.0**
* This is the first release of the plugin

View File

@ -9,10 +9,10 @@ source_suffix = '.rst'
master_doc = 'index'
project = u'The LDAP plugin for Fuel'
copyright = u'2015, Mirantis Inc.'
copyright = u'2016, Mirantis Inc.'
version = '1.0-1.0.0-1'
release = '1.0-1.0.0-1'
version = '3.0-3.0.0-1'
release = '3.0-3.0.0-1'
exclude_patterns = []

View File

@ -5,26 +5,52 @@ Configuring LDAP plugin
#. Create a new OpenStack environment to use an existing LDAP server as authentication
backend for Keystone.
For more information about environment creation, see `Mirantis OpenStack
User Guide <http://docs.mirantis.com/openstack
/fuel/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_.
User Guide <http://docs.openstack.org/developer/fuel-docs
/userdocs/fuel-user-guide/create-environment.html>`_.
#. Open *Settings* tab of the Fuel Web UI, scroll the page down and select
the *LDAP plugin for Keystone* checkbox:
.. image:: images/ldap-checkbox.png
.. image:: images/ldap_plugin.png
.. image:: images/enable_ldap_plugin.png
#. Fill in plugin settings into the text field. LDAP plugin features the following
parameters to enter:
#. Enter plugin settings into the text fields:
.. image:: images/settings.png
Specify domain name, LDAP URL, LDAP suffix:
.. image:: images/ldap_settings.png
.. image:: images/ldap_settings_suffix.png
Enable TLS use and put certificate if it is needed:
.. image:: images/tls_settings.png
Enable LDAP proxy and put custom config if it is needed:
.. image:: images/enable_ldap_proxy.png
.. image:: images/custom_proxy_configs.png
Specify LDAP user, password and other settings:
.. image:: images/user_ldap_settings.png
To use LDAP groups provide settings for it:
.. image:: images/group_ldap_settings.png
Fields description:
================================== ===============
Field Comment
================================== ===============
Domain name Name of the Keystone domain.
LDAP URL URL for connecting to the LDAP server.
LDAP Suffix LDAP server suffix.
LDAP proxy Enable LDAP proxy.
Use TLS Enable TLS for communicating with the LDAP server.
CA Chain CA trust chain in PEM format.
LDAP Suffix LDAP server suffix.
LDAP User User BindDN to query the LDAP server.
LDAP User Password Password for the BindDN to query the LDAP
server.
@ -45,31 +71,62 @@ Configuring LDAP plugin
Group Name Attribute LDAP attribute mapped to group name.
Group Member Attribute LDAP attribute that maps user to group.
Group description Attribute LDAP attribute mapped to description.
Page Size Attribute Maximum results per page.
Chase referrals Attribute Referral chasing behavior for queries.
List of additional Domains Blocks of additional domains/parameters that should be created.
List of custom LDAP proxy configs List of custom LDAP proxy configs.
================================== ===============
.. image:: images/settings.png
#. To deploy an environment with support of multiple domains 'List of additional Domains'
text area should be used. All needed parameters that describes a domain should be copied there,
all parameters form a block of parameters.
* Specify domain name, LDAP URL, LDAP suffix:
.. image:: images/additional_domains.png
.. image:: images/ldap_settings.png
To add multiple domains such block of parameters should be added
to 'List of additional Domains' text area and these blocks should
be separated by empty line.
* Enable TLS use and put certificate if it is needed:
#. To set up an environment with activated LDAP proxy 'LDAP proxy' checkbox should be selected.
When only 'LDAP proxy' checkbox is selected: it activates LDAP proxy for base domain and activates
LDAP proxy for additional domains if they have 'ldap_proxy=true' parameter in their configurations.
.. image:: images/tls_settings.png
.. image:: images/enable_ldap_proxy.png
.. image:: images/ldap_proxy_param.png
* Specify LDAP user, password and other settings:
In this case LDAP proxy configurations for LDAP domains are taken from templates located in the plugin.
Configurations from the templates have minimal functionality and they are intended for testing needs.
.. image:: images/user_ldap_settings.png
To specify custom settings for LDAP proxy 'List of custom LDAP proxy configs' text area should be used.
There can be specified base settings for a proxy service: 'includes', loglevel and etc. can be added to a
proxy configuration file. For this 'config_for' parameter with 'base_config' value should be specified and
after that needed settings should be added.
* To use LDAP groups, enter the corresponding values:
.. image:: images/proxy_base_config.png
.. image:: images/group_ldap_settings.png
To specify custom settings for LDAP domain 'config_for' parameter with <domain_name> value should be added
and after that custom settings can be specified.
.. image:: images/proxy_custom_config.png
#. Finalize environment configuration and run network verification check.
Once done,
`deploy your environment <http://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes>`_.
Blocks of custom settings should be separated by empty line.
#.Continue with environment configuration and deploy it;
for instructions, see
`Fuel User Guide <http://docs.openstack.org/developer/fuel-docs/mitaka/userdocs/fuel-user-guide.html>`_.
#. After successful environment deployment log into dashboard in default domain:
.. image:: images/default_domain.png
#. Go to Identity -> Domains, select needed domain and 'Set Domain Context' for the domain:
.. image:: images/domains.png
.. image:: images/domain_context.png
#. Go to Identity -> Projects and select 'Create Project' to create a new project for the domain
and add user members to the project:
.. image:: images/project.png
.. image:: images/project_members.png

View File

@ -17,9 +17,8 @@ Requirements
================================== ===============
Requirement Version/Comment
================================== ===============
Fuel 7.0
Fuel 9.0
Pre-configured LDAP server
MU (Maintenance Update) 3
================================== ===============
LDAP server should be pre-deployed and be accessible via Public network

View File

@ -2,57 +2,8 @@
User Guide
==========
#. After successfull environment deployment, log into Horizon into the default domain:
.. image:: images/default_domain.png
#. Go to Identity -> Domains, select the required domain and select
*Set Domain Context* for it:
.. image:: images/domains.png
.. image:: images/domain_context.png
#. Go to Identity -> Projects and select 'Create Project' to create a new project for the domain
and add user members to the project:
.. image:: images/project.png
.. image:: images/project_members.png
#. After successful deployment, all users from the LDAP directory matching the
configured filter criteria can authenticate against Keystone. To validate the
configuration, log into the Horizon dashboard using LDAP credentials:
.. image:: images/dashboard.png
#. You can also try to obtain a token to validate authentication:
.. code-block:: bash
# curl -i -s -H "Content-Type: application/json" -d '
{ "auth": {
"identity": {
"methods": ["password"],
"password": {
"user": {
"name": "admin",
"domain": { "id": "default" },
"password": "admin"
}
}
},
"scope": {
"project": {
"name": "admin",
"domain": { "id": "default" }
}
}
}
}' http://<dashboard_ip>:5000/v3/auth/tokens
HTTP/1.1 201 Created
X-Subject-Token: 77a7c2da81f54bb7b46efefa7c7bb5ae
Vary: X-Auth-Token
Content-Type: application/json
Content-Length: 2173

Binary file not shown.

After

Width:  |  Height:  |  Size: 113 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 169 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 193 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 127 KiB

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 122 KiB

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 145 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 153 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 100 KiB

After

Width:  |  Height:  |  Size: 66 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 123 KiB

After

Width:  |  Height:  |  Size: 133 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

After

Width:  |  Height:  |  Size: 72 KiB

View File

@ -9,9 +9,13 @@ Plugin Guide
:maxdepth: 2
description
changelog
limitations
installation
configuration
guide
verification
troubleshooting
appendix

View File

@ -13,27 +13,20 @@ To install LDAP plugin, follow these steps:
#. Copy the plugin on an already installed Fuel Master node (SSH can be used for
that). If you do not have the Fuel Master node yet, see `Quick Start Guide
<https://software.mirantis.com/quick-start/>`_:
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-install-guide/install/install_install_fuel_master_node.html>`_::
.. code-block:: bash
# scp ldap-3.0-3.0.0-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
# scp ldap-1.0-1.0.0-1.noarch.rpm root@<Fuel_Master_IP>:/tmp
#. Log into the Fuel Master node. Install the plugin::
#. Log into the Fuel Master node. Install the plugin:
.. code-block:: bash
# cd /tmp
# fuel plugins --install ldap-1.0-1.0.0-1.noarch.rpm
# cd /tmp
# fuel plugins --install ldap-3.0-3.0.0-1.noarch.rpm
#. Check if the plugin was installed successfully
.. code-block:: bash
::
# fuel plugins
id | name | version | package_version
---|--------------|----------|----------------
1 | ldap | 1.0.0 | 2.0.0
#. MU-3 (Maintenance Update) should be installed to provide proper work of keystone providers
with domains during deployment process.
id | name | version | package_version | releases
---+------+---------+-----------------+--------------------
1 | ldap | 3.0.0 | 3.0.0 | ubuntu (mitaka-9.0)

View File

@ -0,0 +1,11 @@
LDAP plugin limitations
-----------------------
#. LDAP plugin has the following limitations:
- Installation of LDAP plugin before deployment only;
- Fuel will not validate the settings, e.g., by attempting to connect to the LDAP server;
- In multidomain configuration the attributes of the first domain are filled in the web form,
whereas the attributes of other domains are filled in one field;
- The settings of domains determined in “List of additional Domains” field will not be validated;
- The settings of proxy determined in "List of custom LDAP proxy configs" field will not be validated;

View File

@ -5,12 +5,10 @@ Delete all environments, in which the LDAP plugin has been enabled.
#. Uninstall the plugin::
# fuel plugins --remove ldap==1.0.0
# fuel plugins --remove ldap==3.0.0
#. Check if the plugin was uninstalled successfully::
# fuel plugins$
id | name | version | package_version
---|---------------------------|----------|------
# fuel plugins
id | name | version | package_version | releases
---+------+---------+-----------------+---------

View File

@ -0,0 +1,41 @@
===============
Troubleshooting
===============
Checking presence of LDAP domain/users
======================================
To get a list of domains in keystone run the following command on Controller node:
.. code-block:: bash
OS_IDENTITY_API_VERSION=3 openstack domain list
To get a list of users in a domain run the following command on Controller node:
.. code-block:: bash
OS_IDENTITY_API_VERSION=3 openstack user list --quiet --long --domain <domain_name>
Checking LDAP server availability
=================================
To check LDAP server availability run the following command on Controller node:
.. code-block:: bash
ldapsearch -H ldap://<url/ip_address> -x -b dc=<ldap>,dc=<suffix>
LDAP plugin log files
=====================
As LDAP plugin only updates keystone configuration files to check keystone
service, these files keep logs:
/var/log/apache2/keystone_wsgi_admin_access.log
/var/log/apache2/keystone_wsgi_admin_error.log
/var/log/apache2/keystone_wsgi_main_access.log
/var/log/apache2/keystone_wsgi_main_error.log

View File

@ -0,0 +1,12 @@
LDAP plugin validation
----------------------
#. To validate that LDAP plugin is successfully applied after deployment:
- Log into Horizon using domain/user credentials from LDAP server;
- Create an instance;
Expecting results:
- All LDAP users can authenticate via Keystone;
- An instance is successfully created;