~drizzle-trunk/drizzle/development

.. _auth_ldap_plugin:

LDAP Authentication

===================

:program:`auth_ldap` is an authentication plugin that authenticates connections

using an :abbr:`LDAP (Lightweight Directory Access Protocol)` server.  An

LDAP server is required to provide authentication.

Note that a typical use case for using LDAP based authentication, and the

intention with this module, is to be able to consolidate your Drizzle usernames

and passwords in cases where you are already using LDAP in your organization

(such as for Linux or Windows or other system passwords). 

If you are not currently using LDAP for any kind of authentication, you should 

be aware that this is not the simplest authentication method available. For other 

alternatives for managing Drizzle users and passwords, see 

:doc:`/administration/authentication`. A simple authentication module, whose 

behavior will be familiar to those familiar with MySQL and its method for 

storing usernames and passwords, is the :doc:`/plugins/auth_schema/index` plugin.

.. note::

   Unload the :doc:`/plugins/auth_all/index` plugin before using this plugin.

.. seealso:: :doc:`/administration/authentication` 

.. _auth_ldap_loading:

Loading

-------

To load this plugin, start :program:`drizzled` with::

   --plugin-add=auth_ldap

Or, to disable the ability to login without a password, use::

   --plugin-add=auth_pam --plugin-remove=auth_all

Just loading this plugin will not enable or configure it. To actually bind to an

LDAP directory you also need to configure it. See the plugin's

:ref:`auth_ldap_configuration` and :ref:`auth_ldap_variables`.

.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins.

.. _auth_ldap_configuration:

Configuration

-------------

These command line options configure the plugin when :program:`drizzled`

is started.  See :ref:`command_line_options` for more information about specifying

command line options.

.. program:: drizzled

.. option:: --auth-ldap.base-dn ARG

   :Default: 

   :Variable: :ref:`auth_ldap_base_dn <auth_ldap_base_dn>`

   DN to use when searching.

   Drizzle uses the ``LDAP_SCOPE_ONELEVEL`` option when searching the LDAP 

   directory. This means you must specify the full base-dn. For instance, if

   you have users defined in the dn ``ou=people,dn=example,dn=com`` authentication

   will fail if you only specify ``dn=example,dn=com``. (See 

   :ref:`auth_ldap_limitations`)

.. option:: --auth-ldap.bind-dn ARG

   :Default: 

   :Variable: :ref:`auth_ldap_bind_dn <auth_ldap_bind_dn>`

   DN to use when binding to the LDAP server.

   Until Drizzle 2011.11.29 (a Drizzle 7.1 beta release) this option was mistakenly

   called ``bind-db``. Starting with release 2011.12.30 that option will no longer

   work, the correct option is ``bind-dn``. (The corresponding variable was

   always ref:`auth_ldap_bind_dn <auth_ldap_bind_dn>` and is unchanged.)

.. option:: --auth-ldap.bind-password ARG

   :Default: 

   :Variable: :ref:`auth_ldap_bind_password <auth_ldap_bind_password>`

   Password to use when binding the DN, ie. your LDAP admin password.

.. option:: --auth-ldap.cache-timeout ARG

   :Default: ``600``

   :Variable: :ref:`auth_ldap_cache_timeout <auth_ldap_cache_timeout>`

   How often to empty the users cache. The default is 10 minutes.

   A value of 0 means never: if a user has once connected to Drizzle, his 

   credentials will then be cached until the next restart. Any changes to the 

   LDAP directory, such as changing the password, would not be visible in 

   drizzled as long as it wasn't restarted.

.. option:: --auth-ldap.mysql-password-attribute ARG

   :Default: ``drizzleMysqlUserPassword``

   :Variable: :ref:`auth_ldap_mysql_password_attribute <auth_ldap_mysql_password_attribute>`

   Attribute in LDAP with MySQL hashed password.

   Until Drizzle 2011.11.29 (a Drizzle 7.1 beta release) the default value of this

   option was ``mysqlUserPassword``. Beginning with release 2011.12.30

   it was changed to ``drizzleMysqlUserPassword`` to match the provided

   openldap ldif schema.

.. option:: --auth-ldap.password-attribute ARG

   :Default: ``userPassword``

   :Variable: :ref:`auth_ldap_password_attribute <auth_ldap_password_attribute>`

   Attribute in LDAP with plain text password.

.. option:: --auth-ldap.uri ARG

   :Default: ``ldap://127.0.0.1/``

   :Variable: :ref:`auth_ldap_uri <auth_ldap_uri>`

   URI of the LDAP server to contact.

.. _auth_ldap_variables:

Variables

---------

These variables show the running configuration of the plugin.

See `variables` for more information about querying and setting variables.

.. _auth_ldap_base_dn:

* ``auth_ldap_base_dn``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.base-dn`

   DN to use when searching.

.. _auth_ldap_bind_dn:

* ``auth_ldap_bind_dn``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.bind-dn`

   DN to use when binding to the LDAP server.

.. _auth_ldap_bind_password:

* ``auth_ldap_bind_password``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.bind-password`

   Password to use when binding the DN.

   Note: This variable existed until Drizzle 2011.11.29, in particular it was part

   of the Drizzle 7 stable release. For security reasons this variable has been 

   removed in Drizzle release 2011.12.30, a Drizzle 7.1 beta release. There was 

   no valid reason to expose your LDAP admin password to every Drizzle user. 

.. _auth_ldap_cache_timeout:

* ``auth_ldap_cache_timeout``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.cache-timeout`

   How often to empty the users cache.

.. _auth_ldap_mysql_password_attribute:

* ``auth_ldap_mysql_password_attribute``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.mysql-password-attribute`

   Attribute in LDAP with MySQL hashed password.

.. _auth_ldap_password_attribute:

* ``auth_ldap_password_attribute``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.password-attribute`

   Attribute in LDAP with plain text password.

.. _auth_ldap_uri:

* ``auth_ldap_uri``

   :Scope: Global

   :Dynamic: No

   :Option: :option:`--auth-ldap.uri`

   URI of the LDAP server to contact.

.. _auth_ldap_examples:

Examples

--------

Setting up an LDAP directory

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using and configuring an LDAP server is outside the scope of this manual, but 

for the purpose of showing some examples we need an LDAP server to connect to.

Below are some minimal steps you need to do to have in place first.

The following example was tried on Ubuntu Linux, version 11.04 natty. Some

earlier versions of Ubuntu require more steps to configure your empty LDAP

directory, see `this Ubuntu tutorial for more detailed 

instructions <http://https://help.ubuntu.com/11.04/serverguide/C/openldap-server.html>`_

and similarly see tutorials for your own Linux distribution if those do not work

for you.

To install OpenLDAP:

.. code-block:: bash

   sudo apt-get install slapd ldap-utils

The installation asks you to provide an administrator password. In this example

we've used `secret`.

Copy the following text into a file backend.example.com.ldif [1]_:

.. code-block:: none

    # Load dynamic backend modules

    dn: cn=module,cn=config

    objectClass: olcModuleList

    cn: module

    olcModulepath: /usr/lib/ldap

    olcModuleload: back_hdb.la

    # Database settings

    dn: olcDatabase=hdb,cn=config

    objectClass: olcDatabaseConfig

    objectClass: olcHdbConfig

    olcDatabase: {1}hdb

    olcSuffix: dc=example,dc=com

    olcDbDirectory: /var/lib/ldap

    olcRootDN: cn=admin,dc=example,dc=com

    olcRootPW: secret

    olcDbConfig: set_cachesize 0 2097152 0

    olcDbConfig: set_lk_max_objects 1500

    olcDbConfig: set_lk_max_locks 1500

    olcDbConfig: set_lk_max_lockers 1500

    olcDbIndex: objectClass eq

    olcLastMod: TRUE

    olcDbCheckpoint: 512 30

    olcAccess: to attrs=userPassword by dn="cn=admin,dc=example,dc=com" write by anonymous auth by self write by * none

    olcAccess: to attrs=shadowLastChange by self write by * read

    olcAccess: to dn.base="" by * read

    olcAccess: to * by dn="cn=admin,dc=example,dc=com" write by * read

Copy the following text into a file frontend.example.com.ldif:

.. code-block:: none

    # Create top-level object in domain

    dn: dc=example,dc=com

    objectClass: top

    objectClass: dcObject

    objectclass: organization

    o: Example Organization

    dc: Example

    description: LDAP Example 

    # Admin user.                                                                                                                                                                       

    dn: cn=admin,dc=example,dc=com                                                                                                                                                      

    objectClass: simpleSecurityObject                                                                                                                                                   

    objectClass: organizationalRole                                                                                                                                                     

    cn: admin                                                                                                                                                                           

    description: LDAP administrator                                                                                                                                                     

    userPassword: secret

    dn: ou=people,dc=example,dc=com

    objectClass: organizationalUnit

    ou: people

    dn: ou=groups,dc=example,dc=com

    objectClass: organizationalUnit

    ou: groups

    dn: uid=john,ou=people,dc=example,dc=com

    objectClass: inetOrgPerson

    objectClass: posixAccount

    objectClass: shadowAccount

    uid: john

    sn: Doe

    givenName: John

    cn: John Doe

    displayName: John Doe

    uidNumber: 1000

    gidNumber: 10000

    userPassword: password

    gecos: John Doe

    loginShell: /bin/bash

    homeDirectory: /home/john

    shadowExpire: -1

    shadowFlag: 0

    shadowWarning: 7

    shadowMin: 8

    shadowMax: 999999

    shadowLastChange: 10877

    mail: john.doe@example.com

    postalCode: 31000

    l: Toulouse

    o: Example

    mobile: +33 (0)6 xx xx xx xx

    homePhone: +33 (0)5 xx xx xx xx

    title: System Administrator

    postalAddress: 

    initials: JD

    dn: cn=example,ou=groups,dc=example,dc=com

    objectClass: posixGroup

    cn: example

    gidNumber: 10000

Now we create our database and settings, along with the standard 

"inetOrgPerson" LDAP schema:

.. code-block:: none

    $ sudo ldapadd -Y EXTERNAL -H ldapi:/// -f backend.example.com.ldif

    SASL/EXTERNAL authentication started

    SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth

    SASL SSF: 0

    adding new entry "cn=module,cn=config"

    adding new entry "olcDatabase=hdb,cn=config"

    $ sudo ldapadd -x -D cn=admin,dc=example,dc=com -W -f frontend.example.com.ldif

    Enter LDAP Password: secret

    adding new entry "dc=example,dc=com"

    adding new entry "cn=admin,dc=example,dc=com"

    adding new entry "ou=people,dc=example,dc=com"

    adding new entry "ou=groups,dc=example,dc=com"

    adding new entry "uid=john,ou=people,dc=example,dc=com"

    adding new entry "cn=example,ou=groups,dc=example,dc=com"

In the above we first created the database and defined a method to access it.

As you see, in the second ldapadd command we now need to provide the admin 

password `secret` to do further changes, and will need to use it in all further

commands too.

The second command creates a classic `inetOrgPerson` schema, with a user

"John Doe" (Common Name) who has a uid "john" and various other information

commonly part of a UNIX system account. In fact the LDAP object type is called

posixAccount! User john is part of the Organizational Unit "people" in the

domain example.com.

You can verify that everything is working so far by searching for John:

.. code-block:: none

    $ ldapsearch -xLLL -b "ou=people,dc=example,dc=com" uid=john

    dn: uid=john,ou=people,dc=example,dc=com

    objectClass: inetOrgPerson

    objectClass: posixAccount

    objectClass: shadowAccount

    uid: john

    sn: Doe

    givenName: John

    cn: John Doe

    displayName: John Doe

    uidNumber: 1000

    gidNumber: 10000

    gecos: John Doe

    loginShell: /bin/bash

    homeDirectory: /home/john

    shadowExpire: -1

    shadowFlag: 0

    shadowWarning: 7

    shadowMin: 8

    shadowMax: 999999

    shadowLastChange: 10877

    mail: john.doe@example.com

    postalCode: 31000

    l: Toulouse

    o: Example

    mobile: +33 (0)6 xx xx xx xx

    homePhone: +33 (0)5 xx xx xx xx

    title: System Administrator

    postalAddress:

    initials: JD

If you look closely you see that the userPassword field is not shown. Don't 

worry! It is stored in the directory, it is just not shown in search results for

security reasons.

.. _auth_ldap_examples_add_user:

Adding a Drizzle user to LDAP

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You could just setup Drizzle to authenticate against standard LDAP accounts like

John Doe above. But the recommended way is to add a specific Drizzle schema.

You will find this in ``$DRIZZLE_ROOT/share/drizzle7/drizzle_openldap.ldif``.

You can add it to your LDAP schema like this:

.. code-block:: none

    $ sudo ldapadd -Y EXTERNAL -H ldapi:/// -f share/drizzle7/drizzle_openldap.ldif 

    SASL/EXTERNAL authentication started

    SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth

    SASL SSF: 0

    adding new entry "cn=drizzle,cn=schema,cn=config"

Now we can add a Drizzle user to our directory. At this point we will need to 

store the users Drizzle password. Note that Drizzle, just like MySQL, will

prefer to store and use a doubly hashed version of the user password. Other 

Drizzle authentication plugins, like auth_schema, do the same. (But some plugins

do not and Drizzle can use either, since it supports two different 

authentication protocols for this purpose). 

Drizzle 7.1 ships with a nice utility to calculate those hashes called

``drizzle_password_hash``. You simply give it the password and it outputs

the doubly hashed string:

.. code-block:: none

    $ bin/drizzle_password_hash secret

    14E65567ABDB5135D0CFD9A70B3032C179A49EE7

We will use this utility when creating the LDAP entry for our Drizzle user.

Note that the above value is different from what the LDAP directory as the

userPassword entry. The Unix or Posix way to store passwords is to just hash

them once. You can have a look in your ``/etc/shadow`` file to see what they

look like. Anyway, for this reason our Drizzle schema that we just added has

an additional field ``drizzleUserPassword`` to store the Drizzle encoded form

of the same password. (Or the passwords can also be different, but we will

assume most people like to use the same password.)

Since Drizzle 7.1 there is also a nice helper script included to create the ldif

records you need to add new Drizzle users to your LDAP. Using this script is

of course voluntary and you can use any LDAP manager tool you want. But we will

use it for this tutorial.

Let's create the user hingo:

.. code-block:: none

    $ 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

    $ cat hingo.example.com.ldif 

    dn: uid=hingo,ou=people,dc=example,dc=com                                                                                                                                           

    objectclass: top                                                                                                                                                                    

    objectclass: posixAccount

    objectclass: account

    objectclass: drizzleUser

    drizzleUserMysqlPassword: 14E65567ABDB5135D0CFD9A70B3032C179A49EE7

    uidNumber: 500

    gidNumber: 500

    uid: hingo

    homeDirectory: /home/hingo

    loginshell: /sbin/nologin

    userPassword: secret

    cn: hingo

If you want, you could use this as a template to further edit the entry.

Drizzle will only care about the `drizzleUserMySQLPassword`, `uid` and sometimes

(at your option) the `userPassword`. So you can freely edit the rest of the 

entries to suit you. For instance if this user will also be a user on your Linux 

system, make sure to set the loginshell to ``/bin/bash`` and check the uid and

gid numbers. The ``cn`` field is often used to store the full name of the person,

like "Henrik Ingo". (But this is not used by Drizzle.)

We now add the above user to the directory:

.. code-block:: none

    $ sudo ldapadd -x -D cn=admin,dc=example,dc=com -W -f hingo.example.com.ldif 

    Enter LDAP Password: 

    adding new entry "uid=hingo,ou=people,dc=example,dc=com"

.. _auth_ldap_examples_start_server:

Starting Drizzle Server and binding to the LDAP server

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is now time to start the Drizzle server with the needed options so that we

can use the LDAP directory for authentication services:

.. code-block:: none

    $ sbin/drizzled --plugin-remove=auth_all 

                    --plugin-add=auth_ldap 

                    --auth-ldap.bind-password=secret 

                    --auth-ldap.bind-dn="cn=admin,dc=example,dc=com" 

                    --auth-ldap.base-dn="ou=people,dc=example,dc=com"

`(Give all options on one line.)`

``bind-password`` and ``bind-dn`` are used by drizzled to bind to the LDAP

server. ``base-dn`` is the DN where our Drizzle users are stored.

.. _auth_ldap_examples_connect:

Connecting to Drizzle with the client

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We can now use a username and password from the LDAP directory when connecting 

to Drizzle:

.. code-block:: none

    $ bin/drizzle --user=hingo --password

    Enter password: 

    Welcome to the Drizzle client..  Commands end with ; or \g.

    Your Drizzle connection id is 2

    Connection protocol: mysql

    Server version: 2011.10.28.2459 Source distribution (drizzle-auth_ldap-fix-and-docs)

    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

    drizzle> 

.. _auth_ldap_examples_connect_clear_password:

Using the userPassword system password with Drizzle

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is also possible to use the password from the userPassword field when 

connecting with Drizzle. This could be beneficial or necessary to allow

all users who already exist in the directory, but didn't have a 

drizzleUserPassword set for them, to connect to Drizzle.

To do this, you have to give the extra option ``--protocol mysql-plugin-auth``

to the drizzle client. This will tell the drizzle client to send the password

in cleartext to the server, using the MySQL old-password protocol.

We could use this to connect to Drizzle with the username john, that

we added in the beginning of this tutorial.

.. code-block:: none

    $ drizzle --password --protocol mysql-plugin-auth --user=john

    Enter password: 

    Welcome to the Drizzle client..  Commands end with ; or \g.

    Your Drizzle connection id is 2

    Connection protocol: mysql-plugin-auth

    Server version: 2011.10.28.2459 Source distribution (drizzle-auth_ldap-fix-and-docs)

    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

    drizzle> 

.. note::

   Using cleartext passwords is **not recommended**. Please note that

   the connection between drizzle client and drizzled server is completely

   unencrypted, so other people on your network could easily find out the

   password if this method is used.

.. _auth_ldap_limitations:

Limitations

-----------

The option ``LDAP_SCOPE_ONELEVEL`` option is used when searching the LDAP 

directory. This means you must specify the full base-dn. For instance, if

you have users defined in the dn ``ou=people,dn=example,dn=com`` authentication

will fail if you only specify ``dn=example,dn=com``. A consequence of this is

that all your Drizzle users must belong to the same LDAP organizationalUnit.

This is currently a fixed option and can only be changed by editing source code. 

However, there is no reason why it couldn't be a configurable option to also

allow multi level searches. Please contact the Drizzle developers if you have

such needs. (See :doc:`/help`)

.. _auth_ldap_authors:

Authors

-------

:Code: Eric Day, Edward "Koko" Konetzko, Henrik Ingo

:Documentation: Henrik Ingo

.. _auth_ldap_version:

Version

-------

This documentation applies to **auth_ldap 0.2**.

To see which version of the plugin a Drizzle server is running, execute:

.. code-block:: mysql

   SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='auth_ldap'

Changelog

---------

v0.2

^^^^

* Add proper documentation.

* Fix various bugs found while documenting, including:

* drizzle_create_ldap_user would append a counter at the end of each username, such as hingo0. Now it's just the username.

* LDAP directory is now searched for uid field, not cn.

* Change default value of --auth-ldap.mysql-password-attribute to drizzleMysqlUserPassword.

* --auth-ldap.bind-db was changed to --auth-ldap.bind-dn

* Variable auth_ldap_bind_password is no longer shown in SHOW VARIABLES.

v0.1

^^^^

* First release.

.. [1] Configuration scripts courtesy of `Ubuntu OpenLDAP server tutorial <https://help.ubuntu.com/11.04/serverguide/C/openldap-server.html>`_