Skip to main content

Overview of Access Control with LDAP and PKI

Aerospike Database Enterprise Edition (EE) has a role-based access control (RBAC) system that supports several authentication modes. These authentication modes can be used separately or concurrently.

Administrators can either create users in the Aerospike server itself, assigning roles to them, or use an external LDAP system for authentication and authorization.

Configuring Access Control

For configuration instructions see Configuring Access Control.

Types of authentication

Aerospike EE supports the following types of authentication:

  • Password-based authentication for internal users defined in the server itself.
  • Public Key Infrastructure (PKI) authentication for internal users, using mutually-authenticated TLS certificates (mTLS).
  • External authentication using an LDAP server.

Using Federal Edition (FE)

When using the FIPS 140-2 compliant Aerospike Enterprise Edition for United States Federal (AKA Federal Edition or FE), password-based authentication is disabled. Use PKI authentication or external LDAP authentication

Compatible client required for Aerospike EE 4.6

When access control is enabled with Aerospike EE versions 4.6 or later, a feature-compatible Aerospike client is required.

The Aerospike Client originally supported external authentication for LDAP only. At that point, there was no support for explicit internal vs. external authentication mode, and passwords were sent both as hashed internal, and as encrypted clear-text external.

With Aerospike Server version 4.6, a change in authentication, AER-6080, caused authentication failures with older clients. This change disallows logins by external LDAP users who have internal passwords. Older client libraries fail authentication with the following message in the server log: WARNING (security): (security.c:2762) login - internal user using ldap.

Using any of the following Aerospike Client versions will cause this issue:

  • C/C++

    • 4.3.6, 4,3,7, 4.3.8, 4.3.9, 4.3.10
  • Java

    • 4.1.4, 4.1.5
  • C#

    • 3.6.1, 3.6.2
  • Python

    • 3.1.0, 3.1.1

Upgrade to the listed minimum required Aerospike Client version:

  • C/C++

    • 4.3.11 Added support for authentication mode (as_config.auth.mode)
  • Java

    • 4.1.6 Added support for authentication mode (ClientPolicy.authMode)
  • C#

    • 3.6.3 Added support for authentication mode (ClientPolicy.authMode)
  • Python

    • 3.2.0 Added a config parameter for the client constructor (auth_mode)

Client version currently NOT impacted:

  • Node.js
  • PHP
  • REST
  • Ruby
  • Rust

For the Go client library, we recommend you use at least version 1.35.1 if you have authentication enabled.

Client downloads are available at Aerospike Downloads

Compatible Aerospike EE servers required for XDR

When access control is enabled with XDR, a cluster installed with Aerospike EE versions to cannot ship to an Aerospike EE server version 4.6 or later. The simplest workaround is to avoid using incompatible Aerospike EE versions ( to Refer to the following Knowledge Base article for further details.

Access Control Features by Aerospike Database versions

  • Aerospike FE version 6.0 is FIPS 140-2 compliant
  • Aerospike EE version 5.7 added support for PKI authentication.
  • Aerospike EE version 5.6 added the ability to limit user activity by setting rate quotas on reads and writes. See Rate Quotas for more details.
  • Aerospike EE version 5.1 expanded the write privileges (write, read-write, read-write-udf) to include permission to run the truncate command within scope.
  • Aerospike EE version 4.7 added LDAP support for XDR.
  • Aerospike EE version 4.6 added the write (write only) privilege for use in defining custom roles, and added support for specifying network allowlists on these roles.
  • Aerospike EE version 4.1 added support for external authentication via LDAP.
  • Cross-Datacenter Replication (XDR) is compatible with access control as of Aerospike EE version 3.8.
  • Aerospike EE version 3.5 added support for user defined roles, scoping user permissions to a namespace or set, and scoping access logging at the namespace or set level.

Authentication for internal users

Users created within Aerospike EE (internal users) can either use password-based authentication, or mTLS-based PKI authentication.

Password-based authentication

The administrator creates users of the Aerospike cluster with a username, password, and optionally, a role assignment.

The developer configures the client to use the INTERNAL auth mode, and provides a username and password. The client sends the username and a hash of the user's password, to be matched against the one stored in the Aerospike cluster.

This is the default authentication mode of the clients.

PKI authentication

PKI authentication is an alternative authentication mode for internal users. As with any internal user, the administrator first creates the user with a username and a strong random password. If a user is restricted to only PKI mTLS-based access, the administrator does not communicate a password to them. The Aerospike EE cluster nodes must be configured to check the client's TLS certificate.

The developer sets the client to use the PKI auth mode, and configures it for mTLS (refer to Managing mTLS with a Java client). The CN field of the Subject DN must contain the username of this user. The user's certificate must be signed by the server's root CA.

External authentication with LDAP

An Aerospike Database cluster which has LDAP enabled supports authentication against an external LDAP server, without matching internal users. Currently, internal users cannot use LDAP authentication. An internal user (one that was created in the Aerospike Database cluster and given a username and password) can only use the access control modes described earlier (password-based or PKI auth).

The developer sets the client to use the EXTERNAL auth mode, and provides a username and password. The Aerospike server authenticates these credentials against the external LDAP server. Authorization happens when the Aerospike server querying the LDAP server for the user's roles. Roles that match local role names are assigned to the user, granting the privileges associated with these roles.

Aerospike Database caches a local copy of successful authentication and authorization. This local directory is distributed to every cluster node for lower query latency and reduced load on the LDAP server. The external LDAP server is queried on a configurable polling period for changes to the user's access.

For specific instructions, refer to Configuring LDAP.

TLS encryption between the client and server should be enabled when external authentication is used, since the external LDAP server needs a cleartext password forwarded to it.


Regardless of the authentication mode, if the authentication succeeds, an access token is returned to the client. The client uses the access token on subsequent TCP connections, until the session it is associated with expires. See the session-ttl configuration parameter.

Note: The password sent by the client for any mode (password-based or LDAP) is never stored on the Aerospike server.