jupyterhub-ldap-authenticator

LDAP Authenticator plugin for JupyterHub. This project was written with Enterprise LDAP integration in mind and includes the following features:

• Supports multiple LDAP servers and allows for configuration of serverpoolstrategy
• Uses single read-only LDAP connection per authentication request
• Verifies authenticating user exists in LDAP and is a member of allowed_groups

• Supports using nested groups in allowed_groups list
• Supports domain user home directory creation at login

Installation

Install with pip:

pip install jupyterhub-ldap-authenticator

Configuration

To enable LDAPAuthenticator, add the following line to the Jupyterhub config file and extend configuration with the parameters listed below.

c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'

LDAPAuthenticator.server_hosts

List of Names, IPs, or the complete URLs in the scheme://hostname:hostport format of the server (required).

# example- list of complete urls
c.LDAPAuthenticator.server_hosts = ['ldaps://ldap1.example.com:636', 'ldaps://ldap2.example.com:636']
example - list of names
c.LDAPAuthenticator.server_hosts = ['ldap1.example.com', 'ldap2.example.com']
example - list of ips
c.LDAPAuthenticator.server_hosts = ['10.0.0.1', '10.0.0.2']

LDAPAuthenticator.server_port

The port where the LDAP server is listening. Typically 389, for a cleartext connection, and 636 for a secured connection (defaults to None).

# example
c.LDAPAuthenticator.server_port = 636

LDAPAuthenticator.serverusessl

Boolean specifying if the connection is on a secure port (defaults to False).

# example
c.LDAPAuthenticator.serverusessl = True

LDAPAuthenticator.serverconnecttimeout

Timeout in seconds permitted when establishing an ldap connection before raising an exception (defaults to None).

# example
c.LDAPAuthenticator.serverconnecttimeout = 10

LDAPAuthenticator.serverreceivetimeout

Timeout in seconds permitted for responses from established ldap connections before raising an exception (defaults to None).

# example
c.LDAPAuthenticator.serverreceivetimeout = 10

LDAPAuthenticator.serverpoolstrategy

Available Pool HA strategies (defaults to 'FIRST').

- FIRST: Gets the first server in the pool, if 'serverpoolactive' is set to True gets the first available server. - ROUNDROBIN: Each time the connection is open the subsequent server in the pool is used. If 'serverpool_active' is set to True unavailable servers will be discarded. - RANDOM: each time the connection is open a random server is chosen in the pool. If 'serverpoolactive' is set to True unavailable servers will be discarded.

# example
c.LDAPAuthenticator.serverpoolstrategy = 'FIRST'

LDAPAuthenticator.serverpoolactive

If True the ServerPool strategy will check for server availability. Set to Integer for maximum number of cycles to try before giving up (defaults to True).

# example - boolean
c.LDAPAuthenticator.serverpoolactive = True
example - maximum number of tries
c.LDAPAuthenticator.serverpoolactive = 3

LDAPAuthenticator.serverpoolexhaust

If True, any inactive servers will be removed from the pool. If set to an Integer, this will be the number of seconds an unreachable server is considered offline. When this timeout expires the server is reinserted in the pool and checked again for availability (defaults to False).

# example - boolean
c.LDAPAuthenticator.serverpoolexhaust = True
example - offline timeout
c.LDAPAuthenticator.serverpoolexhaust = 600

LDAPAuthenticator.binduserdn

The account of the user to log in for simple bind (defaults to None).

# example - freeipa
c.LDAPAuthenticator.binduserdn = 'uid=imauser,cn=users,cn=accounts,dc=example,dc=com'
example - Active Directory
c.LDAPAuthenticator.binduserdn = 'CN=imauser,CN=Users,DC=example,DC=com'

LDAPAuthenticator.binduserpassword

The password of the user for simple bind (defaults to None).

# example
c.LDAPAuthenticator.binduserpassword = 'password'

LDAPAuthenticator.usersearchbase

The location in the Directory Information Tree where the user search will start.

# example - freeipa
c.LDAPAuthenticator.usersearchbase = 'cn=users,cn=accounts,dc=example,dc=com'
example - active directory
c.LDAPAuthenticator.usersearchbase = 'CN=Users,DC=example,DC=com'

LDAPAuthenticator.usersearchfilter

LDAP search filter to validate that the authenticating user exists within the organization. Search filters containing '{username}' will have that value substituted with the username of the authenticating user.

# example - freeipa
c.LDAPAuthenticator.usersearchfilter = '(&(objectClass=person)(uid={username}))'
example - active directory
c.LDAPAuthenticator.usersearchfilter = '(&(objectCategory=person)(objectClass=user)(sAMAccountName={username}))'

LDAPAuthenticator.usermembershipattribute

LDAP Attribute used to associate user group membership (defaults to 'memberOf').

# example
c.LDAPAuthenticator.usermembershipattribute = 'memberOf'

LDAPAuthenticator.groupsearchbase

The location in the Directory Information Tree where the group search will start. Search string containing '{group}' will be substituted with entries taken from allowed_groups

# example - freeipa
c.LDAPAuthenticator.groupsearchbase = 'cn=groups,cn=accounts,dc=example,dc=com'
example - active directory
c.LDAPAuthenticator.groupsearchbase = 'CN=Groups,DC=example,DC=com'

LDAPAuthenticator.groupsearchfilter

LDAP search filter to return members of groups defined in the allowedgroups parameter. Search filters containing '{group}' will have that value substituted with the group dns provided in the allowedgroups parameter.

# example - freeipa
c.LDAPAuthenticator.groupsearchfilter = '(&(objectClass=ipausergroup)(memberOf={group}))'
example - active directory
c.LDAPAuthenticator.groupsearchfilter = '(&(objectClass=group)(memberOf={group}))'

LDAPAuthenticator.allowed_groups

List of LDAP group DNs that users must be a member of in order to be granted login. If left undefined or set to None, allowed_groups will be short-circuited and all users will be allowed (defaults to None).

# example
c.LDAPAuthenticator.allowed_groups = ['cn=jupyterhub-users,cn=groups,cn=accounts,dc=example,dc=com']

LDAPAuthenticator.allownestedgroups

Boolean allowing for recursive search of members within nested groups of allowed_groups (defaults to False).

# example
c.LDAPAuthenticator.allownestedgroups = True

LDAPAuthenticator.username_pattern

Regular expression pattern that all valid usernames must match. If a username does not match the pattern specified here, authentication will not be attempted. If not set, allow any username (defaults to None).

# example - freeipa
c.LDAPAuthenticator.usernamepattern = '[a-zA-Z0-9.][a-zA-Z0-9.-]{0,252}[a-zA-Z0-9.$-]?'
example - active directory
c.LDAPAuthenticator.usernamepattern = '[a-zA-Z0-9.][a-zA-Z0-9.-]{8,20}[a-zA-Z0-9.$-]?'

LDAPAuthenticator.createuserhome_dir

Boolean allowing for user home directory to be created at login

# example
c.LDAPAuthenticator.createuserhome_dir = True

LDAPAuthenticator.createuserhomedircmd

Command used when creating a userhome directory as a list of strings. The username will be appended as the final argument. Defaults to mkhomedir_helper on linux systems.

# example
c.LDAPAuthenticator.createuserhomedircmd = ['mkhomedir_helper']

Examples

FreeIPA Integration

# freeipa example
c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'
c.LDAPAuthenticator.server_hosts = ['ldaps://ldap1.example.com:636', 'ldaps://ldap2.example.com:636']
c.LDAPAuthenticator.binduserdn = 'uid=imauser,cn=users,cn=accounts,dc=example,dc=com'
c.LDAPAuthenticator.binduserpassword = 'imapassword'
c.LDAPAuthenticator.usersearchbase = 'cn=users,cn=accounts,dc=example,dc=com'
c.LDAPAuthenticator.usersearchfilter = '(&(objectClass=person)(uid={username}))'
c.LDAPAuthenticator.usermembershipattribute = 'memberOf'
c.LDAPAuthenticator.groupsearchbase = 'cn=groups,cn=accounts,dc=example,dc=com'
c.LDAPAuthenticator.groupsearchfilter = '(&(objectClass=ipausergroup)(memberOf={group}))'
c.LDAPAuthenticator.allowed_groups = ['cn=jupyterhub-users,cn=groups,cn=accounts,dc=example,dc=com']
c.LDAPAuthenticator.allownestedgroups = True
c.LDAPAuthenticator.usernamepattern = '[a-zA-Z0-9.][a-zA-Z0-9.-]{0,252}[a-zA-Z0-9.$-]?'
c.LDAPAuthenticator.createuserhome_dir = True
c.LDAPAuthenticator.createuserhomedircmd = ['mkhomedir_helper']

Active Directory Integration

# active directory example
c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'
c.LDAPAuthenticator.server_hosts = ['ldaps://ldap1.example.com:636', 'ldaps://ldap2.example.com:636']
c.LDAPAuthenticator.binduserdn = 'CN=imauser,CN=Users,DC=example,DC=com'
c.LDAPAuthenticator.binduserpassword = 'imapassword'
c.LDAPAuthenticator.usersearchbase = 'CN=Users,DC=example,DC=com'
c.LDAPAuthenticator.usersearchfilter = '(&(objectCategory=person)(objectClass=user)(sAMAccountName={username}))'
c.LDAPAuthenticator.usermembershipattribute = 'memberOf'
c.LDAPAuthenticator.groupsearchbase = 'CN=Groups,DC=example,DC=com'
c.LDAPAuthenticator.groupsearchfilter = '(&(objectClass=group)(memberOf={group}))'
c.LDAPAuthenticator.allowed_groups = ['CN=jupyterhub-users,CN=Groups,DC=example,DC=com']
c.LDAPAuthenticator.allownestedgroups = True
c.LDAPAuthenticator.usernamepattern = '[a-zA-Z0-9.][a-zA-Z0-9.-]{8,20}[a-zA-Z0-9.$-]?'
c.LDAPAuthenticator.createuserhome_dir = True
c.LDAPAuthenticator.createuserhomedircmd = ['mkhomedir_helper']

OpenLDAP Integration

Because OpenLDAP does not natively support the memberOf attribute in their user objects, the allowed_groups scoping has been short-circuited in the following example:

# openldap example
c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'
c.LDAPAuthenticator.server_hosts = ['ldaps://ldap1.example.com:636', 'ldaps://ldap2.example.com:636']
c.LDAPAuthenticator.binduserdn = 'uid=imauser,ou=People,dc=example,dc=com'
c.LDAPAuthenticator.binduserpassword = 'imapassword'
c.LDAPAuthenticator.usersearchbase = 'ou=People,dc=example,dc=com'
c.LDAPAuthenticator.usersearchfilter = '(&(objectClass=posixAccount)(uid={username}))'
c.LDAPAuthenticator.usernamepattern = '[a-zA-Z0-9.][a-zA-Z0-9.-]{0,252}[a-zA-Z0-9.$-]?'
c.LDAPAuthenticator.createuserhome_dir = True
c.LDAPAuthenticator.createuserhomedircmd = ['mkhomedir_helper']