LDAP-based Authentication for SwiftStackAuth

This middleware is designed to allow a company's LDAP authentication information to verify the Swift X-Auth-User and X-Auth-Key fields as a user logs in.

To get to the configuration page, sign into your SwiftStack Controller account, click on the Clusters tab and then click Manage for the cluster. Click the Middleware tab. Under the Available Swift Middleware section, locate and click on the LDAP-based Authentication for SwiftStackAuth row.


Be sure the Enabled box is checked if you want the settings you provide on the page to be used to authenticate users.

All fields above the individual LDAP server configurations are required.


This field is filled in by default.


This field is filled in by default.


If more than one type of authentication middleware is being used simultaneously, the account_prefix and the auth_prefix fields may need to be modified. Please consult with SwiftStack Support to determine the correct values needed.


This time is how long to cache the results of an LDAP lookup. A default time is provided and can be changed to any preferred time (0 or greater).


This time is how long to cache the results of an LDAP lookup. A default time is provided and can be changed to any preferred time (0 or greater).

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.

Select your Swift account authorization model

Selecting Use LDAP groups will allow an authenticated user access to both Swift accounts named for the groups they are a member of, as well as the account whose name matches their LDAP login name.

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.


Remember to Deploy Middleware Changes to apply any changes.

Command Line: Using python-swiftclient with LDAP

When you provide your X-Auth-User and X-Auth-Key to the swift command-line utility or the python-swiftclient library, it returns a storage url and the auth token. This auth token works with any account the user has access to, but the storage url will only access the user's account, not any account they may have access to via group membership. To access a group's account, replace LDAP_<username> with LDAP_<group name> in the storage url.

swift Example

$ swift stat -v -A -U some -K password
Auth Token: AUTH_tkfd3b7b695a4f4de1a8c287898a4b4465
   Account: LDAP_some
Containers: 0
   Objects: 0
     Bytes: 0
Meta Temp-Url-Key: ed94262e-0e66-4333-9f9e-809f2acf8574
X-Timestamp: 1371503771.31799
X-Trans-Id: tx7aa7b4f4c1dc4918aab6e95e163b8901
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
$ swift post --os-storage-url --os-auth-token AUTH_tkfd3b7b695a4f4de1a8c287898a4b4465 containerA
$ swift list --os-storage-url --os-auth-token AUTH_tkfd3b7b695a4f4de1a8c287898a4b4465

swiftclient Example

from swiftclient import get_auth_1_0, head_account
import re

auth_url = "<auth_url>"
username = "<username>"
password = "<password>"
group_name = "<group name>"

url, token = get_auth_1_0(auth_url, username, password, False)
url = re.sub(username, group_name, url)
head_account(url, token)

Disambiguating Multiple LDAP Endpoints

Since it is possible to define multiple LDAP endpoints in the middleware, it is sometimes necessary to be able to specify which endpoint to search at when authenticating. In order to do this, there is a special header named X-Auth-Domain which will allow you to specify. Unfortunately, the swift utility does not allow you to specify this header, so authenticating this way requires making HTTP requests manually, for example via cURL:

curl -H 'X-Auth-User: username' -H 'X-Auth-Key: password' -H 'X-Auth-Domain: ldap://ldap.example.com/' -D- https://swift.example.com/auth/v1.0

The value of the X-Auth-Domain header must be the same as one of the servers you have configured. If a different server name is provided, a 400 Bad Request will be returned. Otherwise, only the provided server will be searched with the given credentials.