jupyterhub-ldap-authenticator 1.1.0

Contents

• Description
• Installation
• Configuration
  • Authentication strategy
  • Server parameters
  • Bind parameters
  • User and group parameters
  • Home directory and auth state parameters
• Examples
• Directory compatibility
• Multi-factor authentication
• Migrating from 0.x
• Development
• License

Description

An LDAP Authenticator plugin for JupyterHub, written with Enterprise LDAP and Active Directory integration in mind. It supports:

• Multiple LDAP servers with configurable high-availability pooling (server_pool_strategy)
• Search-bind authentication using a service account, or direct-bind via bind_dn_template
• Modern TLS negotiation (server_tls_strategy: before_bind / on_connect / insecure)
• Group-based access control with allowed_groups, including recursive nested group resolution
• Automatic creation of a user's home directory at login
• Exposing selected LDAP attributes to JupyterHub as auth_state

Which LDAP authenticator should I use? The JupyterHub organization maintains an official jupyterhub-ldapauthenticator package. This project is a superset of it — reach for this plugin when you need any of its distinguishing features: automatic home-directory creation, multi-server failover pooling, or nested-group resolution. For simpler deployments, the official package is an excellent choice.

Installation

Install with pip:

pip install jupyterhub-ldap-authenticator

Configuration

To enable LDAPAuthenticator, add the following to your JupyterHub config file and extend it with the parameters below.

c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'

Authentication strategy

This plugin supports two authentication strategies:

• Search-bind (default): connect as a service account (bind_user_dn / bind_user_password), search the directory for the authenticating user, then verify their password. Requires bind_user_dn, bind_user_password, user_search_base, and user_search_filter.
• Direct-bind: bind to the server directly as the authenticating user using bind_dn_template, with no service account. Enabled automatically when bind_dn_template is set.

Fully worked configurations for each strategy are in Examples.

Server parameters

⚠️ Certificate validation. By default the ldap3 Tls object does not verify the server's certificate (validate=ssl.CERT_NONE), so before_bind and on_connect encrypt the connection but do not authenticate the server — leaving credentials exposed to man-in-the-middle attacks. When TLS is enabled without validation, the authenticator logs a warning at startup. For production, enable verification against a CA bundle via server_tls_kwargs:

import ssl
c.LDAPAuthenticator.server_tls_kwargs = {
    'validate': ssl.CERT_REQUIRED,
    'ca_certs_file': '/etc/ssl/certs/ca-bundle.pem',
}

Bind parameters

# direct-bind: a single template, or a list tried in order until one binds
c.LDAPAuthenticator.bind_dn_template = 'uid={username},ou=people,dc=example,dc=org'
c.LDAPAuthenticator.bind_dn_template = [
    'uid={username},ou=people,dc=example,dc=org',
    'uid={username},ou=developers,dc=example,dc=org',
]

User and group parameters

Home directory and auth state parameters

c.LDAPAuthenticator.create_user_home_dir = True
c.LDAPAuthenticator.auth_state_attributes = ['mail', 'displayName']

Home-directory command. The default mkhomedir_helper only creates a home directory for a user that already resolves as a local POSIX account (e.g. via SSSD/nslcd). In pure-LDAP deployments where users are not local system accounts, mkhomedir_helper fails and login returns a 500. In that case, use a command that also creates the account, for example:

# create the system user and its home directory
c.LDAPAuthenticator.create_user_home_dir_cmd = ['useradd', '--create-home']

The username is appended as the final argument. The command runs as the user the JupyterHub process runs as, so it must have permission to create accounts (typically root).

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.bind_user_dn = 'uid=imauser,cn=users,cn=accounts,dc=example,dc=com'
c.LDAPAuthenticator.bind_user_password = 'imapassword'
c.LDAPAuthenticator.user_search_base = 'cn=users,cn=accounts,dc=example,dc=com'
c.LDAPAuthenticator.user_search_filter = '(&(objectClass=person)(uid={username}))'
c.LDAPAuthenticator.user_membership_attribute = 'memberOf'
c.LDAPAuthenticator.group_search_base = 'cn=groups,cn=accounts,dc=example,dc=com'
c.LDAPAuthenticator.group_search_filter = '(&(objectClass=ipausergroup)(memberOf={group}))'
c.LDAPAuthenticator.allowed_groups = ['cn=jupyterhub-users,cn=groups,cn=accounts,dc=example,dc=com']
c.LDAPAuthenticator.admin_groups = ['cn=jupyterhub-admins,cn=groups,cn=accounts,dc=example,dc=com']
c.LDAPAuthenticator.allow_nested_groups = True
c.LDAPAuthenticator.username_pattern = '[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?'
c.LDAPAuthenticator.create_user_home_dir = True
c.LDAPAuthenticator.create_user_home_dir_cmd = ['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.bind_user_dn = 'CN=imauser,CN=Users,DC=example,DC=com'
c.LDAPAuthenticator.bind_user_password = 'imapassword'
c.LDAPAuthenticator.user_search_base = 'CN=Users,DC=example,DC=com'
c.LDAPAuthenticator.user_search_filter = '(&(objectCategory=person)(objectClass=user)(sAMAccountName={username}))'
c.LDAPAuthenticator.user_membership_attribute = 'memberOf'
c.LDAPAuthenticator.group_search_base = 'CN=Groups,DC=example,DC=com'
c.LDAPAuthenticator.group_search_filter = '(&(objectClass=group)(memberOf={group}))'
c.LDAPAuthenticator.allowed_groups = ['CN=jupyterhub-users,CN=Groups,DC=example,DC=com']
c.LDAPAuthenticator.allow_nested_groups = True
c.LDAPAuthenticator.username_pattern = '[a-zA-Z0-9_.][a-zA-Z0-9_.-]{8,20}[a-zA-Z0-9_.$-]?'
c.LDAPAuthenticator.create_user_home_dir = True
c.LDAPAuthenticator.create_user_home_dir_cmd = ['mkhomedir_helper']

OpenLDAP Integration (direct-bind)

Because OpenLDAP does not natively populate the memberOf attribute on user objects, allowed_groups scoping is short-circuited below. This example also uses the direct-bind strategy, avoiding a service account entirely:

# openldap example
c.JupyterHub.authenticator_class = 'ldapauthenticator.LDAPAuthenticator'
c.LDAPAuthenticator.server_hosts = ['ldaps://ldap1.example.com:636', 'ldaps://ldap2.example.com:636']
c.LDAPAuthenticator.bind_dn_template = 'uid={username},ou=People,dc=example,dc=com'
c.LDAPAuthenticator.username_pattern = '[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,252}[a-zA-Z0-9_.$-]?'
c.LDAPAuthenticator.create_user_home_dir = True
c.LDAPAuthenticator.create_user_home_dir_cmd = ['mkhomedir_helper']

Directory compatibility

This authenticator uses an LDAP simple bind (username/DN + password) over an optionally TLS-secured connection, and resolves groups from a memberOf-style attribute. Any directory that supports those works. It does not implement SASL, Kerberos/GSSAPI, NTLM, or client-certificate (EXTERNAL) bind mechanisms.

Rule of thumb: if the directory accepts an LDAP simple bind over TLS and exposes a memberOf-like attribute, it is compatible. Kerberos-only realms and proprietary APIs are not.

Multi-factor authentication

This plugin does not implement MFA as a first-class feature — there is no separate OTP field, challenge-response step, or push handling (JupyterHub's login form is a single username/password step).

However, because the password field is passed through to the LDAP bind unchanged, "append your one-time code to your password" MFA works transparently with any directory that validates the appended code at bind time:

In other words, MFA is a property of the directory that this plugin's pass-through bind preserves, rather than something the plugin performs itself.

Migrating from 0.x

Version 1.0 is backward compatible — existing configurations continue to work. Two changes are worth noting:

• server_use_ssl is deprecated in favor of server_tls_strategy. Setting server_use_ssl = True still works but now emits a warning and is translated to server_tls_strategy = 'on_connect'. Note the new default server_tls_strategy is before_bind (STARTTLS); if you relied on the previous plaintext default, set server_tls_strategy = 'insecure' explicitly.
• The authenticator is now async, requiring JupyterHub >= 2.0 and Python >= 3.10.

Development

This project uses a Makefile to drive common tasks. Run make help for the full list.

make venv     # create a virtualenv and install dependencies
make lint     # run ruff (lint + format check) and mypy
make test     # run the pytest suite
make build    # build the sdist/wheel package

License

MIT