Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Make a pass over LDAP config/setup docs. 

Expand on a few things that tend to confuse people (especially the
`%(user)s` thing); move the `LDAPSearchUnion` example out to docs;
adjust the instructions to fit a bit better in their new docs/ home.
This commit is contained in:
Greg Price 2018-09-25 15:05:58 -07:00 committed by Tim Abbott
parent e7737c6342
commit 6f23d2f691
2 changed files with 36 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/production/authentication-methods.md
View File

@ -81,23 +81,35 @@ You can quickly test whether your configuration works by running:
``` ```
./manage.py query_ldap username@example.com ./manage.py query_ldap username@example.com
``` ```
From the root of your Zulip installation; if your configuration is working from the root of your Zulip installation. If your configuration is working,
that will output the full name for your user. that will output the full name for your user.
**If you are using LDAP for authentication**, you will need to enable **If you are using LDAP for authentication**: you will need to enable
the zproject.backends.ZulipLDAPAuthBackend auth backend in the `zproject.backends.ZulipLDAPAuthBackend` auth backend, in
AUTHENTICATION_BACKENDS above. After doing so, you should be able `AUTHENTICATION_BACKENDS` in `/etc/zulip/settings.py`. After doing
to login to Zulip by entering your email address and LDAP password so (and as always [restarting the Zulip server](settings.html) to ensure
on the Zulip login form. your settings changes take effect), you should be able to log into
Zulip by entering your email address and LDAP password on the Zulip
login form.
**If you are using LDAP to populate names in Zulip**, once you finish **If you are using LDAP to populate names in Zulip**: once you finish
configuring this integration, you will need to run: configuring this integration, you will need to run:
``` ```
./manage.py sync_ldap_user_data ./manage.py sync_ldap_user_data
``` ```
To sync names for existing users; you may want to run this in a cron to sync names for existing users. You may want to run this in a cron
job to pick up name changes made on your LDAP server. job to pick up name changes made on your LDAP server.
### Multiple LDAP searches
To do the union of multiple LDAP searches, use `LDAPSearchUnion`. For example:
```
AUTH_LDAP_USER_SEARCH = LDAPSearchUnion(
LDAPSearch("ou=users,dc=example,dc=com", ldap.SCOPE_SUBTREE, "(uid=%(user)s)"),
LDAPSearch("ou=otherusers,dc=example,dc=com", ldap.SCOPE_SUBTREE, "(uid=%(user)s)"),
)
```
## Apache-based SSO with `REMOTE_USER` ## Apache-based SSO with `REMOTE_USER`
If you have any existing SSO solution where a preferred way to deploy If you have any existing SSO solution where a preferred way to deploy

26
zproject/prod_settings_template.py
View File

@ -382,12 +382,13 @@ from django_auth_ldap.config import LDAPSearch, GroupOfNamesType, LDAPSearchUnio
######## ########
# LDAP integration, part 1: Connecting to the LDAP server. # LDAP integration, part 1: Connecting to the LDAP server.
# URI of your LDAP server. If set, LDAP is used to prepopulate a user's name in # The LDAP server to connect to. Setting this enables Zulip
# Zulip. Example: "ldaps://ldap.example.com" # automatically fetching each new user's name from LDAP.
# Example: "ldaps://ldap.example.com"
AUTH_LDAP_SERVER_URI = "" AUTH_LDAP_SERVER_URI = ""
# This DN will be used to bind to your server. If unset, anonymous # The DN of the user to bind as (i.e., authenticate as) in order to
# binds are performed. # query LDAP. If unset, Zulip does an anonymous bind.
AUTH_LDAP_BIND_DN = "" AUTH_LDAP_BIND_DN = ""
# Passwords and secrets are not stored in this file. The password # Passwords and secrets are not stored in this file. The password
@ -399,14 +400,15 @@ AUTH_LDAP_BIND_DN = ""
######## ########
# LDAP integration, part 2: Mapping user info from LDAP to Zulip. # LDAP integration, part 2: Mapping user info from LDAP to Zulip.
# Specify the search base and the property to filter on that corresponds to the # The LDAP search query to find a given user.
# username. One can use LDAPSearchUnion to do the union of multiple LDAP searches. #
# 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
AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=users,dc=example,dc=com", AUTH_LDAP_USER_SEARCH = LDAPSearch("ou=users,dc=example,dc=com",
ldap.SCOPE_SUBTREE, "(uid=%(user)s)") ldap.SCOPE_SUBTREE, "(uid=%(user)s)")
#AUTH_LDAP_USER_SEARCH = LDAPSearchUnion(
# LDAPSearch("ou=users,dc=example,dc=com", ldap.SCOPE_SUBTREE, "(uid=%(user)s)"),
# LDAPSearch("ou=otherusers,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 # If the value of a user's "uid" (or similar) property is not their email
# address, specify the domain to append here. # address, specify the domain to append here.
@ -417,6 +419,10 @@ LDAP_APPEND_DOMAIN = None # type: Optional[str]
LDAP_EMAIL_ATTR = None # type: Optional[str] LDAP_EMAIL_ATTR = None # type: Optional[str]
# This map defines how to populate attributes of a Zulip user from LDAP. # This map defines how to populate attributes of a Zulip user from LDAP.
#
# The format is `zulip_name: ldap_name`; each entry maps a Zulip
# concept (on the left) to the LDAP attribute name (on the right) your
# LDAP database uses for the same concept.
AUTH_LDAP_USER_ATTR_MAP = { AUTH_LDAP_USER_ATTR_MAP = {
# full_name is required; common values include "cn" or "displayName". # full_name is required; common values include "cn" or "displayName".
"full_name": "cn", "full_name": "cn",