# Paddle
[![hex.pm version](https://img.shields.io/hexpm/v/paddle.svg)](https://hex.pm/packages/paddle)
[![Build Status](https://travis-ci.org/ClubNix/paddle.svg?branch=master)](https://travis-ci.org/ClubNix/paddle)
[![Deps Status](https://beta.hexfaktor.org/badge/all/github/ClubNix/paddle.svg)](https://beta.hexfaktor.org/github/ClubNix/paddle)
[![Prod Deps Status](https://beta.hexfaktor.org/badge/prod/github/ClubNix/paddle.svg)](https://beta.hexfaktor.org/github/ClubNix/paddle)
[![Inline docs](http://inch-ci.org/github/ClubNix/paddle.svg)](http://inch-ci.org/github/ClubNix/paddle)
A library simplifying LDAP usage in Elixir projects.
[Documentation](https://hexdocs.pm/paddle/Paddle.html)
## Why another LDAP library?
If you want to communicate with an LDAP server in Elixir, you probably know
that there are other libraries out there. However, I didn't find one that
suited me:
- The [`:eldap`](http://erlang.org/doc/man/eldap.html) library is great, but
very low-level, with no high-level features.
- [EctoLdap](https://github.com/jeffweiss/ecto_ldap) is very interesting, but I
needed the add / modify / delete operations (in fact, I even wanted to do an
Ecto adapter at first).
- [Exldap](https://github.com/jmerriweather/exldap) and
[LDAPEx](https://github.com/OvermindDL1/ldap_ex) are both a translation of
the LDAP `:eldap` in Elixir, which is nice, but are still missing some
higher-level functionalities.
## Usage
Once installed and configured, it allows you to quickly authenticate users:
```elixir
iex> Paddle.authenticate("myUser", "password")
:ok
```
Get meaningful informations using [paddle class objects](https://hexdocs.pm/paddle/Paddle.Class.html):
```elixir
iex> Paddle.get %Paddle.PosixAccount{uid: "myUser"}
{:ok,
[%Paddle.PosixAccount{cn: ["My User"], description: nil,
gecos: ["My User,,,,"], gidNumber: ["120"],
homeDirectory: ["/home/myuser"], host: nil, l: nil,
loginShell: ["/bin/bash"], o: nil, ou: nil, seeAlso: nil, uid: ["myUser"],
uidNumber: ["500"],
userPassword: ["{SSHA}AIzygLSXlArhAMzddUriXQxf7UlkqopP"]}]}
```
Or just get informations about anything:
```elixir
iex> Paddle.get base: [ou: "People"], filter: [objectClass: "organizationalUnit"]
{:ok,
[%{"dn" => "ou=People,dc=test,dc=com",
"objectClass" => ["top", "organizationalUnit"], "ou" => ["People"]}]}
```
Add, delete, modify operations are supported. If you want to know more, just
go to [the documentation](https://hexdocs.pm/paddle/Paddle.html).
## Installation
The package can be installed as:
1. Add `paddle` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[{:paddle, "~> 0.1.0"}]
end
```
2. Ensure `paddle` is started before your application:
```elixir
def application do
[applications: [:paddle]]
end
```
3. Add your configuration in your config files:
```elixir
config :paddle, Paddle,
host: "ldap.my-organisation.org",
base: "dc=myorganisation,dc=org",
ssl: true,
port: 636
```
For more configurations, see the [`Paddle` module docmumentation](https://hexdocs.pm/paddle/Paddle.html#module-configuration).
## Testing
If you want to test this application, you can use the linux commands
described in the [.travis.yml](.travis.yml) file in the
`before_script` block to start a local test LDAP server.
Keep in mind that you may need to change the
[.travis/ldap/slapd.conf](.travis/ldap/slapd.conf) for your system by changing
some configuration paths.
If you want to add some more data to the test server, please feel free
to issue a pull request.