--- title: "Stork LDAP Authentication" slug: "stork-ldap" description: "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." updated: 2025-03-25T19:40:31Z published: 2025-03-25T19:40:31Z --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.isc.org/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/ldap-intro) 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](https://stork.readthedocs.io/en/latest/install.html#setup). 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](https://stork.readthedocs.io/en/latest/install.html#installing-from-packages). If building from source, you must obtain the LDAP hook separately, from [the LDAP hook GitLab project](https://gitlab.isc.org/isc-projects/stork-hook-ldap/). Simply unpack that into your local source tree and build the hook. See the ARM for more on [building Stork from source](https://stork.readthedocs.io/en/v2.0.0/install.html#installing-from-sources). ## 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](https://stork.readthedocs.io/en/latest/hooks/stork-server-ldap/doc/index.html). ### 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`. | Option | Description | | --- | --- | | `URL` | LDAP server to connect to | | `BIND_USERDN` | LDAP login for Stork itself to use | | `BIND_PASSWORD` | Password for `USERDN` | | `ROOT` | Base DN context for all LDAP queries | | `GROUP_ALLOW` | Limit Stork login to an LDAP group | | `MAP_GROUPS` | Map LDAP groups to Stork roles | | `GROUP_SUPER_ADMIN` | Group to map to Stork super-admin | | `GROUP_ADMIN` | Group to map to Stork admin | | `OBJECT_CLASS_USER_ID` | Needed for Active Directory | | `OBJECT_CLASS_GROUP` | Needed for Active Directory | | `DEBUG` | Log LDAP protocol (includes passwords) | ### 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](https://stork.readthedocs.io/en/latest/hooks/stork-server-ldap/doc/index.html) 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 group`netadmins`, 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. Potential Security Exposure Debugging logs details of every LDAP message. That can include passwords (in the clear) and other sensitive information. When enabled, take care that logs are secured appropriately. ## 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](/docs/stork-quickstart-guide) - [Stork Administrator Reference Manual (ARM)](https://stork.readthedocs.io/) - [Stork LDAP Hook Documentation](https://stork.readthedocs.io/en/latest/hooks/stork-server-ldap/doc/index.html) - [stork-hook-ldap project](https://gitlab.isc.org/isc-projects/stork-hook-ldap/) on the ISC GitLab - [A Brief Introduction to LDAP](/docs/ldap-intro)