Documentation of LDAP authentication support. Fixes #5348

docs/en_US/enabling_ldap_authentication.rst

@@ -0,0 +1,72 @@
+.. _enabling_ldap_authentication:
+
+**************************************************
+`Enabling LDAP Authentication for pgAdmin`:index:
+**************************************************
+
+To enable LDAP authentication for pgAdmin, you must configure the LDAP
+settings in the *config_local.py* or *config_distro.py* file on the system where
+pgAdmin is installed in Server mode. You can copy these settings from *config.py*
+file and modify the values for the following parameters:
+
+.. csv-table::
+   :header: "**Parameter**", "**Description**"
+   :class: longtable
+   :widths: 35, 55
+
+   "AUTHENTICATION_SOURCES","The default value for this parameter is *internal*.
+   To enable LDAP authentication, you must include *ldap* in the list of values
+   for this parameter. you can modify the value as follows:
+
+   * [‘ldap’]: pgAdmin will use only LDAP authentication.
+
+   * [‘ldap’, ‘internal’]: pgAdmin will first try to authenticate the user through
+     LDAP. If that authentication fails, then internal user entries of pgAdmin will be used for authentication.
+
+   * [‘internal’, ‘ldap’]: pgAdmin will first try to authenticate the user through internal user entries. If that authentication fails, then LDAP authentication will be used."
+   "LDAP_AUTO_CREATE_USER", "Specifies if you want to automatically create a pgAdmin
+   user corresponding to the LDAP user credentials. Please note that LDAP password
+   is not stored in the pgAdmin database."
+   "LDAP_CONNECTION_TIMEOUT","Specifies the connection timeout (in seconds) for LDAP
+   authentication."
+   "LDAP_SERVER_URI", "An LDAP URI is a combination of connection protocol
+   (ldap or ldaps), IP address/hostname and port of the directory server that you
+   want to connect to. For example, 'ldap://172.16.209.35:389' is a valid
+   LDAP_SERVER_URI where ldap is the connection protocol, 172.16.209.35 is the IP
+   address and 389 is the port. Port 636 is used for the ldaps communication protocol."
+   "LDAP_BASE_DN","Specifies the base DN from where a server will start the search
+   for users. For example, an LDAP search for any user will be performed by the server
+   starting at the base DN (dc=example,dc=com). When the base DN matches, the full
+   DN (cn=admin,dc=example,dc=com) is used to bind with the supplied password."
+   "LDAP_USERNAME_ATTRIBUTE","Specifies the LDAP attribute that contains the
+   usernames. For LDAP authentication, you need to enter the value of that
+   particular attribute as username. For example, if you set the value of
+   LDAP_USERNAME_ATTRIBUTE as ‘cn’ and you have defined 'cn=admin' in your LDAP server
+   entries, you should be able to authenticate by entering ‘admin’ in the 
+   *Email Address / Username* field and its corresponding password in the *Password* 
+   field."
+   "LDAP_SEARCH_BASE_DN","Specifies an element of the search request that works in
+   conjunction with the LDAP search scope to define the subtree of entries that
+   should be considered when processing the search request. You can use this parameter
+   for limiting the search request to a specific group of users."
+   "LDAP_SEARCH_FILTER","Defines the criteria to retrieve matching entries in an
+   LDAP search request. For example, LDAP_SEARCH_FILTER = '(objectclass=HR)’ setting
+   searches only for users having HR as their objectClass attribute."
+   "LDAP_SEARCH_SCOPE","Indicates the set of entries at or below the Base DN that
+   maybe considered as potential matches for a search request. You can specify the
+   scope of a search as either a *base*, *level*, or *subtree* search. A *base* search
+   limits the search to the base object. A *level* search is restricted to the immediate
+   children of a base object, but excludes the base object itself. A *subtree* search
+   includes all child objects as well as the base object."
+   "LDAP_USE_STARTTLS","Specifies if you want to use Transport Layer Security (TLS)
+   for secure communication between LDAP clients and LDAP servers. If you specify
+   the connection protocol in *LDAP_SERVER_URI* as *ldaps*, this parameter is ignored."
+   "LDAP_CA_CERT_FILE","Specifies the path to the trusted CA certificate file. This
+   parameter is applicable only if you are using *ldaps* as connection protocol and
+   you have set *LDAP_USE_STARTTLS* parameter to *True*."
+   "LDAP_CERT_FILE","Specifies the path to the server certificate file. This parameter
+   is applicable only if you are using *ldaps* as connection protocol and you have
+   set *LDAP_USE_STARTTLS* parameter to *True*."
+   "LDAP_KEY_FILE","Specifies the path to the server private key file. This parameter
+   is applicable only if you are using *ldaps* as connection protocol and you have
+   set *LDAP_USE_STARTTLS* parameter to *True*."

docs/en_US/getting_started.rst

@@ -35,6 +35,7 @@ Mode is pre-configured for security.
    login
    user_management
    change_user_password
+   enabling_ldap_authentication
 
 
 .. note:: Pre-compiled and configured installation packages are available for

docs/en_US/login.rst

@@ -10,13 +10,28 @@ Use the *Login* dialog to log in to pgAdmin:
     :alt: pgAdmin login dialog
     :align: center
 
-Use the fields in the *Login* dialog to authenticate your connection:
+Use the fields in the *Login* dialog to authenticate your connection. There are
+two ways to authenticate your connection:
 
-* Provide the email address associated with your account in the *Email Address*
-  field.
-* Provide your password in the *Password* field.
-* Click the *Login* button to securely log into pgAdmin.
-* Please note that, if the pgAdmin server is restarted then you will be logged out. You need to re-login to continue.
+- From pgAdmin version 4.21 onwards, support for LDAP authentication
+  has been added. If LDAP authentication has been enabled for your pgAdmin
+  application, you can use your LDAP credentials to log in to pgAdmin:
+
+  * Provide the LDAP username in the *Email Address/Username* field.
+
+  * Provide your LDAP password in the Password field.
+
+- Alternatively, you can use the following information to log in to pgAdmin:
+
+  * Provide the email address associated with your account in the
+    *Email Address/Username* field.
+
+  * Provide your password in the *Password* field.
+
+Click the *Login* button to securely log into pgAdmin.
+
+Please note that if the pgAdmin server is restarted, then you will be logged
+out. You need to re-login to continue.
 
 Recovering a Lost Password
 **************************
@@ -37,3 +52,7 @@ to launch a password recovery utility.
 If you have forgotten the email associated with your account, please contact
 your administrator.
 
+Please note that your LDAP password cannot be recovered using this dialog. If
+you enter your LDAP username in the *Email Address/Username* field, and then
+enter your email to recover your password, an error message will be displayed
+asking you to contact the LDAP administrator to recover your LDAP password.

docs/en_US/release_notes_4_21.rst

@@ -15,6 +15,7 @@ New features
 | `Issue #5181 <https://redmine.postgresql.org/issues/5181>`_ -  Added support for parameter toast_tuple_target and parallel_workers of the table.
 | `Issue #5263 <https://redmine.postgresql.org/issues/5263>`_ -  Added support of Foreign Tables to the Schema Diff.
 | `Issue #5264 <https://redmine.postgresql.org/issues/5264>`_ -  Added support of Packages, Sequences and Synonyms to the Schema Diff.
+| `Issue #5348 <https://redmine.postgresql.org/issues/5348>`_ -  Documentation of LDAP authentication support.
 | `Issue #5353 <https://redmine.postgresql.org/issues/5353>`_ -  Added an option to prevent a browser tab being opened at startup.
 | `Issue #5399 <https://redmine.postgresql.org/issues/5399>`_ -  Warn the user if an unsupported, deprecated or unknown browser is detected.
 

docs/en_US/user_management.rst

@@ -5,12 +5,12 @@
 *******************************
 
 When invoking pgAdmin in desktop mode, a password is randomly generated, and
-then ignored.  If you install pgAdmin in server mode, you will be prompted for
+then ignored. If you install pgAdmin in server mode, you will be prompted for
 an administrator email and password for the pgAdmin client.
 
 When you authenticate with pgAdmin, the server definitions associated with that
 login role are made available in the tree control.  An administrative user can
-use the *User Management* dialog to
+use the *User Management* dialog to:
 
 * add or delete pgAdmin roles
 * assign privileges
@@ -20,11 +20,13 @@ use the *User Management* dialog to
     :alt: pgAdmin user management window
     :align: center
 
-Use the *Filter by email* search field to find a user; enter a user's email
-address to find a user.  If the user exists, the *User Management* table will
-display the user's current information.
+Use the *Search* field to specify a criteria and review a list of users
+that matches with the specified criteria. You can enter a value that matches
+the following criteria types: *Authentication source*, *Username*, or *Email*.
+For example, you can enter *ldap* in the search box and only the records having
+*ldap* as authentication source will be displayed in the *User Management* table.
 
-To add a user, click *Add* to add new role.
+To add a user, click the Add (+) button at the top right corner.
 
 .. image:: images/add_user.png
     :alt: pgAdmin user management window add new user
@@ -32,10 +34,16 @@ To add a user, click *Add* to add new role.
 
 Provide information about the new pgAdmin role in the row:
 
-* Click in the *Email* field, and provide an email address for the user; this
-  address will be used to recover the password associated with the role should
-  the password be lost.
-* Use the drop-down listbox next to *Role* to select whether a user is an
+* Use the drop-down list box next to *Authentication source* field to select the
+  type of authentication that should be used for the user. If LDAP
+  authentication is not enabled for pgAdmin, then *Authentication source* field
+  is disabled.
+* Click in the *Username* field, and provide a username for the user. This field
+  is enabled only if you select *ldap* as authentication source. If you select
+  *internal* as authentication source, your email address is displayed in the
+  username field.
+* Click in the *Email* field, and provide an email address for the user.
+* Use the drop-down list box next to *Role* to select whether a user is an
   *Administrator* or a *User*.
 
    * Select *Administrator* if the user will have administrative privileges
@@ -46,8 +54,10 @@ Provide information about the new pgAdmin role in the row:
   active; the default is *Yes*. Use this switch to disable account activity
   without deleting an account.
 * Use the *New password* field to provide the password associated with the user
-  specified in the *Email* field.
-* Re-enter the password in the *Confirm password* field.
+  specified in the *Email* field. This field is disabled if you select *ldap*
+  as authentication source since LDAP password is not stored in the pgAdmin database.
+* Re-enter the password in the *Confirm password* field. This field is disabled
+  if you select *ldap* as authentication source.
 
 To discard a user, and revoke access to pgAdmin, click the trash icon to the
 left of the row and confirm deletion in the *Delete user?* dialog.
@@ -58,5 +68,3 @@ users, but otherwise have the same capabilities as those with the *User* role.
 * Click the *Help* button (?) to access online help.
 * Click the *Close* button to save work. You will be prompted to return to the
   dialog if your selections cannot be saved.
-
-