From 47c6037a28c6e17412fb5cbde527eebc91ac1ba3 Mon Sep 17 00:00:00 2001
From: Laurent Peuch <cortex@worlddomination.be>
Date: Sat, 12 Aug 2017 12:04:05 +0200
Subject: [PATCH] [doc] start documentation on ldap

---
 doc/ldap.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 doc/ldap.rst

diff --git a/doc/ldap.rst b/doc/ldap.rst
new file mode 100644
index 00000000..530fef9f
--- /dev/null
+++ b/doc/ldap.rst
@@ -0,0 +1,50 @@
+Common LDAP operation (for YunoHost but not only)
+=================================================
+
+Moulinette is deeply integrated with LDAP which is used for a series of things
+like:
+
+* storing users
+* storing domains (for users emails)
+* SSO
+
+This page document how to uses it on a programming side in YunoHost.
+
+Getting access to LDAP in a command
+-----------------------------------
+
+To get access to LDAP you need to authenticate against it, for that you need to
+declare you command with requiring authentication in the :ref:`actionsmap` this way:
+
+::
+
+    configuration:
+        authenticate: all
+
+
+Here is a complete example:
+
+::
+
+    somecommand:
+        category_help: ..
+        actions:
+
+            ### somecommand_stuff()
+            list:
+                action_help: ...
+                api: GET /...
+                configuration:
+                    authenticate: all
+
+This will prompt the user for a password in CLI.
+
+If you only need to **read** LDAP (and not modify it, for example by listing
+domains), then you prevent the need for a password by using the
+`ldap-anonymous` authenticator this way:
+
+::
+
+    configuration:
+        authenticate: all
+        authenticator: ldap-anonymous