Package: jupyterhub-ldapauthenticator-refresh
ldapauthenticatorSimple LDAP Authenticator Plugin for JupyterHubPlease note that this repository is participating in a study into sustainability
of open source projects. Data will be gathered about this repository for
approximately the next 12 months, starting from 2021-06-11.Data collected will include number of contributors, number of PRs, time taken to
close/merge these PRs, and issues closed.For more information, please visitthe informational pageor download theparticipant information sheet.InstallationYou can install it from pip with:pip install jupyterhub-ldapauthenticator...or using conda with:conda install -c conda-forge jupyterhub-ldapauthenticatorLogging people outIf you make any changes to JupyterHub's authentication setup that changes
which group of users is allowed to login (such as changingallowed_groupsor even just turning on LDAPAuthenticator), youmustchange the
jupyterhub cookie secret, or users who were previously logged in and did
not log out would continue to be able to log in!You can do this by deleting thejupyterhub_cookie_secretfile. Note
that this will log outallusers who are currently logged in.UsageYou can enable this authenticator with the following lines in yourjupyter_config.py:c.JupyterHub.authenticator_class='ldapauthenticator.LDAPAuthenticator'Required configurationAt minimum, the following two configuration options must be set before
the LDAP Authenticator can be used:LDAPAuthenticator.server_addressAddress of the LDAP Server to contact. Just use a bare hostname or IP,
without a port name or protocol prefix.LDAPAuthenticator.lookup_dnorLDAPAuthenticator.bind_dn_templateTo authenticate a user we need the corresponding DN to bind against the LDAP server. The DN can be acquired by either:settingbind_dn_template, which is a list of string template used to
generate the full DN for a user from the human readable username, orsettinglookup_dntoTrue, which does a reverse lookup to obtain the
user's DN. This is because ome LDAP servers, such as Active Directory, don't
always bind with the true DN.lookup_dn = FalseIflookup_dn = False, thenbind_dn_templateis required to be a non-empty
list of templates the users belong to. For example, if some of the users in your
LDAP database have DN of the formuid=Yuvipanda,ou=people,dc=wikimedia,dc=organd some other users have DN likeuid=Mike,ou=developers,dc=wikimedia,dc=orgwhereYuvipandaandMikeare the usernames, you would set this config item
to be:c.LDAPAuthenticator.bind_dn_template=["uid={username},ou=people,dc=wikimedia,dc=org","uid={username},ou=developers,dc=wikimedia,dc=org",]Don't forget the preceedingc.for setting configuration parameters! JupyterHub
usestraitletsfor configuration, and thecrepresents theconfig object.The{username}is expanded into the username the user provides.lookup_dn = Truec.LDAPAuthenticator.lookup_dn=TrueIfbind_dn_templateisn't explicitly configured, i.e. the empty list, the
dynamically acquired value for DN from the username lookup will be used
instead. Ifbind_dn_templateis configured it will be used just like in thelookup_dn = Falsecase.The{username}is expanded to the full path to the LDAP object returned by the
LDAP lookup. For example, on an Active Directory system{username}might
expand to something likeCN=First M. Last,OU=An Example Organizational Unit,DC=EXAMPLE,DC=COM.Also, when usinglookup_dn = Truethe optionsuser_search_base,user_attribute,lookup_dn_user_dn_attributeandlookup_dn_search_filterare required, although their defaults might be sufficient for your use case.Optional configurationLDAPAuthenticator.allowed_groupsLDAP groups whose members are allowed to log in. This must be
set to either empty[](the default, to disable) or to a list of
full DNs that have amemberattribute that includes the current
user attempting to log in.As an example, to restrict access only to people in groupsresearcheroroperations,c.LDAPAuthenticator.allowed_groups=["cn=researcher,ou=groups,dc=wikimedia,dc=org","cn=operations,ou=groups,dc=wikimedia,dc=org",]LDAPAuthenticator.valid_username_regexAll usernames will be checked against this before being sent
to LDAP. This acts as both an easy way to filter out invalid
usernames as well as protection against LDAP injection attacks.By default it looks for the regex^[a-z][.a-z0-9_-]*$which
is what most shell username validators do.LDAPAuthenticator.use_sslBoolean to specify whether to use SSL encryption when contacting
the LDAP server. If it is left toFalse(the default)LDAPAuthenticatorwill try to upgrade connection with StartTLS.
Set this to beTrueto start SSL connection.LDAPAuthenticator.server_portPort to use to contact the LDAP server. Defaults to 389 if no SSL
is being used, and 636 is SSL is being used.LDAPAuthenticator.user_search_baseOnly used withlookup_dn=True.  Defines the search base for looking up users
in the directory.c.LDAPAuthenticator.user_search_base='ou=People,dc=example,dc=com'LDAPAuthenticator.user_attributeOnly used withlookup_dn=True.  Defines the attribute that stores a user's
username in your directory.# Active Directoryc.LDAPAuthenticator.user_attribute='sAMAccountName'# OpenLDAPc.LDAPAuthenticator.user_attribute='uid'LDAPAuthenticator.lookup_dn_search_filterHow to query LDAP for user name lookup, iflookup_dnis set to True.
Default value'({login_attr}={login})'should be good enough for most use cases.LDAPAuthenticator.lookup_dn_search_user,LDAPAuthenticator.lookup_dn_search_passwordTechnical account for user lookup, iflookup_dnis set to True.
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_attributeAttribute containing user's name needed for  building DN string, iflookup_dnis set to True.
Seeuser_search_basefor info on how this attribute is used.
For most LDAP servers, this is username.  For Active Directory, it is cn.LDAPAuthenticator.escape_userdnIf set to True, escape special chars in userdn when authenticating in LDAP.
On some LDAP servers, when userdn contains chars like '(', ')', '' authentication may fail when those chars
are not escaped.LDAPAuthenticator.auth_state_attributesAn optional list of attributes to be fetched for a user after login.
If found these will be returned asauth_state.LDAPAuthenticator.use_lookup_dn_usernameIf set to True (the default) the username used to build the DN string is returned as the username whenlookup_dnis 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.LDAPAuthenticator.enable_refreshIf set to True it then periodically checks if a user is still in one the allowed groups.
This requireslookup_dn_search_userandlookup_dn_search_userto be set if anonymous login is not allowed.
The refresh interval can be set withc.Authenticator.auth_refresh_age.CompatibilityThis has been tested against an OpenLDAP server, with the client
running Python 3.4. Verifications of this code working well with
other LDAP setups are welcome, as are bug reports and patches to make
it work with other LDAP setups!Active Directory integrationPlease use following options for AD integration. This is useful especially in two cases:LDAP Search requires valid user account in order to query user databaseDN does not contain login but some other field, like CN (actual login is present in sAMAccountName, and we need to lookup CN)c.LDAPAuthenticator.lookup_dn=Truec.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='sAMAccountName'c.LDAPAuthenticator.lookup_dn_user_dn_attribute='cn'c.LDAPAuthenticator.escape_userdn=Falsec.LDAPAuthenticator.bind_dn_template='{username}'In setup above, first LDAP will be searched (with account ldap_search_user_technical_account) for users that have sAMAccountName=login
Then DN will be constructed using found CN value.Configuration note on local user creationCurrently, local user creation by the LDAPAuthenticator is unsupported as
this is insecure since there's no cleanup method for these created users. As a
result, users who are disabled in LDAP will have access to this for far longer.Alternatively, there's good support in Linux for integrating LDAP into the
system user setup directly, and users can just use PAM (which is supported in
not just JupyterHub, but ssh and a lot of other tools) to log in. You can seehttp://www.tldp.org/HOWTO/archived/LDAP-Implementation-HOWTO/pamnss.htmland
lots of other documentation on the web on how to set up LDAP to provide user
accounts for your system. Those methods are very widely used, much more secure
and more widely documented. We recommend you use them rather than have
JupyterHub create local accounts using the LDAPAuthenticator.Issue#19provides
additional discussion on local user creation.