Stork LDAP Authentication

Introduction

The Stork server can use an external LDAP server for identification and authorization of users and groups. This is typically used to provide single-sign-on (SSO) via an organization's personnel directory. If you are not familiar with LDAP, a brief introduction to LDAP is available.

Architecture

LDAP support in Stork is provided by the stork-hook-ldap hook (plugin/library). Hooks are binary files with the .so extension, and must be placed in the server hook directory (/usr/lib/stork-server/hooks by default). The Stork server automatically loads any hooks it finds there.

The LDAP hook has a number of options which control its behavior. These are given to the stork-server process when it starts, either by command-line option, or by environment variable. For normal circumstances, it is recommended to use the /etc/stork/server.env file to define the environment variables. Consult the Stork ARM for more information about configuring Stork.

Once you have configured Stork to use LDAP authentication, an option for LDAP will appear on the login page of the Stork web UI (in the "Pick a Method" drop-down list). Select LDAP, then enter an LDAP user name and password. Stork will use the hook to contact the LDAP server, validate the password, and log the user in to Stork.

Installation

The recommended way to install the LDAP hook, and Stork itself, is to use the pre-compiled packages provided by ISC. Please see the Stork ARM for instructions on obtaining and installing ISC packages.

If building from source, you must obtain the LDAP hook separately, from the LDAP hook GitLab project. Simply unpack that into your local source tree and build the hook. See the ARM for more on building Stork from source.

Configuration

The most commonly used options are explained below. It is recommended they be defined in the /etc/stork/server.env file. If you are unsure what values to use, consult your LDAP directory administrator. The hook documentation provides the complete list of LDAP hook parameters.

Option Summary

This table summarizes the options, which are described in detail in the following sections.

All LDAP hook environment variable names begin with STORK_SERVER_HOOK_LDAP_. For readability, this is omitted in the table. For example, when the table gives URL, the actual name will be STORK_SERVER_HOOK_LDAP_URL.

Connection to LDAP Server

You must configure a connection from Stork to the LDAP server. This is used by Stork itself to connect to the directory, make queries, and verify passwords.

• STORK_SERVER_HOOK_LDAP_URL

Specify the URI to your LDAP server. It must include protocol and port. For example, ldap://nyc-dc1.example.com:389 or ldaps://198.51.100.42:636.

• STORK_SERVER_HOOK_LDAP_BIND_USERDN

Provide the user identity the Stork server will use to login to the LDAP server (also called binding). You must provide a fully qualified Distinguished Name (DN). This is not necessarily a regular user, nor a user of Stork. The DN context of this user may differ from STORK_SERVER_HOOK_LDAP_ROOT.

• STORK_SERVER_HOOK_LDAP_BIND_PASSWORD

Indicate the password for the user given in STORK_SERVER_HOOK_LDAP_BIND_USERDN. If the password contains characters special to the Unix shell, they may need to be quoted, or escaped with a backslash.

LDAP Details

You must tell Stork how to find your users and groups in the directory.

• STORK_SERVER_HOOK_LDAP_ROOT

Specify an LDAP naming context used as the base DN for all LDAP queries. You must provide a fully qualified Distinguished Name (DN). You may use the root of your directory. For example, DC=example,DC=com. If all Stork users and groups can be found within a particular Organizational Unit, limiting the context can improve performance. For example, OU=InfoTech,OU=Widgets Division,DC=example,DC=com.

• STORK_SERVER_HOOK_LDAP_OBJECT_CLASS_USER_ID
• STORK_SERVER_HOOK_LDAP_OBJECT_CLASS_GROUP

The LDAP hook has several options that control the names used in LDAP queries. These must match your own LDAP implementation. Two in particular will need to be adjusted if you are using Microsoft Active Directory.

OBJECT_CLASS_USER_ID defines the name of the property that represents the user's login ID (also called username, UID, logon name, etc.). By default, this is uid. With Active Directory, this should be set to sAMAccountName (the odd capitalization is correct).

OBJECT_CLASS_GROUP defines the name of the class that represents a group. By default, this is groupOfNames. With Active Directory, this should be set to group.

The hook documentation provides the complete list of LDAP names you can modify.

Nested Groups

If you plan to use LDAP groups with Stork, you should be aware of the following limitation.

Some LDAP implementations allow groups to be nested. That is, one group can be placed inside another group. For example, if a group routeradmins is made a member of a groupnetadmins, then any user placed in the routeradmins group should automatically become a member of the netadmins group.

As of version 2.0.1, Stork does not recognize nested group memberships. Stork will only see users who are directly placed in any groups you specify. To continue our example, if Stork was configured to use netadmins, then placing a user in the routeradmins group would not work for Stork. The users would have to be placed in the netadmins group as well.

This may change in a future release of Stork.

User Access

Optionally, you can limit Stork logins to a particular LDAP group.

• STORK_SERVER_HOOK_LDAP_GROUP_ALLOW

If defined, Stork login will be allowed only for members of the specified LDAP group. You must provide the Common Name of the group (without CN= prefix). Use this if not all LDAP users should be permitted login to Stork. For example, if you have an LDAP group netadmins, you might specify that here, and then only your network admins will be able to login to Stork.

This is independent of the group mapping feature (MAP_GROUPS). You can restrict Stork login without mapping Stork roles. You can map Stork roles without restricting Stork login. However, it often makes the most sense to use both features together.

Group Mapping

Optionally, you can configure mapping between LDAP groups and Stork roles. This allows Stork to automatically follow permission changes in your organization's directory.

If you do not enable group mapping, all Stork users are granted the super-admin role.

If you enable group mapping, but a user is mapped to neither super-admin nor admin, that user will have no permissions in Stork. Such a user will be allowed to login to Stork, but then receive repeated error messages. To avoid this, make sure all users are mapped to one of the Stork roles, and/or, deny other users using the GROUP_ALLOW feature above.

• STORK_SERVER_HOOK_LDAP_MAP_GROUPS

First, this must be set to true to enable the group mapping feature.

• STORK_SERVER_HOOK_LDAP_GROUP_SUPER_ADMIN

Members of this LDAP group will be granted the super-admin role in Stork. Specify the Common Name of an LDAP group (without CN= prefix).

• STORK_SERVER_HOOK_LDAP_GROUP_ADMIN

Members of this LDAP group will be granted the admin role in Stork. Specify the Common Name of an LDAP group (without CN= prefix).

Troubleshooting

• STORK_SERVER_HOOK_LDAP_DEBUG

Set this to a true value (1 or true) to have the LDAP hook log details of the LDAP protocol messages it exchanges with the LDAP server. This can help you determine exactly where things are going wrong.

Normally, this should be kept disabled (0 or false), the default.

Examples

Simple

The following is an example of what a very simple /etc/stork/server.env with LDAP might look like. This would allow any user recognized by LDAP to login to Stork with the super-admin role.

STORK_DATABASE_PASSWORD=DoNotUseExamplePasswords
STORK_SERVER_HOOK_LDAP_URL=ldaps://198.51.100.42:636
STORK_SERVER_HOOK_LDAP_BIND_USERDN=CN=ldapguest,DC=example,DC=net
STORK_SERVER_HOOK_LDAP_BIND_PASSWORD=hunter2
STORK_SERVER_HOOK_LDAP_ROOT=DC=example,DC=net

Microsoft Active Directory

The following is an example of what a /etc/stork/server.env could look like, for an LDAP integration with Microsoft Active Directory. This demonstrates most of the features described above, including optional features. Only members of the netadmins group can login to Stork, and their Stork role is based on membership in the storkadmins and storksupers groups.

STORK_DATABASE_PASSWORD=DoNotUseExamplePasswords
STORK_SERVER_HOOK_LDAP_DEBUG=false
STORK_SERVER_HOOK_LDAP_URL=ldap://nyc-dc1.example.com
STORK_SERVER_HOOK_LDAP_OBJECT_CLASS_USER_ID=sAMAccountName
STORK_SERVER_HOOK_LDAP_OBJECT_CLASS_GROUP=group
STORK_SERVER_HOOK_LDAP_BIND_USERDN=CN=ADQUERY,OU=Central IT,DC=example,DC=com
STORK_SERVER_HOOK_LDAP_BIND_PASSWORD='battery horse correct staple'
STORK_SERVER_HOOK_LDAP_ROOT=OU=InfoTech,OU=Widgets Division,DC=example,DC=com
STORK_SERVER_HOOK_LDAP_GROUP_ALLOW=netadmins
STORK_SERVER_HOOK_LDAP_MAP_GROUPS=true
STORK_SERVER_HOOK_LDAP_GROUP_ADMIN=storkadmins
STORK_SERVER_HOOK_LDAP_GROUP_SUPER_ADMIN=storksupers

See also

• Stork Quickstart guide
• Stork Administrator Reference Manual (ARM)
• Stork LDAP Hook Documentation
• stork-hook-ldap project on the ISC GitLab
• A Brief Introduction to LDAP