Configuring LDAP

LDAP is an Aerospike Enterprise Edition feature.

LDAP authentication is also known as External Authentication, as opposed to local-to-the-server authentication for internal users defined in the server itself.

Useful knowledge base article

Knowledge Base article Faq - ldap has useful information about setting up LDAP for use with Aerospike server, including examples of using standard LDAP tools likeldapsearchand other details.

Aerospike versions for LDAP

To use LDAP, the following minimum client API versions are required. Without these versions, LDAP cannot be used.

• Java 4.1.4
• C / C++ 4.3.6
• C# .NET 3.6.1
• Python 3.1.0

Required and optional settings for LDAP

This section details settings in the feature-key-file and the aerospike.conf configuration file.

Required features in features.conf

The features.conf file must include asdb-ldap set to true.

Required and optional parameters in aerospike.conf

For fuller examples of these configuration parameters in use, see Example LDAP configurations.

Desired configurations	Example stanzas and parameters
The configuration file must have a security stanza, which must include an ldap sub-stanza. For Database 5.7 and later, the presence of these two stanzas enables security and LDAP. The enable-security and enable-ldap items are unrecognized, and their presence in the configuration file will prevent the server from starting. For versions prior to Database 5.7, enable-security must be set true and enable-ldap must be set true within the security stanza.	security { ... security settings ldap { ... LDAP settings }
Because passwords are sent in cleartext to the LDAP service, Aerospike strongly recommends that you implement Transport Layer Security (TLS). For TLS, the network stanza of the configuration file must includes the tls parameter and definitions of hostnames, cluster names, or other settings depending on your desired configuration. For full example configurations, see Transport Layer Security (TLS) and TLS Configuration.	network { tls tlsname1 { ... TLS settings } tls tlsname2 { ... TLS settings } ... }
If you are using Cross-Datacenter Replication (XDR): The configuration file must enable XDR with an xdr stanza. In the xdr stanza, for each datacenter definition that should authenticate with LDAP, the parameter auth-mode should be set external. Aerospike recommends that you do not set auth-mode to external-insecure. Full example XDR configurations are in Cross-Datacenter Replication (XDR).	xdr { dc someDataCenter { auth-mode external ... other datacenter settings } ... }

LDAP optional parameters

• In the security stanza, the optional ldap-login-threads specifies the number of threads to use for LDAP logins.

All other LDAP options belong to the ldap sub-stanza of the security stanza.

• disable-tls <true|false> whether to disable the use of TLS for LDAP server connections.
• polling-period <integer> how frequently (in seconds) to query the LDAP server for user group membership information. Allowable range is 0 to 86400 (24 hours). A value of 0 means do not poll. Default: 300 (5 minutes). Dynamic.
• query-base-dn <string> distinguished name of the LDAP directory entry at which to begin the search when querying for a user's group membership information. Required option. Certain characters in the value of this parameter must be escaped. See Parameters whose values must be escaped.
• query-user-dn <string> distinguished name of the user designated for user group membership queries. Certain characters in the value of this parameter must be escaped. See Parameters whose values must be escaped.
• query-user-password-file <string> path to file containing clear text password for the user designated for user group membership queries.
• role-query-base-dn <string> if specified uses this value as the base dn when performing the role queries. Default: query-base-dn value is used. Certain characters in the value of this parameter must be escaped. See Parameters whose values must be escaped.
• role-query-pattern <string> – format for the search filter to use when querying for a user's group membership information. The substitutions for username, ${un}, and distinguished name, ${dn} will be replaced by the actual username and the actual user’s full distinguished name when constructing the search filter. If needed, multiple role-query-pattern strings can be specified separately and each will be tried in order when querying for a user's information. Required option.
• role-query-search-ou <true|false> whether to look for a user's group membership information in the organizational unit entries of the user's LDAP distinguished name. Default: false
• user-dn-pattern <string> format for the distinguished name of the LDAP directory entry to use when binding to the LDAP server for user authentication.
  • Either user-dn-pattern or user-query-pattern is required.
  • The literal ${un} must be placed in this string to specify where the user ID is inserted when Aerospike Database constructs the distinguished name.
  • Certain characters in the value of this parameter must be escaped. See Parameters whose values must be escaped.
  • For examples, see LDAP Direct Bind vs Query User DN authentication.
• user-query-pattern <string> format for the search filter to use when querying for a user's distinguished name.
  • Either user-query-pattern or user-dn-pattern is required.
  • The literal ${un} must be placed in this string to specify where the user ID is inserted when Aerospike Database constructs the search filter.
  • For examples, see LDAP Direct Bind vs Query User DN authentication.
  • As of Database 5.1, Aerospike escapes certain illegal characters in the user DN returned by the LDAP server before making role queries for the user. Previous versions would fail querying the LDAP server if such characters are present. The characters that are escaped are as follows:
    • (
    • )
    • \
    • /
    • space
• server domainNameOfLDAPserver name of the LDAP server to use. Multiple servers can be specified using a comma-delimited string without whitespace. Required option.
• session-ttl integer lifetime (in seconds) of an access token. A TCP connection attempt with an expired token will fail, and the client must log in again to get a fresh token.
• tls-ca-file string path to the CA certificate file used for validating TLS connections to the LDAP server. Must end with the file name, like /path/to/CA/cert/file. Required FOR TLS.
• token-hash-method string hash algorithm to use when generating the HMAC for access tokens.

Parameters whose values must be escaped

The values of certain configuration parameters must escape some certain illegal characters. The parameters are as follows:

• query-base-dn
• query-user-dn
• role-query-base-dn
• user-dn-pattern

The characters that must be escaped are as follows. The escape must use the hexadecimal representation of the character.

ASCII character	Hexadecimal representation
* asterisk	\2A
( left parenthesis	\28
) right parenthesis	\29
\ backslash	\5C
/ slash	\2F
space	\20

Settings in client API

For the client application to use LDAP, the client call must set the authentication mode to EXTERNAL. Client authentication mode can be used with or without XDR configured on the server. For example, for details for the C client, see Enum AuthMode.

LDAP Direct Bind vs query user DN authentication

The Aerospike server takes a username and maps it to an LDAP Distinguished Name (DN). The DN is then used for the authentication (bind) request and, in some cases, querying for groups.

If the username is not in the DN (often the case for Active Directory) or if user DNs are in different organizational units (OUs), you must set the configuration parameter user-query-pattern. This query must return exactly one user record from which the DN is extracted. For example in Active Directory the configuration would be something like:

user-query-pattern (&(objectCategory=Person)(sAMAccountName=${un}))

The username gets substituted in for the ${un} so in the above case if the username were jane_doe:

• The actual query would be (&(objectCategory=Person)(sAMAccountName=jane_doe)) .
• When run, the query would return the entry with a DN of cn=Jane Doe,ou=People,dc=janetsoft,dc=com

In the special case where the system's user's DNs always follow the same pattern with the username embedded, like for a fictitious company named "Johnny Corp", uid=johnny_doe,ou=People,dc=johnnycorp,dc=com, the Aerospike server saves one extra query to configure the user-dn-pattern directly and not user-query-pattern. For example, in Johnny Corp’s case, the configuration parameter would be as follows. No extra user lookup query will be made and the substituted DN will be used.

user-dn-pattern uid=${un},ou=People,dc=johnnycorp,dc=com

LDAP group mapping

For easier management, through a set of LDAP queries, Aerospike uses the external LDAP server to provide the mapping from an individual username to a list of groups. The Aerospike server configuration is described in the section LDAP Users and Groups below.

The results of this request will be stored in Aerospike’s shared System Metadata store (SMD). This allows the query responses to be shared among all Aerospike servers, reducing the query load. This request is done on a repeated basis (configurable time). If the response shows that the user has been deleted or the user has been modified, all servers will be quickly notified of the change, and all authorization will use the new authorization – including existing in-flight connections.

Aerospike’s SMD store also includes the time that the data was last updated. Aerospike will be configured to not use data past a certain age, providing some resiliency in case of LDAP server failure, but also providing protection in case of an LDAP DOS attack.

Through this mechanism, changes in user authorization and authentication will be quickly learned and used throughout the cluster, on a time-bounded basis.

The mapping of groups to individual access rights will be done through existing Aerospike configuration mechanisms, and use the existing Aerospike logging and levels. An administrator will need to create a set of groups, and determine the privilege levels of those groups, and set those groups in Aerospike using the already existing and provided tools.

LDAP users and groups

Organizing users and giving permissions in LDAP is flexible. The supported groupings to use for Aerospike roles fit into two categories:

• Groupings of users These groupings can be Posix groups, OUs like "groupOfUniqueNames", or any other entry that can be queried using either username or DN of the user. The role-query-pattern(s) are used to find these groups :

• role-query-pattern contains an LDAP query to search for an entry. Multiple may be specified for cases where groups are kept in different locations or need different queries. The queries will be run in order and all entries found will be collected.

An example configuration is as follows:

role-query-pattern (&(objectclassName=posixGroup)(memberUid=${un}))
role-query-pattern (&(ou=db_groups)(uniqueMember=${dn}))
role-query-pattern (&(ou=admins)(uniqueMember=uid=${un},dc=blastcorp,dc=com))

Note the substitutions for username, ${un}, and distinguished name, ${dn}. These will be replaced by the actual username and the actual user’s full distinguished name when the queries get run.

• User’s position in LDAP tree In some setups the user’s position within a directory tree is what determines their privilege level. For example a user such as uid=jim,ou=Users,ou=Admins,dc=blastcorp,dc=com might have groups of privileges for "Users" as well as for "Admins". If this is the case, setting role-query-search-ou to true will treat the OUs in the user’s DN as potential roles.

In all cases the CN of the entry must match an Aerospike role name to be detected as such; any others will be ignored.

Example LDAP configurations

Below are examples of LDAP configurations.

note

These examples assume Aerospike Database 5.7 or later, where the enable-security and enable-ldap configuration items are obsolete, and the presence of either of these items in the configuration file will prevent the server from starting.

These examples cannot be used directly and must be modified to match you own systems.

Example basic aerospike.conf parameters for LDAP

The values shown here are only examples.

security {
    ...
    ldap {
    # Base DN 
        query-base-dn o=LDAPvalueOfO,dc=valueOfDC,dc=com
    # Domain name or IP address and port of LDAP servers
        server ldap://someDomainMame:somePort
    # TLS
        disable-tls false
    # Location of the cert file for TLS communication with LDAP server 
        tls-ca-file /pathToSomeCertFile
    # DN of the Aerospike "trusted user" to query for roles
        query-user-dn uid=as_user,ou=Users,o=5a7b4b08f4f3414e69eb5f8c,dc=jumpcloud,dc=com
    # Path to cleartext password of the same user
        query-user-password-file /some/path/to/the_query_user_password.txt
    # Set this true to treat the OUs of the users' DN as possible roles
        role-query-search-ou true
    # This query is to search for other entries to use for roles.
    # In this case the ${dn} is replaced with the user's full DN
        role-query-pattern (&(objectclassName=groupOfNames)(member=${dn}))
    # How often to poll for new roles in seconds.
        polling-period 10
    # Pattern to look up user. ${un} is replaced with the username
        user-query-pattern (uid=${un})
    }
    ...
}

Example parameters for XDR auth-mode

The xdr stanza needed for LDAP with XDR enabled and auth-mode external is shown in Cross-Datacenter Replication (XDR).

Example JumpCloud's LDAP directory-as-a-service

security {
    ...
    ldap {
    # base dn will be different for every jumpcloud instance
        query-base-dn o=5a7b4b08f4f3414e69eb5f8c,dc=jumpcloud,dc=com
    # ldap server(s) to use
        server ldap://ldap.jumpcloud.com:389
    # this is the default, but we want to use tls
        disable-tls false
    # location of the cert file needed for TLS communication with the jumpcloud server
        tls-ca-file /etc/ssl/certs/jumpcloud.chain.pem
    # this is the dn of the aerospike "trusted user" which queries for roles
        query-user-dn uid=as_user,ou=Users,o=5a7b4b08f4f3414e69eb5f8c,dc=jumpcloud,dc=com
    # path to cleartext password of the same user
        query-user-password-file /some/path/to/the_query_user_password.txt
    # set this to true to treat the OUs of the users dn as possible roles
        role-query-search-ou true
    # this query will be used to search for other entries to use for roles.
    # in this case the ${dn} will be substituted with the user's full dn
        role-query-pattern (&(objectclassName=groupOfNames)(member=${dn}))
    # how often to poll for new roles. We are doing it every 10 seconds for development testing
        polling-period 10
    # pattern to look up user. ${un} will be replaced with the username
        user-query-pattern (uid=${un})
    }
    ...
}

Example Active Directory configuration

Query user DN, no TLS, trusted role poling user, and multiple group types:

security {
    ldap {
        query-base-dn dc=aerospike,dc=com
        server ldap://blast.aerospike.com:389
        # This server does not support TLS
        disable-tls true
        query-user-dn CN=Trusted\20User,CN=Users,DC=aerospike,DC=com
        query-user-password-file  /path/to/password_file.txt
        role-query-search-ou true
        role-query-pattern (&(objectclassName=posixGroup)(memberUid=${un}))
        role-query-pattern (&(objectclassName=group)(member=${dn}))
        role-query-pattern (&(ou=*)(uniqueMember=uid=${un},dc=aerospike,dc=com))
        polling-period 20
        user-query-pattern (sAMAccountName=${un})
    }
    log {
        report-violation true
    }
}

Example OpenLDAP configurations

Direct bind pattern, TLS, anonymous role binding, and POSIX groups:

security {
    ldap {
        query-base-dn dc=aerospike,dc=com
        server ldap://localhost:389
        tls-ca-file /etc/ssl/certs/ca_server.pem
        user-dn-pattern uid=${un},ou=People,dc=aerospike,dc=com
        role-query-search-ou true
        role-query-pattern (&(objectclassName=posixGroup)(memberUid=${un}))
        polling-period 10
    }
    log {
        report-violation true
    }
}

Query user DN, TLS, trusted role polling user, and multiple group types:

security {
    ldap {
        query-base-dn dc=aerospike,dc=com
        server ldap://ldaptest.aerospike.com:389,ldap://localhost:389
        tls-ca-file /etc/ssl/certs/ca_server.pem
        query-user-dn uid=aero,dc=aerospike,dc=com
        query-user-password-file /path/to/password_file.txt
        role-query-pattern (objectclassName=group)
        role-query-pattern (&(ou=*)(uniqueMember=uid=${un},dc=aerospike,dc=com))
        role-query-pattern (&(objectclassName=posixGroup)(memberUid=${un}))
        polling-period 10
        user-query-pattern (&(uid=${un})(|(objectclassName=inetOrgPerson)(objectclassName=posixAccount)))
    }
    log {
        report-violation true
    }
}

LDAP debugging tips

Using ldapsearch

When configuring LDAP in Aerospike, especially in writing your queries (filters in LDAP) it is helpful to have the full LDAP records for both a typical LDAP user and the groups to use for Aerospike roles.

One way to get this information is with ldapsearch.

Example ldapsearch queries

• For a user:

ldapsearch -w password -D CN=trusted_user,OU=ServiceAccount,DC=example,DC=com -b dc=example,dc=com -h ldap://ldap.example.com:389  '(uid=my_user)'

• For a group:

ldapsearch -w password -D CN=trusted_user,OU=ServiceAccout,DC=example,DC=com -b DC=example,DC=com -h ldap://ldap.example.com:389  '(CN=some_group)'

For other examples, see Examples of Common ldapsearches.

If you have TLS enabled you must add your certs on the client machine and either an ldap.conf file must be created, or environment variables must be set. For more details, see Using LDAP.

ldapsearch is also useful to test your query patterns. The pattern can be plugged directly to the earlier queries (replacing the (CN=some_group) in the above example) but with a value substituted in for the ${un} placeholder.

For example, if you have a configuration like role-query-pattern (&(objectclassName=posixGroup)(memberUid=${un})) you can see if the query is valid for a perspective user with a uid of joe_user by issuing a command like:

ldapsearch -w password -D CN=trusted_user,OU=ServiceAccout,DC=example,DC=com -b DC=example,DC=com -h ldap://ldap.example.com:389  '(&(objectclassName=posixGroup)(memberUid=joe_user))'

Extra logging

You can turn on extra logging to see what role queries are being made for login, polling, and other verbose information. In the logging section of your configuration file, specify either of the following or both:

    console {
        context any critical
        context security detail
    }

or

    file <filename> {
        context any critical
        context security detail
    }

To activate detailed security logging dynamically on a running system, run the following command:

Note: Tools package 6.0.x or later is required to use asadm's manage config commands. Otherwise, use the equivalent asinfo - log-set

    asadm -e 'enable; manage config logging file <filename> param security to detail'