Add documention for setting up LDAP
Devstack supports deploying an LDAP server and configuring keystone to use it, but we didn't have any documentation for it. This commit adds some basic documentation that should help developers setup LDAP-backed development environments. Change-Id: I8ba07d73f52cb7f575ff2953977e9fdcade92d83
This commit is contained in:
Lance Bragstad
parent
d9060111d9
commit
f3f7c07925
@ -20,6 +20,7 @@ Walk through various setups used by stackers
|
||||
guides/devstack-with-nested-kvm
|
||||
guides/nova
|
||||
guides/devstack-with-lbaas-v2
|
||||
guides/devstack-with-ldap
|
||||
|
||||
All-In-One Single VM
|
||||
--------------------
|
||||
@ -66,3 +67,8 @@ Nova and devstack
|
||||
--------------------------------
|
||||
|
||||
Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
|
||||
|
||||
Deploying DevStack with LDAP
|
||||
----------------------------
|
||||
|
||||
Guide to setting up :doc:`DevStack with LDAP <guides/devstack-with-ldap>`.
|
||||
|
||||
174
doc/source/guides/devstack-with-ldap.rst
Normal file
174
doc/source/guides/devstack-with-ldap.rst
Normal file
@ -0,0 +1,174 @@
|
||||
============================
|
||||
Deploying DevStack with LDAP
|
||||
============================
|
||||
|
||||
The OpenStack Identity service has the ability to integrate with LDAP. The goal
|
||||
of this guide is to walk you through setting up an LDAP-backed OpenStack
|
||||
development environment.
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
LDAP support in keystone is read-only. You can use it to back an entire
|
||||
OpenStack deployment to a single LDAP server, or you can use it to back
|
||||
separate LDAP servers to specific keystone domains. Users within those domains
|
||||
will can authenticate against keystone, assume role assignments, and interact
|
||||
with other OpenStack services.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
To deploy an OpenLDAP server, make sure ``ldap`` is added to the list of
|
||||
``ENABLED_SERVICES``::
|
||||
|
||||
enable_service ldap
|
||||
|
||||
Devstack will require a password to set up an LDAP administrator. This
|
||||
administrative user is also the bind user specified in keystone's configuration
|
||||
files, similar to a ``keystone`` user for MySQL databases.
|
||||
|
||||
Devstack will prompt you for a password when running ``stack.sh`` if
|
||||
``LDAP_PASSWORD`` is not set. You can add the following to your
|
||||
``local.conf``::
|
||||
|
||||
LDAP_PASSWORD=super_secret_password
|
||||
|
||||
At this point, devstack should have everything it needs to deploy OpenLDAP,
|
||||
bootstrap it with a minimal set of users, and configure it to back to a domain
|
||||
in keystone::
|
||||
|
||||
./stack.sh
|
||||
|
||||
Once ``stack.sh`` completes, you should have a running keystone deployment with
|
||||
a basic set of users. It is important to note that not all users will live
|
||||
within LDAP. Instead, keystone will back different domains to different
|
||||
identity sources. For example, the ``default`` domain will be backed by MySQL.
|
||||
This is usually where you'll find your administrative and services users. If
|
||||
you query keystone for a list of domains, you should see a domain called
|
||||
``Users``. This domain is set up by devstack and points to OpenLDAP.
|
||||
|
||||
User Management
|
||||
===============
|
||||
|
||||
Initially, there will only be two users in the LDAP server. The ``Manager``
|
||||
user is used by keystone to talk to OpenLDAP. The ``demo`` user is a generic
|
||||
user that you should be able to see if you query keystone for users within the
|
||||
``Users`` domain. Both of these users were added to LDAP using basic LDAP
|
||||
utilities installed by devstack (e.g. ``ldap-utils``) and LDIFs. The LDIFs used
|
||||
to create these users can be found in ``devstack/files/ldap/``.
|
||||
|
||||
Listing Users
|
||||
-------------
|
||||
|
||||
To list all users in LDAP directly, you can use ``ldapsearch`` with the LDAP
|
||||
user bootstrapped by devstack::
|
||||
|
||||
ldapsearch -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
|
||||
-H ldap://localhost -b dc=openstack,dc=org
|
||||
|
||||
As you can see, devstack creates an OpenStack domain called ``openstack.org``
|
||||
as a container for the ``Manager`` and ``demo`` users.
|
||||
|
||||
Creating Users
|
||||
--------------
|
||||
|
||||
Since keystone's LDAP integration is read-only, users must be added directly to
|
||||
LDAP. Users added directly to OpenLDAP will automatically be placed into the
|
||||
``Users`` domain.
|
||||
|
||||
LDIFs can be used to add users via the command line. The following is an
|
||||
example LDIF that can be used to create a new LDAP user, let's call it
|
||||
``peter.ldif.in``::
|
||||
|
||||
dn: cn=peter,ou=Users,dc=openstack,dc=org
|
||||
cn: peter
|
||||
displayName: Peter Quill
|
||||
givenName: Peter Quill
|
||||
mail: starlord@openstack.org
|
||||
objectClass: inetOrgPerson
|
||||
objectClass: top
|
||||
sn: peter
|
||||
uid: peter
|
||||
userPassword: im-a-better-pilot-than-rocket
|
||||
|
||||
Now, we use the ``Manager`` user to create a user for Peter in LDAP::
|
||||
|
||||
ldapadd -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
|
||||
-H ldap://localhost -c -f peter.ldif.in
|
||||
|
||||
We should be able to assign Peter roles on projects. After Peter has some level
|
||||
of authorization, he should be able to login to Horizon by specifying the
|
||||
``Users`` domain and using his ``peter`` username and password. Authorization
|
||||
can be given to Peter by creating a project within the ``Users`` domain and
|
||||
giving him a role assignment on that project::
|
||||
|
||||
$ openstack project create --domain Users awesome-mix-vol-1
|
||||
+-------------+----------------------------------+
|
||||
| Field | Value |
|
||||
+-------------+----------------------------------+
|
||||
| description | |
|
||||
| domain_id | 61a2de23107c46bea2d758167af707b9 |
|
||||
| enabled | True |
|
||||
| id | 7d422396d54945cdac8fe1e8e32baec4 |
|
||||
| is_domain | False |
|
||||
| name | awesome-mix-vol-1 |
|
||||
| parent_id | 61a2de23107c46bea2d758167af707b9 |
|
||||
| tags | [] |
|
||||
+-------------+----------------------------------+
|
||||
$ openstack role add --user peter --user-domain Users \
|
||||
--project awesome-mix-vol-1 --project-domain Users admin
|
||||
|
||||
|
||||
Deleting Users
|
||||
--------------
|
||||
|
||||
We can use the same basic steps to remove users from LDAP, but instead of using
|
||||
LDIFs, we can just pass the ``dn`` of the user we want to delete::
|
||||
|
||||
ldapdelete -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
|
||||
-H ldap://localhost cn=peter,ou=Users,dc=openstack,dc=org
|
||||
|
||||
Group Management
|
||||
================
|
||||
|
||||
Like users, groups are considered specific identities. This means that groups
|
||||
also fall under the same read-only constraints as users and they can be managed
|
||||
directly with LDAP in the same way users are with LDIFs.
|
||||
|
||||
Adding Groups
|
||||
-------------
|
||||
|
||||
Let's define a specific group with the following LDIF::
|
||||
|
||||
dn: cn=guardians,ou=UserGroups,dc=openstack,dc=org
|
||||
objectClass: groupOfNames
|
||||
cn: guardians
|
||||
description: Guardians of the Galaxy
|
||||
member: cn=peter,dc=openstack,dc=org
|
||||
member: cn=gamora,dc=openstack,dc=org
|
||||
member: cn=drax,dc=openstack,dc=org
|
||||
member: cn=rocket,dc=openstack,dc=org
|
||||
member: cn=groot,dc=openstack,dc=org
|
||||
|
||||
We can create the group using the same ``ldapadd`` command as we did with
|
||||
users::
|
||||
|
||||
ldapadd -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
|
||||
-H ldap://localhost -c -f guardian-group.ldif.in
|
||||
|
||||
If we check the group membership in Horizon, we'll see that only Peter is a
|
||||
member of the ``guardians`` group, despite the whole crew being specified in
|
||||
the LDIF. Once those accounts are created in LDAP, they will automatically be
|
||||
added to the ``guardians`` group. They will also assume any role assignments
|
||||
given to the ``guardians`` group.
|
||||
|
||||
Deleting Groups
|
||||
---------------
|
||||
|
||||
Just like users, groups can be deleted using the ``dn``::
|
||||
|
||||
ldapdelete -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
|
||||
-H ldap://localhost cn=guardians,ou=UserGroups,dc=openstack,dc=org
|
||||
|
||||
Note that this operation will not remove users within that group. It will only
|
||||
remove the group itself and the memberships any users had with that group.
|
||||
Loading…
Reference in New Issue
Block a user