A feature new in Zato 3.1 is the ability to connect to LDAP servers, including Active Directory instances, and this article covers basic administration as programming tasks involved in their usage from Python code.

Creating Connections

Connections can be easily created in web-admin. Navigate to Connections -> Outgoing -> LDAP and then click Create a new connection.

The same form works for both regular LDAP and AD — in the latter case, make sure that Auth type is set to NTLM.

The most important information is:

• User credentials
• Authentication type
• Server or servers to connect to

Note that if authentication type is not NTLM, user credentials can be provided using the LDAP syntax, e.g. uid=MyUser,ou=users,o=MyOrganization,dc=example,dc=com.

Right after creating a connection, be sure to set its password too — the password assigned by default is a randomly generated one.

Pinging

It is always prudent to ping a newly created connection to ensure that all the information entered was correct.

Note that if you have more than one server in a pool, then the first available one of them will be pinged — it is the whole pool that is pinged, not a particular part of it.

Active Directory as a REST service

As the first usage example, let's create a service that will translate JSON queries into LDAP lookups — given username or email the service will basic information about the person's account, such as first and last name.

Note that the conn object returned by client.get() below is capable of running any commands that its underlying Python library offers — in this case, we are only using searches but any other operation can also be used, e.g. add or modify as well.

# -*- coding: utf-8 -*-

from __future__ import absolute_import, division, print_function, unicode_literals

# stdlib
from json import loads

# Bunch
from bunch import bunchify

# Zato
from zato.server.service import Service

# Where in the directory we expect to find the user
search_base = 'cn=users, dc=example, dc=com'

# On input, we are looking users up by either username or email
search_filter = '(&(|(uid={user_info})(mail={user_info})))'

# On output, we are interested in username, first name, last name and the person's email
query_attributes = ['uid', 'givenName', 'sn', 'mail']

class ADService(Service):
    """ Looks up users in AD by their username or email.
    """
    class SimpleIO:
        input_required = 'user_info'
        output_optional = 'message', 'username', 'first_name', 'last_name', 'email'
        response_elem = None
        skip_empty_keys = True

    def handle(self):

        # Connection name to use
        conn_name = 'My AD Connection'

        # Get a handle to the connection pool
        with self.out.ldap[conn_name].conn.client() as client:

            # Get a handle to a particular connection
            with client.get() as conn:

                # Build a filter to find a user by
                user_info = self.request.input['user_info']
                user_filter = search_filter.format(user_info=user_info)

                # Returns True if query succeeds and has any information on output
                if conn.search(search_base, user_filter, attributes=query_attributes):

                    # This is where the actual response can be found
                    response = conn.entries

                    # In this case, we expect at most one user matching input criteria
                    entry = response[0]

                    # Convert to JSON so it is easier to handle
                    entry = entry.entry_to_json()

                    # Load from JSON to a Python dict
                    entry = loads(entry)

                    # Convert to a Bunch instance to get dot access to dictionary keys
                    entry = bunchify(entry['attributes'])

                    # Now, actually produce a JSON response. For simplicity's sake,
                    # assume that users have only one of email or other attributes.
                    self.response.payload.message = 'User found'
                    self.response.payload.username = entry.uid[0]
                    self.response.payload.first_name = entry.givenName[0]
                    self.response.payload.last_name = entry.sn[0]
                    self.response.payload.email = entry.mail[0]

                else:
                    # No business response = no such user found
                    self.response.payload.message = 'No such user'

After creating a REST channel, we can invoke the service from the command line:

$ curl "localhost:11223/api/get-user?user_info=MyOrganization\\MyUser" ; echo
{
    "message": "User found",
    "username": "MyOrganization\\MyUser",
    "first_name": "First",
    "last_name": "Last",    
    "email": "address@example.com"
}
$

Checking User Credentials

A recurrent task in enterprise integrations in checking user credentials on behalf of systems that are not able to connect to AD or LDAP themselves; for instance, because they do not support the LDAP protocol or because a particular architecture disallows for them to make direct connections to backend servers.

To support this use-case, a separate method was added to the Python API specifically to validate user credentials — the code below is everything that is needed to confirm if user credentials are valid:

...

def handle(self):

    # Connection name to use
    conn_name = 'My AD Connection'

    # Credentials to check
    username = 'myuser'
    password = 'mypassword'

    # Get a handle to the connection pool object
    with self.out.ldap[conn_name].conn.client() as client:

        # Check credentials using the pool's configuration
        is_valid = client.check_credentials(username, password)

        if is_valid:
            # Credentials are valid, act accordingly here
            ...

        else:
            # Invalid username or password, return an error here
            ...

Summary

Full support for LDAP and Active Directory connections was added in Zato 3.1, and the Python API exposed grants one access to all the operations possible — offering means to integrate with directories or making them communicate with other technologies or protocols is now just a matter of authoring a service and exposing it through a channel, such as REST or one of the other types that Zato supports.