Flask-SimpleLDAP Documentation

Transcription

1 Flask-SimpleLDAP Documentation Release Alexandre Ferland Sep 14, 2017

2

3 Contents 1 Quickstart 3 2 Configuration 5 3 API Classes History i

4 ii

5 Flask-SimpleLDAP Documentation, Release Flask-SimpleLDAP provides LDAP authentication for Flask. Contents 1

6 Flask-SimpleLDAP Documentation, Release Contents

7 CHAPTER 1 Quickstart First, install Flask-SimpleLDAP: $ pip install flask-simpleldap Flask-SimpleLDAP depends, and will install for you, recent versions of Flask ( or later) and pyldap. Flask- SimpleLDAP is compatible with and tested on Python 2.7, 3.4, 3.5 and 3.6. 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 def ldap_protected(): return 'Success!' 3

8 Flask-SimpleLDAP Documentation, Release Chapter 1. Quickstart

9 CHAPTER 2 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_OPTIONSdict of ldap options you want to set in this format: {option: value}. Default: None 5

10 Flask-SimpleLDAP Documentation, Release Chapter 2. Configuration

11 CHAPTER 3 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. 7

12 Flask-SimpleLDAP Documentation, Release 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, 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. 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: July 17, Merge GitHub PR #30, Fix for python3 8 Chapter 3. API

13 Flask-SimpleLDAP Documentation, Release Fix decoding bytes in PY April 10, Merge GitHub pull #26, Fix set_option call to LDAP for SSL CERT June 7, 2016 Add the ability the pass any valid pyldap config options via the LDAP_CUSTOM_OPTIONS configuration directive June 5, 2016 Fix ldap filter import June 4, 2016 Python 3.x support. Switched from python-ldap to pyldap which is a fork with Python 3.x support : September 5, 2015 Added support for OpenLDAP directories. Thanks on GitHub : 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 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 3.2. History 9

14 Flask-SimpleLDAP Documentation, Release Chapter 3. API

15 Index B basic_auth_required() (flask_simpleldap.ldap method), 7 bind (flask_simpleldap.ldap attribute), 7 bind_user() (flask_simpleldap.ldap method), 7 G get_group_members() (flask_simpleldap.ldap method), 8 get_object_details() (flask_simpleldap.ldap method), 8 get_user_groups() (flask_simpleldap.ldap method), 8 group_required() (flask_simpleldap.ldap static method), 8 I init_app() (flask_simpleldap.ldap static method), 8 initialize (flask_simpleldap.ldap attribute), 8 L LDAP (class in flask_simpleldap), 7 login_required() (flask_simpleldap.ldap static method), 8 11