217
Setting up an LDAP directory
218
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
220
Using and configuring an LDAP server is outside the scope of this manual, but
221
for the purpose of showing some examples we need an LDAP server to connect to.
222
Below are some minimal steps you need to do to have in place first.
224
The following example was tried on Ubuntu Linux, version 11.04 natty. Some
225
earlier versions of Ubuntu require more steps to configure your empty LDAP
226
directory, see `this Ubuntu tutorial for more detailed
227
instructions <http://https://help.ubuntu.com/11.04/serverguide/C/openldap-server.html>`_
228
and similarly see tutorials for your own Linux distribution if those do not work
235
sudo apt-get install slapd ldap-utils
237
The installation asks you to provide an administrator password. In this example
240
Copy the following text into a file backend.example.com.ldif [1]_:
244
# Load dynamic backend modules
245
dn: cn=module,cn=config
246
objectClass: olcModuleList
248
olcModulepath: /usr/lib/ldap
249
olcModuleload: back_hdb.la
252
dn: olcDatabase=hdb,cn=config
253
objectClass: olcDatabaseConfig
254
objectClass: olcHdbConfig
256
olcSuffix: dc=example,dc=com
257
olcDbDirectory: /var/lib/ldap
258
olcRootDN: cn=admin,dc=example,dc=com
260
olcDbConfig: set_cachesize 0 2097152 0
261
olcDbConfig: set_lk_max_objects 1500
262
olcDbConfig: set_lk_max_locks 1500
263
olcDbConfig: set_lk_max_lockers 1500
264
olcDbIndex: objectClass eq
266
olcDbCheckpoint: 512 30
267
olcAccess: to attrs=userPassword by dn="cn=admin,dc=example,dc=com" write by anonymous auth by self write by * none
268
olcAccess: to attrs=shadowLastChange by self write by * read
269
olcAccess: to dn.base="" by * read
270
olcAccess: to * by dn="cn=admin,dc=example,dc=com" write by * read
272
Copy the following text into a file frontend.example.com.ldif:
276
# Create top-level object in domain
277
dn: dc=example,dc=com
279
objectClass: dcObject
280
objectclass: organization
281
o: Example Organization
283
description: LDAP Example
286
dn: cn=admin,dc=example,dc=com
287
objectClass: simpleSecurityObject
288
objectClass: organizationalRole
290
description: LDAP administrator
293
dn: ou=people,dc=example,dc=com
294
objectClass: organizationalUnit
297
dn: ou=groups,dc=example,dc=com
298
objectClass: organizationalUnit
301
dn: uid=john,ou=people,dc=example,dc=com
302
objectClass: inetOrgPerson
303
objectClass: posixAccount
304
objectClass: shadowAccount
309
displayName: John Doe
312
userPassword: password
314
loginShell: /bin/bash
315
homeDirectory: /home/john
321
shadowLastChange: 10877
322
mail: john.doe@example.com
326
mobile: +33 (0)6 xx xx xx xx
327
homePhone: +33 (0)5 xx xx xx xx
328
title: System Administrator
332
dn: cn=example,ou=groups,dc=example,dc=com
333
objectClass: posixGroup
337
Now we create our database and settings, along with the standard
338
"inetOrgPerson" LDAP schema:
342
$ sudo ldapadd -Y EXTERNAL -H ldapi:/// -f backend.example.com.ldif
343
SASL/EXTERNAL authentication started
344
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
346
adding new entry "cn=module,cn=config"
348
adding new entry "olcDatabase=hdb,cn=config"
350
$ sudo ldapadd -x -D cn=admin,dc=example,dc=com -W -f frontend.example.com.ldif
351
Enter LDAP Password: secret
352
adding new entry "dc=example,dc=com"
354
adding new entry "cn=admin,dc=example,dc=com"
356
adding new entry "ou=people,dc=example,dc=com"
358
adding new entry "ou=groups,dc=example,dc=com"
360
adding new entry "uid=john,ou=people,dc=example,dc=com"
362
adding new entry "cn=example,ou=groups,dc=example,dc=com"
364
In the above we first created the database and defined a method to access it.
365
As you see, in the second ldapadd command we now need to provide the admin
366
password `secret` to do further changes, and will need to use it in all further
369
The second command creates a classic `inetOrgPerson` schema, with a user
370
"John Doe" (Common Name) who has a uid "john" and various other information
371
commonly part of a UNIX system account. In fact the LDAP object type is called
372
posixAccount! User john is part of the Organizational Unit "people" in the
375
You can verify that everything is working so far by searching for John:
379
$ ldapsearch -xLLL -b "ou=people,dc=example,dc=com" uid=john
380
dn: uid=john,ou=people,dc=example,dc=com
381
objectClass: inetOrgPerson
382
objectClass: posixAccount
383
objectClass: shadowAccount
388
displayName: John Doe
392
loginShell: /bin/bash
393
homeDirectory: /home/john
399
shadowLastChange: 10877
400
mail: john.doe@example.com
404
mobile: +33 (0)6 xx xx xx xx
405
homePhone: +33 (0)5 xx xx xx xx
406
title: System Administrator
410
If you look closely you see that the userPassword field is not shown. Don't
411
worry! It is stored in the directory, it is just not shown in search results for
414
.. _auth_ldap_examples_add_user:
416
Adding a Drizzle user to LDAP
417
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
419
You could just setup Drizzle to authenticate against standard LDAP accounts like
420
John Doe above. But the recommended way is to add a specific Drizzle schema.
421
You will find this in ``$DRIZZLE_ROOT/share/drizzle7/drizzle_openldap.ldif``.
422
You can add it to your LDAP schema like this:
426
$ sudo ldapadd -Y EXTERNAL -H ldapi:/// -f share/drizzle7/drizzle_openldap.ldif
427
SASL/EXTERNAL authentication started
428
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
430
adding new entry "cn=drizzle,cn=schema,cn=config"
432
Now we can add a Drizzle user to our directory. At this point we will need to
433
store the users Drizzle password. Note that Drizzle, just like MySQL, will
434
prefer to store and use a doubly hashed version of the user password. Other
435
Drizzle authentication plugins, like auth_schema, do the same. (But some plugins
436
do not and Drizzle can use either, since it supports two different
437
authentication protocols for this purpose).
439
Drizzle 7.1 ships with a nice utility to calculate those hashes called
440
``drizzle_password_hash``. You simply give it the password and it outputs
441
the doubly hashed string:
445
$ bin/drizzle_password_hash secret
446
14E65567ABDB5135D0CFD9A70B3032C179A49EE7
448
We will use this utility when creating the LDAP entry for our Drizzle user.
450
Note that the above value is different from what the LDAP directory as the
451
userPassword entry. The Unix or Posix way to store passwords is to just hash
452
them once. You can have a look in your ``/etc/shadow`` file to see what they
453
look like. Anyway, for this reason our Drizzle schema that we just added has
454
an additional field ``drizzleUserPassword`` to store the Drizzle encoded form
455
of the same password. (Or the passwords can also be different, but we will
456
assume most people like to use the same password.)
458
Since Drizzle 7.1 there is also a nice helper script included to create the ldif
459
records you need to add new Drizzle users to your LDAP. Using this script is
460
of course voluntary and you can use any LDAP manager tool you want. But we will
461
use it for this tutorial.
463
Let's create the user hingo:
467
$ share/drizzle7/drizzle_create_ldap_user -p secret -b bin/drizzle_password_hash -u hingo -n 1 -l "ou=people,dc=example,dc=com" > hingo.example.com.ldif
468
$ cat hingo.example.com.ldif
469
dn: uid=hingo,ou=people,dc=example,dc=com
471
objectclass: posixAccount
473
objectclass: drizzleUser
474
drizzleUserMysqlPassword: 14E65567ABDB5135D0CFD9A70B3032C179A49EE7
478
homeDirectory: /home/hingo
479
loginshell: /sbin/nologin
483
If you want, you could use this as a template to further edit the entry.
484
Drizzle will only care about the `drizzleUserMySQLPassword`, `uid` and sometimes
485
(at your option) the `userPassword`. So you can freely edit the rest of the
486
entries to suit you. For instance if this user will also be a user on your Linux
487
system, make sure to set the loginshell to ``/bin/bash`` and check the uid and
488
gid numbers. The ``cn`` field is often used to store the full name of the person,
489
like "Henrik Ingo". (But this is not used by Drizzle.)
491
We now add the above user to the directory:
495
$ sudo ldapadd -x -D cn=admin,dc=example,dc=com -W -f hingo.example.com.ldif
497
adding new entry "uid=hingo,ou=people,dc=example,dc=com"
499
.. _auth_ldap_examples_start_server:
501
Starting Drizzle Server and binding to the LDAP server
502
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
504
It is now time to start the Drizzle server with the needed options so that we
505
can use the LDAP directory for authentication services:
509
$ sbin/drizzled --plugin-remove=auth_all
510
--plugin-add=auth_ldap
511
--auth-ldap.bind-password=secret
512
--auth-ldap.bind-dn="cn=admin,dc=example,dc=com"
513
--auth-ldap.base-dn="ou=people,dc=example,dc=com"
515
`(Give all options on one line.)`
517
``bind-password`` and ``bind-dn`` are used by drizzled to bind to the LDAP
518
server. ``base-dn`` is the DN where our Drizzle users are stored.
520
.. _auth_ldap_examples_connect:
522
Connecting to Drizzle with the client
523
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
525
We can now use a username and password from the LDAP directory when connecting
530
$ bin/drizzle --user=hingo --password
532
Welcome to the Drizzle client.. Commands end with ; or \g.
533
Your Drizzle connection id is 2
534
Connection protocol: mysql
535
Server version: 2011.10.28.2459 Source distribution (drizzle-auth_ldap-fix-and-docs)
537
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
541
.. _auth_ldap_examples_connect_clear_password:
543
Using the userPassword system password with Drizzle
544
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
546
It is also possible to use the password from the userPassword field when
547
connecting with Drizzle. This could be beneficial or necessary to allow
548
all users who already exist in the directory, but didn't have a
549
drizzleUserPassword set for them, to connect to Drizzle.
551
To do this, you have to give the extra option ``--protocol mysql-plugin-auth``
552
to the drizzle client. This will tell the drizzle client to send the password
553
in cleartext to the server, using the MySQL old-password protocol.
555
We could use this to connect to Drizzle with the username john, that
556
we added in the beginning of this tutorial.
560
$ drizzle --password --protocol mysql-plugin-auth --user=john
562
Welcome to the Drizzle client.. Commands end with ; or \g.
563
Your Drizzle connection id is 2
564
Connection protocol: mysql-plugin-auth
565
Server version: 2011.10.28.2459 Source distribution (drizzle-auth_ldap-fix-and-docs)
567
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
573
Using cleartext passwords is **not recommended**. Please note that
574
the connection between drizzle client and drizzled server is completely
575
unencrypted, so other people on your network could easily find out the
576
password if this method is used.
579
.. _auth_ldap_limitations:
584
The option ``LDAP_SCOPE_ONELEVEL`` option is used when searching the LDAP
585
directory. This means you must specify the full base-dn. For instance, if
586
you have users defined in the dn ``ou=people,dn=example,dn=com`` authentication
587
will fail if you only specify ``dn=example,dn=com``. A consequence of this is
588
that all your Drizzle users must belong to the same LDAP organizationalUnit.
590
This is currently a fixed option and can only be changed by editing source code.
591
However, there is no reason why it couldn't be a configurable option to also
592
allow multi level searches. Please contact the Drizzle developers if you have
593
such needs. (See :doc:`/help`)
173
Sorry, there are no examples for this plugin.
596
175
.. _auth_ldap_authors:
601
:Code: Eric Day, Edward "Koko" Konetzko, Henrik Ingo
602
:Documentation: Henrik Ingo
604
182
.. _auth_ldap_version:
609
This documentation applies to **auth_ldap 0.2**.
187
This documentation applies to **auth_ldap 0.1**.
611
189
To see which version of the plugin a Drizzle server is running, execute:
added
removed
plugin/auth_ldap/docs/index.rst
