docs: Expand on LDAP config; try to clarify "username" concept.

The term "username" confusingly refers both to the Django concept of
"username" (meaning "the name the user types into the login form") and
a concept the admin presumably already has in their existing
environment; which may or may not be the same thing, and in fact this
is where we document the admin's choice of whether and how they should
correspond.  The Django concept in particular isn't obvious, and is
counterintuitive when it means something like an email address.

Explicitly explain the Django "username" concept, under the name of
"Zulip username" to take responsibility for our choice of how it's
exposed in the settings interface.  Then use an explicit qualifier,
like "LDAP username", whenever referring to some other notion of
username.  And make a pass over this whole side of the instructions,
in particular for consistent handling of these concepts.

docs/production/authentication-methods.md

@@ -52,30 +52,38 @@ In either configuration, you will need to do the following:
      `auth_ldap_bind_password`.  For example: `auth_ldap_bind_password
      = abcd1234`.
 
-2. Tell Zulip how to map the information it needs about users from how
-   it's stored in your LDAP server.  There are three supported ways to
-   setup the username and/or email mapping:
+2. Decide how you want to map the information in your LDAP database to
+   users' experience in Zulip.  For each Zulip user, two closely
+   related concepts are:
+   * their **email address**.  Zulip needs this in order to send, for
+     example, a notification when they're offline and another user
+     sends a PM.
+   * their **Zulip username**.  This means the name the user types into the
+     Zulip login form.  You might choose for this to be the user's
+     email address (`sam@example.com`), or look like a traditional
+     "username" (`sam`), or be something else entirely, depending on
+     your environment.
 
-   A. If users' email addresses are in LDAP and used as username, set
-      ```
-      LDAP_APPEND_DOMAIN = None
-      AUTH_LDAP_USER_SEARCH to lookup users by email address
-      ```
+   Either or both of these might be an attribute of the user records
+   in your LDAP database.
 
-   B. If LDAP only has usernames but email addresses are of the form
-      `username@example.com`, you should set:
-      ```
-      LDAP_APPEND_DOMAIN = example.com and
-      AUTH_LDAP_USER_SEARCH to lookup users by username
-      ```
+3. Tell Zulip how to map the user information in your LDAP database to
+   the form it needs.  There are three supported ways to set up the
+   username and/or email mapping:
 
-   C. If LDAP usernames are completely unrelated to email addresses,
-      you should set:
-      ```
-      LDAP_EMAIL_ATTR = "email"
-      LDAP_APPEND_DOMAIN = None
-      AUTH_LDAP_USER_SEARCH to lookup users by username
-      ```
+   (A) Using email addresses as usernames, if LDAP has each user's
+      email address.  To do this, just set `AUTH_LDAP_USER_SEARCH` to
+      query by email address.
+
+   (B) Using LDAP usernames as Zulip usernames, with email addresses
+      formed consistently like `sam` -> `sam@example.com`.  To do
+      this, set `AUTH_LDAP_USER_SEARCH` to query by LDAP username, and
+      `LDAP_APPEND_DOMAIN = "example.com"`.
+
+   (C) Using LDAP usernames as Zulip usernames, with email addresses
+      taken from some other attribute in LDAP (for example, `email`).
+      To do this, set `AUTH_LDAP_USER_SEARCH` to query by LDAP
+      username, and `LDAP_EMAIL_ATTR = "email"`.
 
 You can quickly test whether your configuration works by running:
 ```

zproject/prod_settings_template.py

@@ -372,15 +372,15 @@ EMAIL_GATEWAY_IMAP_FOLDER = "INBOX"
 #
 # Zulip supports retrieving information about users via LDAP, and
 # optionally using LDAP as an authentication mechanism.
-#
-# For detailed instructions, see the Zulip documentation:
-#   https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap
 
 import ldap
 from django_auth_ldap.config import LDAPSearch, GroupOfNamesType, LDAPSearchUnion
 
 ########
 # LDAP integration, part 1: Connecting to the LDAP server.
+#
+# For detailed instructions, see the Zulip documentation:
+#   https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap
 
 # The LDAP server to connect to.  Setting this enables Zulip
 # automatically fetching each new user's name from LDAP.
@@ -399,23 +399,33 @@ AUTH_LDAP_BIND_DN = ""
 
 ########
 # LDAP integration, part 2: Mapping user info from LDAP to Zulip.
+#
+# For detailed instructions, see the Zulip documentation:
+#   https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap
 
 # The LDAP search query to find a given user.
 #
 # The arguments to `LDAPSearch` are (base DN, scope, filter).  In the
-# filter, the string `%(user)s` is a Python placeholder; the Zulip
-# server will replace this with the user's Zulip username.  For more
-# details and alternatives, see the Zulip documentation:
-#   https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap
+# filter, the string `%(user)s` is a Python placeholder.  The Zulip
+# server will replace this with the user's Zulip username, i.e. the
+# name they type into the Zulip login form.
+#
+# For more details and alternatives, see the documentation linked above.
 AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=users,dc=example,dc=com",
                                    ldap.SCOPE_SUBTREE, "(uid=%(user)s)")
 
-# If the value of a user's "uid" (or similar) property is not their email
-# address, specify the domain to append here.
+# Domain to combine with a user's username to figure out their email address.
+#
+# If users log in as e.g. "sam" when their email address is "sam@example.com",
+# set this to "example.com".  If users log in with their full email addresses,
+# leave as None; if the username -> email address mapping isn't so simple,
+# leave as None and see LDAP_EMAIL_ATTR.
 LDAP_APPEND_DOMAIN = None  # type: Optional[str]
 
-# If username and email are two different LDAP attributes, specify the
-# attribute to get the user's email address from LDAP here.
+# LDAP attribute to find a user's email address.
+#
+# Leave as None if users log in with their email addresses,
+# or if using LDAP_APPEND_DOMAIN.
 LDAP_EMAIL_ATTR = None  # type: Optional[str]
 
 # This map defines how to populate attributes of a Zulip user from LDAP.