Exldap

A module for working with LDAP from Elixir

Installation

The package can be installed as:

1. Add exldap to your list of dependencies in mix.exs:

        def deps do
          [{:exldap, "~> 0.6"}]
        end

1. Ensure exldap is started before your application:

        def application do
          [applications: [:exldap]]
        end

1. Optionally add 'config\config.secret.exs' file with:

        import Config

        config :exldap, :settings,
          server: <server address>,
          base: "DC=example,DC=com",
          port: 636,
          ssl: true,
          user_dn: <user distinguished name>,
          password: <password>,
          search_timeout: 1000 # optionally set a search timeout in milliseconds, default is infinity

Usage with configuration set in config.exs

# the default_timeout is infinity


{:ok, connection} = Exldap.connect(TIMEOUT \\ default_timeout) # optionally set the maximum time in milliseconds that each server request may take


{:ok, search_results} = Exldap.search_field(connection, "cn", "test123")

{:ok, first_result} = search_results |> Enum.fetch(0)

result = Exldap.search_attributes(first_result, "displayName")

Usage without configuration

# the default_timeout is infinity


{:ok, connection} = Exldap.connect("SERVERADDRESS", 636, true, "CN=test123,OU=Accounts,DC=example,DC=com", "PASSWORD", TIMEOUT \\ default_timeout)

{:ok, search_results} = Exldap.search_field(connection, "OU=Accounts,DC=example,DC=com", "cn", "useraccount")

{:ok, first_result} = search_results |> Enum.fetch(0)

result = Exldap.search_attributes(first_result, "displayName")

Change a password

# Active Directory: writes unicodePwd directly, needs SSL

:ok = Exldap.change_password(connection, "CN=test123,OU=Accounts,DC=example,DC=com", "NEW_PASSWORD")
:ok = Exldap.change_password(connection, "CN=test123,OU=Accounts,DC=example,DC=com", "OLD_PASSWORD", "NEW_PASSWORD")

# OpenLDAP and other RFC 3062 servers: password modify extended operation

:ok = Exldap.modify_password(connection, "uid=test123,ou=People,dc=example,dc=org", "NEW_PASSWORD")
:ok = Exldap.modify_password(connection, "uid=test123,ou=People,dc=example,dc=org", "OLD_PASSWORD", "NEW_PASSWORD")

Verify credentials with configuration set in config.exs

# the default_timeout is infinity


{:ok, connection} = Exldap.open(TIMEOUT \\ default_timeout) # optionally set the maximum time in milliseconds that each server request may take


case Exldap.verify_credentials(connection, "CN=test123,OU=Accounts,DC=example,DC=com", "PASSWORD") do
  :ok -> IO.puts "Successfully connected"
  _ -> IO.puts "Failed to connect"
end

Verify credentials without configuration

# the default_timeout is infinity


{:ok, connection} = Exldap.open("SERVERADDRESS", 636, true, TIMEOUT \\ default_timeout)

case Exldap.verify_credentials(connection, "CN=test123,OU=Accounts,DC=example,DC=com", "PASSWORD") do
  :ok -> IO.puts "Successfully connected"
  _ -> IO.puts "Failed to connect"
end

Use SSL, validating certificates, from configuration

        import Config

        config :exldap, :settings,
          server: <server address>,
          base: "DC=example,DC=com",
          port: 636,
          ssl: true,
          sslopts: [cacertfile: 'path/to/ca.pem', verify: verify_peer]
          user_dn: <user distinguished name>,
          password: <password>,
          search_timeout: 1000

Use SSL, validating certificates, from configuration

        sslopts=[cacertfile: 'path/to/ca.pem', verify: verify_peer]
        {:ok, connection} = Exldap.connect("SERVERADDRESS", 636, true, "CN=test123,OU=Accounts,DC=example,DC=com", "PASSWORD", timeout, sslopts)
        ...

Running the tests

test/exldap_unit_test.exs runs without a server. The integration tests in test/exldap_test.exs need an Active Directory. A Samba AD domain controller and an OpenLDAP server are provided via Docker, with the accounts the tests expect provisioned by test/ad/10-provision-test-users.sh and test/openldap/50-test-users.ldif:

docker compose up -d --wait   # Samba AD on :389/:636, OpenLDAP on :1389/:1636 (self-signed certs)

mix test                      # settings come from config/test.exs

docker compose down -v        # discard the domain

To run against a real directory instead, create config/config.secret.exs with your own :settings and :test keys (see config/test.exs). Tests tagged :real_ad cover behaviour Samba does not implement, such as approximate matching, and run with mix test --include real_ad.

Note: if you upgrade Erlang/OTP, recompile this library with mix deps.compile exldap --force. The record shapes in :eldap are read at compile time.