docs: Updated LDAP Documentation (#1988)

* Updated LDAP Documentation * fixed a typo --------- Co-authored-by: Daniel Vaz Gaspar <danielvazgaspar@gmail.com>
dpgaspar · Feb 23, 2023 · 0132aad · 0132aad
1 parent c5e453e
commit 0132aad
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 3 deletions.
diff --git a/docs/config.rst b/docs/config.rst
@@ -56,6 +56,12 @@ Use config.py to configure the following parameters. By default it will use SQLL
 |                                        | AUTH_TYPE = 2                              |           |
 |                                        |                                            |           |
 |                                        | AUTH_LDAP_SERVER = "ldap://ldapserver.new" |           |
+|                                        |                                            |           |
+|                                        | For using LDAP over TLS, set the protocol  |           |
+|                                        | scheme to "ldaps" and set                  |           |
+|                                        | "AUTH_LDAP_USE_TLS = False"                |           |
++----------------------------------------+--------------------------------------------+-----------+
+| AUTH_LDAP_USE_TLS                      | Require the use of STARTTLS                |           |
 +----------------------------------------+--------------------------------------------+-----------+
 | AUTH_LDAP_BIND_USER                    | Define the DN for the user that will be    |   No      |
 |                                        | used for the initial LDAP BIND.            |           |
@@ -72,10 +78,11 @@ Use config.py to configure the following parameters. By default it will use SQLL
 |                                        | (Bool)                                     |           |
 +----------------------------------------+--------------------------------------------+-----------+
 | AUTH_LDAP_TLS_CACERTDIR                | CA Certificate directory to check peer     |   No      |
-|                                        | certificate                                |           |
+|                                        | certificate. Certificate files must be     |           |
+|                                        | PEM-encoded                                |           |
 +----------------------------------------+--------------------------------------------+-----------+
 | AUTH_LDAP_TLS_CACERTFILE               | CA Certificate file to check peer          |   No      |
-|                                        | certificate                                |           |
+|                                        | certificate. File must be PEM-encoded      |           |
 +----------------------------------------+--------------------------------------------+-----------+
 | AUTH_LDAP_TLS_CERTFILE                 | Certificate file for client auth           |   No      |
 |                                        | use with AUTH_LDAP_TLS_KEYFILE             |           |
@@ -344,4 +351,4 @@ causes users 1 and 2 to be registered with role ``Admin`` and rest with the role
 JMESPath expression allow more groups to be evaluated:
 ``email == 'user1@domain.com' && 'Admin' || (email == 'user2@domain.com' && 'Op' || 'Viewer')``
 
-For more example, see `specification <https://jmespath.org/specification.html>`_.
+For more example, see `specification <https://jmespath.org/specification.html>`_.
diff --git a/docs/security.rst b/docs/security.rst
@@ -154,6 +154,21 @@ You can give FlaskAppBuilder roles based on LDAP roles (note, this requires AUTH
     # force users to re-auth after 30min of inactivity (to keep roles in sync)
     PERMANENT_SESSION_LIFETIME = 1800
 
+TLS
+~~~
+
+For STARTTLS, configure an `ldap://` server and set `AUTH_LDAP_USE_TLS` to `True`::
+
+    AUTH_LDAP_SERVER = "ldap://ldap.example.com"
+    AUTH_LDAP_USE_TLS = True
+
+For LDAP over TLS (ldaps), configure the server with the `ldaps://` scheme and set `AUTH_LDAP_USE_TLS` to `False`::
+
+    AUTH_LDAP_SERVER = "ldaps://ldap.example.com"
+    AUTH_LDAP_USE_TLS = False
+
+Additional LDAP/TLS Options, including CA certificate settings and client authentication, can be found in the :doc:`config`.
+
 Authentication: OAuth
 ---------------------