ckanext-ldap

A CKAN extension that provides LDAP authentication.

Overview

This plugin provides LDAP authentication for CKAN.

Features include:

• Imports username, full name, email and description;
• Can match against several LDAP fields (eg. username or full name);
• Allows to have LDAP only authentication, or combine LDAP and basic CKAN authentication;
• Can add LDAP users to a given organization automatically;
• Works with Active Directory.

Installation

Path variables used below:

• $INSTALL_FOLDER (i.e. where CKAN is installed), e.g. /usr/lib/ckan/default
• $CONFIG_FILE, e.g. /etc/ckan/default/development.ini

Installing from PyPI

pip install ckanext-ldap

Installing from source

1. Clone the repository into the src folder:

   cd $INSTALL_FOLDER/src
   git clone https://github.com/NaturalHistoryMuseum/ckanext-ldap.git
   

2. Activate the virtual env:

   . $INSTALL_FOLDER/bin/activate
   

3. Install via pip:

   pip install $INSTALL_FOLDER/src/ckanext-ldap
   

Installing in editable mode

Installing from a pyproject.toml in editable mode (i.e. pip install -e) requires setuptools>=64; however, CKAN 2.9 requires setuptools==44.1.0. See our CKAN fork for a version of v2.9 that uses an updated setuptools if this functionality is something you need.

Post-install setup

1. Add 'ldap' to the list of plugins in your $CONFIG_FILE:

   ckan.plugins = ... ldap
   

2. Upgrade the database to create the tables:

   ckan -c $CONFIG_FILE db upgrade -p ldap
   

Configuration

These are the options that can be specified in your .ini config file.

LDAP configuration [REQUIRED]

Other options

Usage

Example Test Configuration

To test that the extension is working correctly without having to set up an LDAP service yourself, you can try this config snippet:

ckanext.ldap.uri = ldap://ldap.forumsys.com:389
ckanext.ldap.base_dn = dc=example,dc=com
ckanext.ldap.search.filter = cn=*{login}*
ckanext.ldap.username = cn
ckanext.ldap.auth.dn = cn=read-only-admin,dc=example,dc=com
ckanext.ldap.email = mail
ckanext.ldap.auth.password = password
ckanext.ldap.auth.method = SIMPLE

See here for more information. Then just login with tesla or gauss for example with password as the password.

Commands

ldap

1. setup-org: create the organisation specified in ckanext.ldap.organization.id.

   ckan -c $CONFIG_FILE ldap setup-org
   

Templates

This extension overrides templates/user/login.html and sets the form action to the LDAP login handler.

To use it elsewhere:

{% set ldap_action = h.get_login_action() %}
{% snippet "user/snippets/login_form.html", action=ldap_action, error_summary=error_summary %}

The helper function h.is_ldap_user() is also provided for templates.

Testing

There is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the docker/ folder.

To run the tests can be run against ckan 2.9.x and 2.10.x on Python3:

1. Build the required images:

   docker compose build
   

2. Then run the tests. The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies.

   # run tests against ckan 2.9.x
   docker compose run latest
   
   # run tests against ckan 2.10.x
   docker compose run next