Flask-Multipass Instructions

Thank you for helping us test the new LDAP provider for Indico.

Below you will find instructions on how to install and use the example application for testing. While this is a very simple application, it uses the same code as Indico 2.0 to perform LDAP operations.

Testing this application with the LDAP server you use for Indico will allow us to catch LDAP related bugs before we release Indico 2.0 or Flask-Multipass.

Prerequisites

Flask-Multipass requires Python 2.7 or newer. You can test it using:

python --version

For the python-ldap library to work, you will also need to have the OpenLDAP client libraries version 2.4.11 or later, as well as OpenSSL if you connect to your LDAP server over SSL. (See the python-ldap prerequisites for more details.)

If you perform the installation on a machine which can run Indico with LDAP authentication, those libraries should already be present.

If you have an OpenLDAP server, make sure the member of attribute is enabled. You can do so with a simple ldapsearch for a user who is part of some groups.

If it is enabled you should see the member of attribute with the distinguished names of the groups he is a members of. If it is not enabled you can have a look here for instructions on how to enable it.

Installation

Follow these simple steps to install the example application and connect it with your LDAP server.

Get Flask-Multipass from GitHub.

git clone https://github.com/indico/flask-multipass.git --branch indico-admins-test

Create a new virtual environment.

cd flask-multipass
virtualenv env
source env/bin/activate

If the virtualenv command is not available, you can install it using
pip install virtualenv

Install Flask-Multipass. (Don't forget the dot.)

pip install -e .

Install the dependencies for the example application (this includes python-ldap).

pip install -r example/requirements.txt

You will need the OpenLDAP client libs version 2.4.11 or later
(see the python-ldap documentation on prerequisites).

Download the example configuration into example/example.cfg:
- Active Directory Server
```
wget http://git.io/vfnvm -O example/example.cfg
```
- OpenLDAP Server
```
wget http://git.io/vfnvB -O example/example.cfg
```
  and adapt the file (example/example.cfg) to your LDAP server.

See the available LDAP Options for more details on how to configure the application. You must also configure the values of the mapping between application keys and the LDAP attributes on lines 35-38. (See the mapping section for more information.)

Run the application. (It will be available at 127.0.0.1:10500.)

python example/example.py

LDAP Options

uri – str (required, default: None)
The URI referring to the LDAP server including the protocol and the port.
Use ldaps:// for LDAP over SSL/TLS and ldap:// with the starttls option for a plain LDAP connection with TLS negotiation.
The port can be omitted if the LDAP server listens on the default port (636 for LDAP over SSL and 389 for a plain LDAP connection with TLS negotiation).
bind_dn – str (required, default: None)
The distinguished name to bind to the LDAP directory.
bind_password – str (required, default: None)
The bind password for simple authentication
timeout – int (default: 30)
The delay in seconds to wait for a reply from the LDAP server (-1 to disable).
verify_cert – bool (default: True)
Whether to verify the server certificate or not.
Equivalent to LDAP's TLS_REQCERT option where demand is True and allow is False. That is, True will require a certificate and fail if the certificate is missing or could not be validated. (This should be used in production.) False will accept a certificate but it will not fail if the certificate is missing or invalid.
starttls – bool (default: False)
Whether to start TLS negotiation or not. (Ignored with a LDAP over SSL connection.)
page_size – int (default: 1000)
The limit of entries to retrieve at once for a search.
0 means no size limit. It is recommended to have at most the size limit set by the server.
uid – str (default: 'uid')
The attribute whose value is used as an identifier for the user (typically the username).
This attribute must be a single-valued attribute whose value is unique for each user. If the attribute is multi-valued, only the first one retrieved will be returned.
user_base – str (required, default: None)
The base node for all the nodes which might contain a user.
user_filter – str (default: '(objectClass=person)')
A valid LDAP filter which will select exclusively all users in the subtree from the user_base. The combination of the user_base and the user_filter must match exclusively all the users.
gid – str (default: 'cn')
The attribute whose value is used as an identifier for the group (typically the group's name).
This attribute must be a single-valued attribute whose value is unique for each group. If the attribute is multi-valued, only the first one retrieved will be returned.
group_base – str (required, default: None)
The base node for all the nodes which might contain a group.
group_filter – str (default: '(objectClass=groupOfNames)')
A valid LDAP filter which will select exclusively all groups in the subtree from the group_base. The combination of the group_base and the group_filter must match exclusively all the groups.
member_of_attr – str (default: 'memberOf')
The multi-valued attribute of a user containing the list of groups a user is a member of.

The member of must be enabled on SLAPD servers. While it is not by default, the majority of servers will have it enabled. A simple ldapsearch for a user member of any group should show if that is the case. (See this article on how to enable MemberOf with OpenLDAP for more details if it is not.)
ad_group_style – bool (default: False)
Whether the server uses Active Directory group style or not.
This is only use to check if a user is a member of a group. In the case of Active Directory, it will take advantage of the tokenGroups attribute of a user to check for nested group membership. Otherwise, it will only look through the values of the member of attribute, which should also work for Active Directory, but only for direct membership.

Mapping

The mapping allows to map the attributes of an LDAP entry to the application keys and is defined in example.cfg. The example application expects 3 keys (defined in MULTIPASS_IDENTITY_INFO_KEYS, line 49): email, name and affiliation. The corresponding attributes could be for example: mail, givenName and org. If a key is missing from the mapping, it is assumed that the application key and LDAP attribute are identical.

Note: While this simple application only uses the first name. Indico will have more applications keys, including the last name, the phone number and the address of a user.

Using and testing the application

Once the application is running you can access it via your web browser at: 127.0.0.1:10500. Here are a few scenarios you can try to make sure, the application works with your LDAP server and that the configuration is correct:

Authentication

Click on Log in at the top left of the screen.
Make sure it says "Log in using My Organization LDAP" and log in.

At the top of the page you should see a line starting with

success: Received IdentityInfo: <IdentityInfo(<LDAPIdentityProvider(my-ldap)>

followed by your user information.

User Search

Search for a user by his name and/or email. By default this will be a wildcard match, tick Exact for an exact match, try both.
Check the results are consistent with your LDAP data.

Group Search and Membership

Search a group by name (wildcard and exact match)
Check the results are consistent.
Click on a group in the search results and check the list of members is correct.
While logged in:
1. Search for a group you are a member of.
2. Go to the list of members by clicking on the group.
3. At the bottom of the list of members. Make sure it says: You are a group member: YES
4. Repeat the steps above for a group you are not a member of and check that it says: You are a group member: NO at the bottom the of list of members.

ThiefMaster/flask-multipass_instructions.md