From 17fcd47632ae8208701591dd70b4f36d1dfa9dbc Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 23 Sep 2024 10:10:54 +0200 Subject: [PATCH 1/6] docs: update text for user_search_base --- README.md | 22 ++++++++++++++++++++-- ldapauthenticator/ldapauthenticator.py | 20 +++++++++++++------- 2 files changed, 33 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9c636ce..407e6a0 100644 --- a/README.md +++ b/README.md @@ -219,13 +219,31 @@ otherwise. #### `LDAPAuthenticator.user_search_base` -Only used with `lookup_dn=True`. Defines the search base for looking up users -in the directory. +Only used with `lookup_dn=True` or with a configured `search_filter`. + +Defines the search base for looking up users in the directory. ```python c.LDAPAuthenticator.user_search_base = 'ou=People,dc=example,dc=com' ``` +LDAPAuthenticator will search all objects matching under this base where +the `user_attribute` is set to the current username to form the userdn. + +For example, if all users objects existed under the base +`ou=people,dc=wikimedia,dc=org`, and the username users use is set with +the attribute `uid`, you can use the following config: + +```python +c.LDAPAuthenticator.lookup_dn = True +c.LDAPAuthenticator.lookup_dn_search_filter = '({login_attr}={login})' +c.LDAPAuthenticator.lookup_dn_search_user = 'ldap_search_user_technical_account' +c.LDAPAuthenticator.lookup_dn_search_password = 'secret' +c.LDAPAuthenticator.user_search_base = 'ou=people,dc=wikimedia,dc=org' +c.LDAPAuthenticator.user_attribute = 'uid' +c.LDAPAuthenticator.lookup_dn_user_dn_attribute = 'cn' +``` + #### `LDAPAuthenticator.user_attribute` Only used with `lookup_dn=True`. Defines the attribute that stores a user's diff --git a/ldapauthenticator/ldapauthenticator.py b/ldapauthenticator/ldapauthenticator.py index 5ac656b..ac0631d 100644 --- a/ldapauthenticator/ldapauthenticator.py +++ b/ldapauthenticator/ldapauthenticator.py @@ -224,15 +224,22 @@ def _validate_bind_dn_template(self, proposal): default_value=None, allow_none=True, help=""" - Base for looking up user accounts in the directory, if `lookup_dn` is set to True. + Only used with `lookup_dn=True` or with a configured `search_filter`. - LDAPAuthenticator will search all objects matching under this base where the `user_attribute` - is set to the current username to form the userdn. - - For example, if all users objects existed under the base ou=people,dc=wikimedia,dc=org, and - the username users use is set with the attribute `uid`, you can use the following config: + Defines the search base for looking up users in the directory. + ```python + c.LDAPAuthenticator.user_search_base = 'ou=People,dc=example,dc=com' ``` + + LDAPAuthenticator will search all objects matching under this base where + the `user_attribute` is set to the current username to form the userdn. + + For example, if all users objects existed under the base + `ou=people,dc=wikimedia,dc=org`, and the username users use is set with + the attribute `uid`, you can use the following config: + + ```python c.LDAPAuthenticator.lookup_dn = True c.LDAPAuthenticator.lookup_dn_search_filter = '({login_attr}={login})' c.LDAPAuthenticator.lookup_dn_search_user = 'ldap_search_user_technical_account' @@ -240,7 +247,6 @@ def _validate_bind_dn_template(self, proposal): c.LDAPAuthenticator.user_search_base = 'ou=people,dc=wikimedia,dc=org' c.LDAPAuthenticator.user_attribute = 'uid' c.LDAPAuthenticator.lookup_dn_user_dn_attribute = 'cn' - c.LDAPAuthenticator.bind_dn_template = '{username}' ``` """, ) From a74e5cf1c12aa4991b7fdca43321908db13c4adf Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 23 Sep 2024 10:14:16 +0200 Subject: [PATCH 2/6] docs: update text for user_attribute --- README.md | 6 ++++-- ldapauthenticator/ldapauthenticator.py | 14 ++++++++++---- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 407e6a0..f8ffbe8 100644 --- a/README.md +++ b/README.md @@ -246,8 +246,10 @@ c.LDAPAuthenticator.lookup_dn_user_dn_attribute = 'cn' #### `LDAPAuthenticator.user_attribute` -Only used with `lookup_dn=True`. Defines the attribute that stores a user's -username in your directory. +Only used with `lookup_dn=True` or with a configured `search_filter`. + +Together with `user_search_base`, this attribute will be searched to +contain the username provided by the user in JupyterHub's login form. ```python # Active Directory diff --git a/ldapauthenticator/ldapauthenticator.py b/ldapauthenticator/ldapauthenticator.py index ac0631d..9bfc3cf 100644 --- a/ldapauthenticator/ldapauthenticator.py +++ b/ldapauthenticator/ldapauthenticator.py @@ -256,12 +256,18 @@ def _validate_bind_dn_template(self, proposal): default_value=None, allow_none=True, help=""" - Attribute containing user's name, if `lookup_dn` is set to True. + Only used with `lookup_dn=True` or with a configured `search_filter`. - See `user_search_base` for info on how this attribute is used. + Together with `user_search_base`, this attribute will be searched to + contain the username provided by the user in JupyterHub's login form. + + ```python + # Active Directory + c.LDAPAuthenticator.user_attribute = 'sAMAccountName' - For most LDAP servers, this is uid. For Active Directory, it is - sAMAccountName. + # OpenLDAP + c.LDAPAuthenticator.user_attribute = 'uid' + ``` """, ) From 6f4a961ab66b9a9d55379d6e5ac5d0c15c197c66 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 23 Sep 2024 10:16:03 +0200 Subject: [PATCH 3/6] docs: update text for lookup_dn_search_filter --- README.md | 8 ++++++-- ldapauthenticator/ldapauthenticator.py | 7 ++++++- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f8ffbe8..c68307e 100644 --- a/README.md +++ b/README.md @@ -261,8 +261,12 @@ c.LDAPAuthenticator.user_attribute = 'uid' #### `LDAPAuthenticator.lookup_dn_search_filter` -How to query LDAP for user name lookup, if `lookup_dn` is set to True. -Default value `'({login_attr}={login})'` should be good enough for most use cases. +Only used with `lookup_dn=True`. + +How to query LDAP for user name lookup. + +Default value `'({login_attr}={login})'` should be good enough for most +use cases. #### `LDAPAuthenticator.lookup_dn_search_user`, `LDAPAuthenticator.lookup_dn_search_password` diff --git a/ldapauthenticator/ldapauthenticator.py b/ldapauthenticator/ldapauthenticator.py index 9bfc3cf..8a5c354 100644 --- a/ldapauthenticator/ldapauthenticator.py +++ b/ldapauthenticator/ldapauthenticator.py @@ -276,7 +276,12 @@ def _validate_bind_dn_template(self, proposal): default_value="({login_attr}={login})", allow_none=True, help=""" - How to query LDAP for user name lookup, if `lookup_dn` is set to True. + Only used with `lookup_dn=True`. + + How to query LDAP for user name lookup. + + Default value `'({login_attr}={login})'` should be good enough for most + use cases. """, ) From 2a5159d3865e960f89c70d3d5efc9fa1d3980556 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 23 Sep 2024 10:17:02 +0200 Subject: [PATCH 4/6] docs: update text for lookup_dn_search_user --- README.md | 7 +++++-- ldapauthenticator/ldapauthenticator.py | 11 +++++++---- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c68307e..ca46295 100644 --- a/README.md +++ b/README.md @@ -270,8 +270,11 @@ use cases. #### `LDAPAuthenticator.lookup_dn_search_user`, `LDAPAuthenticator.lookup_dn_search_password` -Technical account for user lookup, if `lookup_dn` is set to True. -If both lookup_dn_search_user and lookup_dn_search_password are None, then anonymous LDAP query will be done. +Only used with `lookup_dn=True`. + +Technical account for user lookup. If both `lookup_dn_search_user` and +`lookup_dn_search_password` are None, then anonymous LDAP query will be +done. #### `LDAPAuthenticator.lookup_dn_user_dn_attribute` diff --git a/ldapauthenticator/ldapauthenticator.py b/ldapauthenticator/ldapauthenticator.py index 8a5c354..02209a4 100644 --- a/ldapauthenticator/ldapauthenticator.py +++ b/ldapauthenticator/ldapauthenticator.py @@ -290,10 +290,11 @@ def _validate_bind_dn_template(self, proposal): default_value=None, allow_none=True, help=""" - DN for a technical user account allowed to search for information about - provided username, if `lookup_dn` is set to True. + Only used with `lookup_dn=True`. - If both lookup_dn_search_user and lookup_dn_search_password are None, then anonymous LDAP query will be done. + Technical account for user lookup. If both `lookup_dn_search_user` and + `lookup_dn_search_password` are None, then anonymous LDAP query will be + done. """, ) @@ -302,7 +303,9 @@ def _validate_bind_dn_template(self, proposal): default_value=None, allow_none=True, help=""" - Technical account for user lookup, if `lookup_dn` is set to True. + Only used with `lookup_dn=True`. + + Password for a `lookup_dn_search_user`. """, ) From add246be5a7fe9c2278dde18c9bb7e2c16f5fe56 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 23 Sep 2024 10:22:23 +0200 Subject: [PATCH 5/6] docs: update text for lookup_dn_user_dn_attribute --- README.md | 4 +++- ldapauthenticator/ldapauthenticator.py | 8 ++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ca46295..65a3072 100644 --- a/README.md +++ b/README.md @@ -278,7 +278,9 @@ done. #### `LDAPAuthenticator.lookup_dn_user_dn_attribute` -Attribute containing user's name needed for building DN string, if `lookup_dn` is set to True. +Only used with `lookup_dn=True`. + +Attribute containing user's name needed for building DN string. See `user_search_base` for info on how this attribute is used. For most LDAP servers, this is username. For Active Directory, it is cn. diff --git a/ldapauthenticator/ldapauthenticator.py b/ldapauthenticator/ldapauthenticator.py index 02209a4..92b78ad 100644 --- a/ldapauthenticator/ldapauthenticator.py +++ b/ldapauthenticator/ldapauthenticator.py @@ -314,11 +314,11 @@ def _validate_bind_dn_template(self, proposal): default_value=None, allow_none=True, help=""" - Attribute containing user's name needed for building DN string, if `lookup_dn` is set to True. - - See `user_search_base` for info on how this attribute is used. + Only used with `lookup_dn=True`. - For most LDAP servers, this is username. For Active Directory, it is cn. + Attribute containing user's name needed for building DN string. See + `user_search_base` for info on how this attribute is used. For most LDAP + servers, this is username. For Active Directory, it is cn. """, ) From 0e9e43d72b856e8965219d203105ae3cf37daa79 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 23 Sep 2024 10:22:55 +0200 Subject: [PATCH 6/6] docs: update text for use_lookup_dn_username --- README.md | 6 ++++-- ldapauthenticator/ldapauthenticator.py | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 65a3072..b3e9762 100644 --- a/README.md +++ b/README.md @@ -291,9 +291,11 @@ If found, these will be available as `auth_state["user_attributes"]`. #### `LDAPAuthenticator.use_lookup_dn_username` -If set to True (the default) the username used to build the DN string is returned as the username when `lookup_dn` is True. +Only used with `lookup_dn=True`. -When authenticating on a Linux machine against an AD server this might return something different from the supplied UNIX username. In this case setting this option to False might be a solution. +If configured True (default value), the `lookup_dn_user_dn_attribute` +value used to build the LDAP user's DN string is also used as the +authenticated user's JuptyerHub username. #### `LDAPAuthenticator.search_filter` diff --git a/ldapauthenticator/ldapauthenticator.py b/ldapauthenticator/ldapauthenticator.py index 92b78ad..41380d1 100644 --- a/ldapauthenticator/ldapauthenticator.py +++ b/ldapauthenticator/ldapauthenticator.py @@ -376,9 +376,11 @@ def _observe_escape_userdn(self, change): True, config=True, help=""" - If set to true uses the `lookup_dn_user_dn_attribute` attribute as username instead of the supplied one. + Only used with `lookup_dn=True`. - This can be useful in an heterogeneous environment, when supplying a UNIX username to authenticate against AD. + If configured True (default value), the `lookup_dn_user_dn_attribute` + value used to build the LDAP user's DN string is also used as the + authenticated user's JuptyerHub username. """, )