1. devstack
  2. Commit f3f7c079257701efcc3eb50125e09171ad88811e
Browse code

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

Lance Bragstad authored on 2018/03/31 05:56:04
Showing 2 changed files
doc/source/guides.rst
History View file @ f3f7c07
... ... 
@@ -20,6 +20,7 @@ Walk through various setups used by stackers
20 20 
    guides/devstack-with-nested-kvm
21 21 
    guides/nova
22 22 
    guides/devstack-with-lbaas-v2
23 
+   guides/devstack-with-ldap
23 24
24 25 
 All-In-One Single VM
25 26 
 --------------------
... ... 
@@ -66,3 +67,8 @@ Nova and devstack
66 66 
 --------------------------------
67 67
68 68 
 Guide to working with nova features :doc:`Nova and devstack <guides/nova>`.
69 
+
70 
+Deploying DevStack with LDAP
71 
+----------------------------
72 
+
73 
+Guide to setting up :doc:`DevStack with LDAP <guides/devstack-with-ldap>`.
doc/source/guides/devstack-with-ldap.rst
History View file @ f3f7c07
69 74 
new file mode 100644
... ... 
@@ -0,0 +1,174 @@
0 
+============================
1 
+Deploying DevStack with LDAP
2 
+============================
3 
+
4 
+The OpenStack Identity service has the ability to integrate with LDAP. The goal
5 
+of this guide is to walk you through setting up an LDAP-backed OpenStack
6 
+development environment.
7 
+
8 
+Introduction
9 
+============
10 
+
11 
+LDAP support in keystone is read-only. You can use it to back an entire
12 
+OpenStack deployment to a single LDAP server, or you can use it to back
13 
+separate LDAP servers to specific keystone domains. Users within those domains
14 
+will can authenticate against keystone, assume role assignments, and interact
15 
+with other OpenStack services.
16 
+
17 
+Configuration
18 
+=============
19 
+
20 
+To deploy an OpenLDAP server, make sure ``ldap`` is added to the list of
21 
+``ENABLED_SERVICES``::
22 
+
23 
+    enable_service ldap
24 
+
25 
+Devstack will require a password to set up an LDAP administrator. This
26 
+administrative user is also the bind user specified in keystone's configuration
27 
+files, similar to a ``keystone`` user for MySQL databases.
28 
+
29 
+Devstack will prompt you for a password when running ``stack.sh`` if
30 
+``LDAP_PASSWORD`` is not set. You can add the following to your
31 
+``local.conf``::
32 
+
33 
+    LDAP_PASSWORD=super_secret_password
34 
+
35 
+At this point, devstack should have everything it needs to deploy OpenLDAP,
36 
+bootstrap it with a minimal set of users, and configure it to back to a domain
37 
+in keystone::
38 
+
39 
+    ./stack.sh
40 
+
41 
+Once ``stack.sh`` completes, you should have a running keystone deployment with
42 
+a basic set of users. It is important to note that not all users will live
43 
+within LDAP. Instead, keystone will back different domains to different
44 
+identity sources. For example, the ``default`` domain will be backed by MySQL.
45 
+This is usually where you'll find your administrative and services users. If
46 
+you query keystone for a list of domains, you should see a domain called
47 
+``Users``. This domain is set up by devstack and points to OpenLDAP.
48 
+
49 
+User Management
50 
+===============
51 
+
52 
+Initially, there will only be two users in the LDAP server. The ``Manager``
53 
+user is used by keystone to talk to OpenLDAP. The ``demo`` user is a generic
54 
+user that you should be able to see if you query keystone for users within the
55 
+``Users`` domain. Both of these users were added to LDAP using basic LDAP
56 
+utilities installed by devstack (e.g. ``ldap-utils``) and LDIFs. The LDIFs used
57 
+to create these users can be found in ``devstack/files/ldap/``.
58 
+
59 
+Listing Users
60 
+-------------
61 
+
62 
+To list all users in LDAP directly, you can use ``ldapsearch`` with the LDAP
63 
+user bootstrapped by devstack::
64 
+
65 
+    ldapsearch -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
66 
+        -H ldap://localhost -b dc=openstack,dc=org
67 
+
68 
+As you can see, devstack creates an OpenStack domain called ``openstack.org``
69 
+as a container for the ``Manager`` and ``demo`` users.
70 
+
71 
+Creating Users
72 
+--------------
73 
+
74 
+Since keystone's LDAP integration is read-only, users must be added directly to
75 
+LDAP. Users added directly to OpenLDAP will automatically be placed into the
76 
+``Users`` domain.
77 
+
78 
+LDIFs can be used to add users via the command line. The following is an
79 
+example LDIF that can be used to create a new LDAP user, let's call it
80 
+``peter.ldif.in``::
81 
+
82 
+    dn: cn=peter,ou=Users,dc=openstack,dc=org
83 
+    cn: peter
84 
+    displayName: Peter Quill
85 
+    givenName: Peter Quill
86 
+    mail: starlord@openstack.org
87 
+    objectClass: inetOrgPerson
88 
+    objectClass: top
89 
+    sn: peter
90 
+    uid: peter
91 
+    userPassword: im-a-better-pilot-than-rocket
92 
+
93 
+Now, we use the ``Manager`` user to create a user for Peter in LDAP::
94 
+
95 
+    ldapadd -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
96 
+        -H ldap://localhost -c -f peter.ldif.in
97 
+
98 
+We should be able to assign Peter roles on projects. After Peter has some level
99 
+of authorization, he should be able to login to Horizon by specifying the
100 
+``Users`` domain and using his ``peter`` username and password. Authorization
101 
+can be given to Peter by creating a project within the ``Users`` domain and
102 
+giving him a role assignment on that project::
103 
+
104 
+    $ openstack project create --domain Users awesome-mix-vol-1
105 
+    +-------------+----------------------------------+
106 
+    | Field       | Value                            |
107 
+    +-------------+----------------------------------+
108 
+    | description |                                  |
109 
+    | domain_id   | 61a2de23107c46bea2d758167af707b9 |
110 
+    | enabled     | True                             |
111 
+    | id          | 7d422396d54945cdac8fe1e8e32baec4 |
112 
+    | is_domain   | False                            |
113 
+    | name        | awesome-mix-vol-1                |
114 
+    | parent_id   | 61a2de23107c46bea2d758167af707b9 |
115 
+    | tags        | []                               |
116 
+    +-------------+----------------------------------+
117 
+    $ openstack role add --user peter --user-domain Users \
118 
+          --project awesome-mix-vol-1 --project-domain Users admin
119 
+
120 
+
121 
+Deleting Users
122 
+--------------
123 
+
124 
+We can use the same basic steps to remove users from LDAP, but instead of using
125 
+LDIFs, we can just pass the ``dn`` of the user we want to delete::
126 
+
127 
+    ldapdelete -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
128 
+        -H ldap://localhost cn=peter,ou=Users,dc=openstack,dc=org
129 
+
130 
+Group Management
131 
+================
132 
+
133 
+Like users, groups are considered specific identities. This means that groups
134 
+also fall under the same read-only constraints as users and they can be managed
135 
+directly with LDAP in the same way users are with LDIFs.
136 
+
137 
+Adding Groups
138 
+-------------
139 
+
140 
+Let's define a specific group with the following LDIF::
141 
+
142 
+    dn: cn=guardians,ou=UserGroups,dc=openstack,dc=org
143 
+    objectClass: groupOfNames
144 
+    cn: guardians
145 
+    description: Guardians of the Galaxy
146 
+    member: cn=peter,dc=openstack,dc=org
147 
+    member: cn=gamora,dc=openstack,dc=org
148 
+    member: cn=drax,dc=openstack,dc=org
149 
+    member: cn=rocket,dc=openstack,dc=org
150 
+    member: cn=groot,dc=openstack,dc=org
151 
+
152 
+We can create the group using the same ``ldapadd`` command as we did with
153 
+users::
154 
+
155 
+    ldapadd -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
156 
+        -H ldap://localhost -c -f guardian-group.ldif.in
157 
+
158 
+If we check the group membership in Horizon, we'll see that only Peter is a
159 
+member of the ``guardians`` group, despite the whole crew being specified in
160 
+the LDIF. Once those accounts are created in LDAP, they will automatically be
161 
+added to the ``guardians`` group. They will also assume any role assignments
162 
+given to the ``guardians`` group.
163 
+
164 
+Deleting Groups
165 
+---------------
166 
+
167 
+Just like users, groups can be deleted using the ``dn``::
168 
+
169 
+    ldapdelete -x -w LDAP_PASSWORD -D cn=Manager,dc=openstack,dc=org \
170 
+        -H ldap://localhost cn=guardians,ou=UserGroups,dc=openstack,dc=org
171 
+
172 
+Note that this operation will not remove users within that group. It will only
173 
+remove the group itself and the memberships any users had with that group.