1. devstack
  2. Commit 22855eb787b6a31843092d6ea52b2ec8541dda97
Browse code

Merge "Add documention for setting up LDAP"

Zuul authored on 2018/04/08 21:38:01
Showing 2 changed files
doc/source/guides.rst
History View file @ 22855eb
... ... 
@@ -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 @ 22855eb
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.