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.

Note

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://192.0.43.10

Transport

LDAP (unencrypted) or LDAP with StartTLS (encrypted)

Warning

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.

Tip

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.

Multi-Variable¶

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
role:
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.

Use LDAP search¶

This option is appropriate if your directory has a structure such as the following:

ou=people,dc=example,dc=com
  dn=employeeId=1234,ou=people,dc=example,dc=com
    uid=alice
    givenName=Alice
    surname=Smith
    homeDir=/users/alice
    ...
  dn=employeeId=5678,ou=people,dc=example,dc=com
    uid=bob
    givenName=Robert
    surname=Jones
    homeDir=/users/bob
    ...

If user Alice Smith logs in with "alice" for the X-Auth-User, it cannot be found directly in the DN, so we must configure a search. For this example:

Set User search DN field to ou=people,dc=example,dc=com.

Set User search template field to uid={username}.

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:

ou=products,dc=example,dc=com
  ou=swift_product,ou=products,dc=example,dc=com
    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:

cn=admins,ou=groups,dc=example,dc=com
  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:

Note

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.

posixGroups¶

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

groupOfNames¶

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

Configure LDAP Search¶

The process of authenticating and authorizing an LDAP user is likely to require the system to perform LDAP queries beyond simple LDAP bind (password verification) operations. These LDAP queries include:

If Use A Fixed Template is not configured, then looking up a user requires searching the directory for an attribute-value pair.
If Whitelist/Blacklist Filters are configured, then the system must retrieve the user's attributes to check if the user should be filtered.
If Grant access only to members of a certain LDAP group is selected, the system must look up that group's membership.
If Use LDAP groups for authorization is selected, then the system must query all groups to find the ones containing the user as a member.

Because of this, the system needs a way to perform read-only searches of the LDAP directory.

Some LDAP directories are configured to allow anonymous clients to perform searches. If this is your situation, select Anonymous LDAP Search for your LDAP search method.

However, for security reasons, it is common for LDAP administrators to prohibit anonymous searches. In this case, you will need to use a role account to perform the search. If your LDAP search role account has the DC uid=search_user,ou=roles,dc=example,dc=com, then you would select Authenticated LDAP Search and configure the fields like this:

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.

Submit¶

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