LDAP-based Authentication for the SwiftStack Controller

In addition to using LDAP to authenticate user access to the Swift cluster (see LDAP-based Authentication for SwiftStackAuth), it is also possible to configure the SwiftStack Controller On-Premises to authenticate using LDAP. By default, the controller uses Django authentication, with credentials encrypted locally in a database on the controller server. However, for larger enterprises, privileges for using the controller to configure the Swift cluster may be stored in the corporate LDAP directory. In this case, you will want to configure LDAP authentication for the controller itself.

SwiftStack Controller On-Premises LDAP authentication can be configured on the LDAP Authentication for SwiftStack Controller Users page. You must be logged in as an administrator with superuser privileges (like the localadmin user created during controller installation).

Controller LDAP is enabled by selecting Both Django and LDAP authentication from the SwiftStack Controller authentication methods field. To disable, select Django based authentication only. Django based authentication is always available in order to provide access when LDAP servers are down or LDAP settings need to be configured. Controller "super users" can only be local Django users (like the default localadmin user created during controller installation).

"ControllerUser" LDAP group, "ControllerAdministrator" LDAP group, "ClusterOperator" LDAP group, and "ClusterAccountManager" LDAP group are required in order to map LDAP groups to controller roles. For a controller LDAP user to have the privileges of a controller role, that LDAP user must be in the corresponding LDAP group.


The controller roles are additive not heirarchical. So if you want an LDAP controller user to be a full administrator with all privileges, that LDAP user must be a member of all four role groups.


Configuration For Each LDAP Server

In a small LDAP installation, a single LDAP endpoint might contain the entire directory. However, in a large organization which has only recently merged separate divisions' LDAP installations, it may be necessary to query several independent LDAP endpoints in order to get an authoritative answer. For this reason, SwiftStack's LDAP infrastructure supports multiple independent LDAP server configurations. The discussion below applies to each LDAP endpoint that is configured.

Required Parameters

Server URI

The Uniform Resource Identifier (URI) field should contain the ldap uri in the form of ldap://<hostname or IP address> or ldaps://<hostname or IP address>, e.g. ldap://


LDAP (unencrypted) or LDAP with StartTLS (encrypted)


If using secure LDAP (either ldaps or StartTLS), the nodes must be configured to accept the LDAP server's certificate. This is not configured by the SwiftStack controller.

User Lookup Method

In addition to the Server URI and Transport parameters, also required is a way to map usernames to LDAP Distinguished Names.


Different LDAP installations will be configured with different directory structures, so please be sure to verify the field names and types that your LDAP server supports, in order to correctly configure the LDAP support.

One of two relationships must be used.


LDAP uniquely identifies its entries by Distinguished Name (DN), but users rarely log in with the full DN. If the user's X-Auth-User (username or login identifier) can be interpolated into a fixed template (such as cn={username},ou=people,dc=example,dc=com), then LDAP support can be configured to Use a fixed template.

If the user's X-Auth-User is not part of the DN but is the value of an attribute, then Use LDAP search must be defined.

Use A Fixed Template

Single variable

X-Auth-User provided by the user is represented by the variable {username} in the LDAP settings.

Consider a directory with this structure:

dn: cn=John Doe,ou=people,dc=example,dc=com
objectClass: pilotPerson
cn: John Doe
sn: Doe
userPassword: changeme

If John Doe logs in using "John Doe" (which matches the cn) for the X-Auth-User, then:

Select Use A Fixed Template
Set Bind DN template to cn={username},ou=people,dc=example,dc=com.


If your LDAP server requires the user to provide multiple pieces of information to identify themselves then a multi-variable template or user search can be configured. For this example the LDAP server will require the user's UID, the customer's OU, and the franchise's OU. The LDAP record for a user called "1 A alpha" would look like this:

dn: uid=test_customer1a_alpha,ou=Customer1A,ou=Franchise1,dc=example,dc=com
uid: test_customer1a_alpha
cn: 1 A alpha
uidNumber: 2001
gidNumber: 10000
homeDirectory: /home/1Aa
objectclass: account
objectclass: simpleSecurityObject
objectclass: extensibleObject
objectClass: posixAccount

In this case, the user would provide a composite username for authentication separating each required part by a colon, e.g. Franchise1:Customer1A:test_customer1a_alpha.

The user input is read in order and each part numbered starting with zero. e.g. Franchise1 = 0, Customer1A = 1. These numbered variables are then used for the verification.

Select Use A Fixed Template
Set Bind DN template to uid={2},ou={1},ou={0},dc=example,dc=com.

The numbered variables may also be used in the User search DN and User search template fields as necessary.

Restrictions On Users

It may be the case that some valid LDAP users should not be allowed to authenticate. You may choose to configure access by group, whitelist restrictions (only the specified users are allowed) or blacklist restrictions (only the specified users are disallowed). You may even configure all three types, in which case the user must pass all restrictions.


Use LDAP group membership

Only LDAP users who are a member of the defined group may authenticate.

This option is appropriate if your directory maintains permissions in a structure such as the following:

    objectClass: groupOfNames
    member: uid=alice,ou=people,dc=example,dc=com
    member: uid=bob,ou=people,dc=example,dc=com
    member: ...
For this example:
Set the User auth group field to ou=swift_product,ou=products,dc=example,dc=com
Set the User auth group attr field to member

Note that the structure of an LDAP posixGroup is slightly different from a groupOfNames:

  objectClass: posixGroup
  memberUid: alice
  memberUid: bob
  memberUid: ...
For this example:
Set the User auth group field to cn=admins,ou=groups,dc=example,dc=com
Set the User auth group attr field to memberUid

Whitelist and Blacklist

Whitelist and Blacklist restrictions may be any valid LDAP filter string, which gives great flexibility. For information on LDAP search filters, many guides are available online (e.g. the guides provided by CentOS and Microsoft). For a formal reference on LDAP search filters, see the appropriate section of RFC 4511 .

To configure a restriction filter on LDAP users, select the appropriate checkbox and fill in the filter value:

../../_images/ldap-whitelist-filter.png ../../_images/ldap-blacklist-filter.png


The example filter userClass=swiftUser depends upon cosine.schema (RFC 1274) being installed and the objectClass for the user being pilotPerson. Adding arbitrary key:value pairs not defined in the object type's schema to user definitions may cause the user to fail authentication.

Define Your LDAP Group Structure

Authorization by LDAP Group is required for Controller LDAP, but optional for LDAP Auth Middleware.


There are multiple ways to configure groups under LDAP. In the event yours is not described here, please contact Technical Support for assistance.


LDAP's posixGroup entries list the shortened names of their members. If your groups belong to objectClass posixGroup and look something like

dn: cn=swiftPosix,ou=groups,dc=example,dc=com
objectClass: posixGroup
cn: swiftPosix
gidNumber: 10001
memberUid: some
Then set
Group search DN to ou=groups,dc=example,dc=com
Group search template to memberUid={uid}
Group name attribute to cn


LDAP's groupOfNames entries list the complete DNs of their members. If your group belongs to objectClass groupOfNames and looks something like

dn: cn=swift,ou=groups,dc=example,dc=com
objectClass: groupOfNames
cn: swift
member: cn=John White,ou=people,dc=example,dc=com
Then set
Group search DN to ou=groups,dc=example,dc=com
Group search template to member={dn}
Group name attribute to cn

Verify Settings

Once you have filled in the user and/or groups settings you can verify your middleware configuration in the Verify Settings section. Provide the Search user and Search user password for an account on the LDAP server and click on the Verify button.

The results will return a message about the user being found or not found.



Once you are satisfied with the configuration, click the Submit button to save it.