Welcome to Flask-SimpleLDAP’s documentation!

Flask-SimpleLDAP provides LDAP authentication for Flask.

Quickstart

First, install Flask-SimpleLDAP:

$ pip install flask-simpleldap

Flask-SimpleLDAP depends, and will install for you, recent versions of Flask (0.12.4 or later) and pyldap. Flask-SimpleLDAP is compatible with and tested on Python 3.5, 3.6 and 3.7.

Next, add a LDAP to your code and at least the three required configuration options:

from flask import Flask
from flask_simpleldap import LDAP

app = Flask(__name__)
app.config['LDAP_BASE_DN'] = 'OU=users,dc=example,dc=org'
app.config['LDAP_USERNAME'] = 'CN=user,OU=Users,DC=example,DC=org'
app.config['LDAP_PASSWORD'] = 'password'

ldap = LDAP(app)

@app.route('/ldap')
@ldap.login_required
def ldap_protected():
    return 'Success!'


if __name__ == '__main__':
    app.run()

Configuration

LDAP understands the following configuration directives:

LDAP_HOST The host name or IP address of your LDAP server. Default: ‘localhost’.
LDAP_PORT The port number of your LDAP server. Default: 389.
LDAP_SCHEMA The LDAP schema to use between ‘ldap’ and ‘ldaps’. Default: ‘ldap’.
LDAP_USERNAME Required: The user name used to bind.
LDAP_PASSWORD Required: The password used to bind.
LDAP_TIMEOUT How long (seconds) a connection can take to be opened before timing out. Default: 10.
LDAP_USE_SSL Set to True if your server uses SSL. Default: False.
LDAP_USE_TLS Set to True if your server uses TLS. Default: False.
LDAP_REQUIRE_CERT Set to True if your server requires a certificate. Default: False.
LDAP_CERT_PATH Path to the certificate if LDAP_REQUIRE_CERT is True.
LDAP_BASE_DN Required: The distinguished name to use as the search base.
LDAP_OBJECTS_DN The field to use as the objects’ distinguished name. Default: ‘distinguishedName’.
LDAP_USER_FIELDS list of fields to return when searching for a user’s object details. Default: list (all).
LDAP_USER_OBJECT_FILTER The filter to use when searching for a user object. Default: ‘(&(objectclass=Person)(userPrincipalName=%s))’
LDAP_USER_GROUPS_FIELD The field to return when searching for a user’s groups. Default: ‘memberOf’.
LDAP_GROUP_FIELDS list of fields to return when searching for a group’s object details. Default: list (all).
LDAP_GROUP_OBJECT_FILTER The filter to use when searching for a group object. Default: ‘(&(objectclass=Group)(userPrincipalName=%s))’
LDAP_GROUP_MEMBERS_FIELD The field to return when searching for a group’s members. Default: ‘member’
LDAP_LOGIN_VIEW Views decorated with login_required() or group_required() will redirect unauthenticated requests to this view. Default: ‘login’.
LDAP_REALM_NAME Views decorated with basic_auth_required() will use this as the “realm” part of HTTP Basic Authentication when responding to unauthenticated requests.
LDAP_OPENLDAP Set to True if your server is running OpenLDAP. Default: False
LDAP_GROUP_MEMBER_FILTER The group member filter to use when using OpenLDAP. Default: ‘*’
LDAP_GROUP_MEMBER_FILTER_FIELD The group member filter field to use when using OpenLDAP. Default: ‘*’
LDAP_CUSTOM_OPTIONS dict of ldap options you want to set in this format: {option: value}. Default: None

API

Classes

class flask_simpleldap.LDAP(app=None)
basic_auth_required(func)

When applied to a view function, any unauthenticated requests are asked to authenticate via HTTP’s standard Basic Authentication system. Requests with credentials are checked with bind_user().

The user’s browser will typically show them the contents of LDAP_REALM_NAME as a prompt for which username and password to enter.

If the request’s credentials are accepted by the LDAP server, the username is stored in flask.g.ldap_username and the password in flask.g.ldap_password.

Parameters:func – The view function to decorate.
bind

Attempts to bind to the LDAP server using the credentials of the service account.

Returns:Bound LDAP connection object if successful or None if unsuccessful.
bind_user(username, password)

Attempts to bind a user to the LDAP server using the credentials supplied.

Note

Many LDAP servers will grant anonymous access if password is the empty string, causing this method to return True no matter what username is given. If you want to use this method to validate a username and password, rather than actually connecting to the LDAP server as a particular user, make sure password is not empty.

Parameters:
  • username (str) – The username to attempt to bind with.
  • password (str) – The password of the username we’re attempting to bind with.
Returns:

Returns True if successful or None if the credentials are invalid.

get_group_members(group)

Returns a list with the group’s members or None if unsuccessful.

Parameters:group (str) – Group we want users for.
get_object_details(user=None, group=None, query_filter=None, dn_only=False)

Returns a dict with the object’s (user or group) details.

Parameters:
  • user (str) – Username of the user object you want details for.
  • group (str) – Name of the group object you want details for.
  • query_filter (str) – If included, will be used to query object.
  • dn_only (bool) – If we should only retrieve the object’s distinguished name or not. Default: False.
get_user_groups(user)

Returns a list with the user’s groups or None if unsuccessful.

Parameters:user (str) – User we want groups for.
static group_required(groups=None)

When applied to a view function, any unauthenticated requests will be redirected to the view named in LDAP_LOGIN_VIEW. Authenticated requests are only permitted if they belong to one of the listed groups.

The login view is responsible for asking for credentials, checking them, and setting flask.g.user to the name of the authenticated user and flask.g.ldap_groups to the authenticated user’s groups if the credentials are acceptable.

Parameters:groups (list) – List of groups that should be able to access the view function.
static init_app(app)

Initialize the app for use with this LDAP. This is called automatically if app is passed to __init__().

Parameters:app (flask.Flask) – the application to configure for use with this LDAP
initialize

Initialize a connection to the LDAP server.

Returns:LDAP connection object.
static login_required(func)

When applied to a view function, any unauthenticated requests will be redirected to the view named in LDAP_LOGIN_VIEW. Authenticated requests do NOT require membership from a specific group.

The login view is responsible for asking for credentials, checking them, and setting flask.g.user to the name of the authenticated user if the credentials are acceptable.

Parameters:func – The view function to decorate.

History

Changes:

  • 1.3.0 July 14, 2019 - Thanks to the contributors, this release fixes issues related to bind_user and fixes some issues related to filtering.

    #51 Referral chasing crash #54 Fixes #44 - Error in bind_user method, also fixes #60 and #61 #56 OpenLDAP section has Incorrect LDAP_GROUP_OBJECT_FILTER #57 next vaule: Priority use request.full_path #59 get_object_details to take query_filter and fallback to LDAP_USER_OBJECT_FILTER or LDAP_GROUP_OBJECT_FILTER

  • 1.2.0 September 26, 2017 - Changed get_group_members() and get_user_groups() returning strings instead of bytes in PY3.

  • 1.1.2 July 17, 2017 - Merge GitHub PR #30,

    Fix for python3

    • Fix decoding bytes in PY3 for @ldap.group_required.
  • 1.1.1 April 10, 2017 - Merge GitHub pull #26,

    Fix set_option call to LDAP for SSL CERT

  • 1.1.0 June 7, 2016 - Add the ability the pass any valid pyldap config options via the LDAP_CUSTOM_OPTIONS configuration directive.

  • 1.0.1 June 5, 2016 - Fix ldap filter import.

  • 1.0.0 June 4, 2016 - Python 3.x support. Switched from python-ldap to pyldap which is a fork with Python 3.x support.

  • 0.4.0: September 5, 2015 - Added support for OpenLDAP directories. Thanks to @jm66 on GitHub.

  • 0.3.0: January 21, 2015 - Fix Github issue #10,

    Redirect users back to the page they originally requested after authenticating

    • Fix GitHub issue #12, Only trust .bind_user() with a non-empty password
  • 0.2.0: December 7, 2014 - Added HTTP Basic Authentication. Thanks to @OptiverTimAll on GitHub. - Fix GitHub issue #4,

    User or group queries are vulnerable to LDAP injection. Make sure you update your filters to use ‘%s’ instead of the old ‘{}’!

  • 0.1.1: September 6, 2014 - Fix GitHub issue #3,

    Not compatible with uppercase distinguished names.

  • 0.1: August 9, 2014 - Initial Release