DEPRECATED!
As EWC (aka StackStorm Enterprise) was open-sourced, the community-driven repo is deprecated in favor of https://github.com/StackStorm/st2-auth-ldap which is integrated into the st2 core.

If you're using this repository and interested migrating any of the functionality from this plugin, please open a pull request in the st2-auth-ldap repository instead.

LDAP authentication plug-in for StackStorm Community edition

The LDAP backend reads credentials and authenticates users against an LDAP server. This backend was originally contributed to the st2 repo by Ruslan Tumarkin under PR #1790.

Note:

There are currently two types of LDAP backends available - community contributed one and one developed and maintained by the StackStorm team. This repository contains the community contributed one.

Community contributed backend can be installed by anyone and the StackStorm developed one is only available in the enterprise edition (for more information on the enterprise edition, please see https://stackstorm.com/product/#enterprise).

The difference between them is that the one included in the enterprise edition is developed, supported, tested, maintained and certified by the StackStorm team and the community contributed one is developed and maintained by the community.

Requirements

Ubuntu:

sudo apt-get -y install gcc libldap2-dev

RHEL/CentOS:

sudo yum -y install gcc openldap-devel

Configuration Options

option	required	type	default	description
ldap_uri	yes	string		URI of the LDAP server. Format: <protocol>://<hostname>[:port] (Protocol: ldap or ldaps)
use_tls	yes	boolean	false	Boolean parameter to set if tls is required. This upgrades a plain-text LDAP connection on tcp/389 to a TLS connection on the same port using the STARTTLS LDAP command. This is the preferred method of encrypting an LDAP connection as ldaps:// is deprecated. seee this article. Should be set to false if using ldaps in the uri.
bind_dn	no	string	""	DN user to bind to LDAP. If an empty string, an anonymous bind is performed. To use the user supplied username in the bind_dn, use the {username} placeholder in string.
bind_pw	no	string	""	DN password. Use the {password} placeholder in the string to use the user supplied password.
user	no	object	null	Search parameters for user authentication. see user table below
group	no	object	null	Search parameters for user's group membership. see group table below
chase_referrals	no	boolean	false	Boolean parameter to set whether to chase referrals.
ref_hop_limit	no	integer	0	The maximum number to refer Referrals recursively

Attributes for user option

option	required	default	description
base_dn	yes	n/a	Base DN on the LDAP server to be used when looking up the user account.
search_filter	yes	n/a	Should contain the placeholder {username} for the username.
scope	yes	n/a	The scope of the search to be performed. Available choices: base, onelevel, subtree

Attributes for group option

option	required	default	description
base_dn	yes	n/a	Base DN on the LDAP server to be used when looking up the group.
search_filter	yes	n/a	Should contain the placeholder {username} for the username.
scope	yes	n/a	The scope of the search to be performed. Available choices: base, onelevel, subtree

Configuration Example

Please refer to the authentication section in the StackStorm documentation for basic setup concept. The following is an example of the auth section in the StackStorm configuration file for the ldap backend.

[auth]
mode = standalone
backend = ldap
backend_kwargs = { "ldap_uri": "ldap://ldap.example.com", "use_tls": true, "bind_dn": "cn=user,dc=example,dc=com", "bind_pw": "bind_password", "user": {"base_dn": "ou=users,dc=example,dc=com", "search_filter": "(uid={username})", "scope": "onelevel"}, "group": {"base_dn": "ou=groups,dc=example,dc=com", "search_filter": "(&(cn=st2access)(memberUid={username}))", "scope": "subtree"} }
enable = True
use_ssl = True
cert = /path/to/ssl/cert/file
key = /path/to/ssl/key/file
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Configuration Example 2 - restrict access to a specific LDAP AD group.

[auth]
mode = standalone
backend = ldap
backend_kwargs = { "ldap_uri": "ldap://ldap.example.com", "use_tls": true, "bind_dn": "cn=user,dc=example,dc=com", "bind_pw": "bind_password", "user": {"base_dn": "ou=users,dc=example,dc=com", "search_filter": "((sAMAccountName={username})(memberOf=CN=AD-GroupName,OU=Groups,OU=Region,OU=Client,DC=example,DC=com)", "scope": "subtree"} }
enable = True
use_ssl = True
cert = /path/to/ssl/cert/file
key = /path/to/ssl/key/file
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Configuration Example - Connecting using encryption

LDAP has deprecated the use of ldaps:// URIs as described in this article. The proper way to configure this module to connect to a LDAP server using encryption is to specify the ldap_uri parameter with an ldap:// URI and then set "use_tls": true. This will connect to the LDAP server on port tcp/389 and then use the STARTTLS LDAP command to upgrade the connection to an encrypted connetion in-place.

Below is an example config with encryption enabled:

backend_kwargs = { "ldap_uri": "ldap://ldap.example.com", "use_tls": true, "bind_dn": "cn=user,dc=example,dc=com", "bind_pw": "bind_password", "user": {"base_dn": "ou=users,dc=example,dc=com", "search_filter": "(uid={username})", "scope": "onelevel"}, "group": {"base_dn": "ou=groups,dc=example,dc=com", "search_filter": "(&(cn=st2access)(memberUid={username}))", "scope": "subtree"} }

Authenticating users against various schemas.

There is no one standard way to store user credentials in LDAP. There are various ways to organise the directory tree and various ways to secure it. In some cases, the users DN can't be determined with a static configuration and requires a bind DN to locate the user in the database before user authentication can occur.

This authentication backend attempts to be flexible with the way LDAP binding and authentication can be performed, but may not meet all use cases.

Active Directory Examples

Using sAMAccountName should be unique in combination with a domain name. "bind_dn": "sAMAccountName={username}@example.com", "bind_pw": "{password}"

Using userPrincipalName should be unique within a forest. "bind_dn": "userPrincipalName={username}", "bind_pw": "{password}"

OpenLDAP Examples

Using anonymous binding "bind_dn": "", "bind_pw": ""

Using bind DN "bind_dn": "cn=bind_user,dc=example,dc=com", "bind_pw": "bind_user_password"

Installation

Production

1. Activate the StackStorm virtual environment. source /<path to stackstorm>/st2/bin/activate
2. Install the LDAP plug-in and its dependencies. pip install git+https://github.com/<github_account>/st2-auth-backend-ldap.git@master#egg=st2_auth_backend_ldap
3. Configure the authentication backend in /etc/st2/st2.conf (see example above).
4. Restart StackStorm st2ctl restart

Development

Suitable for development environments and may not be ideal under production conditions.

1. Activate the StackStorm virtual environment. source /<path to stackstorm>/st2/bin/activate
2. Upgrade pip to the latest version. pip install --update pip
3. Optionally, install dev packages for ldap apt-get install libsasl2-dev python-dev libldap2-dev libssl-dev
4. Install the LDAP plug-in and its dependencies. pip install git+https://github.com/<github_account>/st2-auth-backend-ldap.git@master#egg=st2_auth_backend_ldap
5. Deactivate virtual environment. deactivate
6. Configure the authentication backend in /etc/st2/st2.conf (see example above).
7. Restart StackStorm st2ctl restart

Copyright, License, and Contributors Agreement

Copyright 2015 StackStorm, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at: http://www.apache.org/licenses/LICENSE-2.0

By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full, complete, irrevocable copyright license to all users and developers of the project, present and future, pursuant to the license of the project.