Configure access control

This page describes how to enable authentication and assign roles and permissions in the Aerospike Database.

Aerospike Database uses role-based access control (RBAC) to manage internal and external users. It is available in Aerospike Database Enterprise Edition (EE), and the FIPS 140-2-compliant Aerospike Database Enterprise Edition for United States Federal (FE).

Aerospike supports LDAP, PKI, and password-based authentication modes that are described in detail in Access Control with LDAP and PKI.

Database requirements

• Aerospike Database Enterprise Edition (EE), or Aerospike Database Enterprise Edition for United States Federal (FE).

Client requirements

The following table shows the minimum client version for the following security features:

Client	RBAC support	LDAP support	Rolling restart to enable RBAC	PKI auth support (Database 5.7 or later)
Java	3.1.2	4.1.6	4.4.4	5.1.8
C	3.1.16	4.3.11	4.6.5	5.2.3
C#	3.1.2	3.6.4	3.8.2	4.2.3
Go	1.3.0	1.35.1	2.3.0	5.6.0
Python	1.0.44	3.2.0	3.7.3	6.1.0
Node.js	1.0.35	3.3.0	3.12.0	4.0.5, 5.0.3
Ruby	1.0.0	-	-	-
Rust	1.1.0	-	-	-

Enable access control with rolling restart

You can enable RBAC in Aerospike EE with a rolling restart.

During a rolling restart activation of RBAC, some nodes in the cluster authenticate the clients and some don’t yet. Verify that your client versions supports this mixed environment prior to initiating the rolling restart.

Enable access control node-by-node

In a running cluster, execute the following steps node-by-node. If the node isn’t running, skip to step (3):

1. Quiesce the node.
2. Stop the Aerospike server.
3. In the configuration file(aerospike.conf), verify that a security stanza is present.

a. In Database 5.7 and later, the presence of a security stanza enables security and access control. The server does not recognize enable-security and will not start if it is present.

b. Prior to Database 5.7, in the security stanza, set enable-security to true.

4. (Optional) Set enable-quotas to true in the security stanza to enable rate quotas.

    security {
        # enable-security true # versions < 5.7 only
        enable-quotas true

        # Other security-related configuration...
    }

Note

To change the default password for the admin user, edit the default-password-file configuration parameter which was introduced in Database 7.1.

5. Start the Aerospike server.

6. Verify that access control is enabled on the cluster. Use asadm to connect to the server.

• Aerospike EE: Log in with the default username admin and password admin.
• Federal Edition: An admin user must create and sign the certificate.

7. Use asadm -U USERNAME to change the password. Replace USERNAME with your username. For example:

asadm -U admin

Privileges

Privileges are a fundamental unit of RBAC, and cannot be modified.

• A privilege consists of permissions and a scope.
• The scope is global, per namespace, or per set within a specified namespace.
• A role is a collection of scoped privileges, and roles are granted to users.

The following table describes permissions and the scope corresponding with each privilege.

Privilege	Permission	Scope
read	- Get record - Scan - Query - Get server configuration and statistics - Change user password	Global, per namespace, or per set in a namespace.
write	- Record-level write commands such as put, touch, delete -Bin-level write commands such as List or Map write commands - Truncate or undo a truncation of namespaces or sets permissions (Only in 5.7 and earlier. Permissions moved to truncate in 6.0)	Global, per namespace, or per set in a namespace.
read-write	- All read user role privileges - All write user role privileges	Global, per namespace, or per set in a namespace.
read-write-udf	- All read-write user role privileges - Execute User-Defined Functions (UDFs) - Execute queries using UDFs	Global, per namespace, or per set in a namespace.
truncate (Database 6.0+)	- Truncate or undo a truncation of namespaces or sets	Global, per namespace, or per set in a namespace.
data-admin	- Create and drop secondary indexes - Register and remove UDFs - Use the scan-query job monitoring system - Abort scans and queries - Change user password - Truncate or undo a truncation of namespaces or sets	Global
sindex-admin (Database 6.0+)	- Create and drop secondary indexes	Global
sys-admin	- All data-admin role privileges - Set dynamic server configuration variables - Enable specialized logging - Get server configuration and statistics	Global
udf-admin (Database 6.0+)	- Register and remove UDFs	Global
user-admin	- Create and drop users - Change any user password - Grant roles to users - Revoke user roles - Create and drop user roles - Grant user role privileges - Revoke role privileges - Set allowlists for roles - Set read/write rate quotas for roles - Query all users and their roles - Query all roles and their privileges - Get server configuration and statistics	Global

Commands for managing roles

Aerospike provides pre-defined roles corresponding with each privilege. Each has a name matching the single privilege, such as read-write.

Pre-defined roles have a global scope. They cannot be modified. They can only be assigned as-is to users.

For instructions on how to to manage roles and users with the Admin tool, asadm, see Create and manage users.

Create a role

The asadm command to create a new role is:

manage acl create role <role-name> priv <privilege> [ns <namespace> [set <set>]] [allow <addr1> [<addr2> [...]]] [read <read-quota>] [write <write-quota>]

Example

manage acl create role superusers priv read-write-udf

Add a privilege to a role

The asadm command to add a privilege to a role is:

manage acl grant role <role-name> priv <privilege> [ns <namespace> [set <set>]]>

Example

manage acl grant role demo-users priv read-write-udf ns test set demoset

Remove a privilege from a role

The asadm command to remove a privilege from a role is:

manage acl revoke role <role-name> priv <privilege> [ns <namespace> [set <set>]]>

Example

manage acl revoke role demo-users priv read-write-udf

Add an IP address to a role’s allowlist

The asadm command to add an IP address or range to a role’s allowlist is:

manage acl allowlist role <role-name> allow <addr1> [<addr2> [...]]

Examples

manage acl allowlist role superusers allow 10.0.0.1

manage acl allowlist role demo-users allow 127.0.0.0/8

Clear a role’s allowlist

The asadm command to clear an allowlist from a role is:

manage acl allowlist role <role-name> clear

Example

manage acl allowlist role demo-users clear

Delete a role

The asadm command to delete a role is:

manage acl delete user <username>

Example

manage acl delete role demo-users

Create and manage users

When RBAC is first enabled in an Aerospike EE cluster, it comes with a default admin user that has the permissions to create new users.

• In Aerospike EE the default credentials are username:admin, password: admin. To change the default password for the admin user, edit the default-password-file configuration parameter which was introduced in Aerospike Database 7.1.
• In Aerospike Federal Edition password authentication is disabled. You must create and sign a TLS certificate for the admin user, in order to use PKI authentication. See Generate TLS certificate requests.

Set a new password

The asadm command to set a password for an existing user is:

manage acl set-password user USERNAME [password PASSWORD]

Caution

In tools package 7.1.1 (asadm 2.8.1) and earlier, asadm (formerly performed in aql) limits the characters you can use when setting a password. Valid passwords can contain alphanumeric characters and the symbols .*-:/_{}@. White space is not supported.

When setting a user password with a hidden prompt these restrictions do not apply.

Example

manage acl set-password user admin

Create a user

The asadm command to create a user is:

manage acl create user <username> [password <password>] [roles <role1> <role2> ...]

Examples

manage acl create user alice password alicepass roles superusers

manage acl create user bob password bobpass roles user-admin demo-users aaargh-users

Grant a role to a user

The asadm command to add one or more roles to a user is:

manage acl grant user <username> roles <role1> [<role2> [...]]

Examples

manage acl grant user alice roles superusers

manage acl grant user bob roles user-admin demo-users aaargh-users

Revoke a user’s role

The asadm command to revoke one or more roles previously granted to a user is:

manage acl revoke user <username> roles <role1> [<role2> [...]]

Examples

manage acl revoke user alice roles superusers

manage acl revoke user bob roles user-admin demo-users

Delete a user

The asadm command to delete a user is:

manage acl delete user <username>

Example

manage acl delete user jdoe

PKI authentication

For PKI authentication:

• Verify that the server is using Mutual TLS (mTLS). If it is not, see TLS Configuration for configuration instructions.
• Create a user and grant them privileges and roles.
• Generate an SSL certificate for the user, with the username as the Common Name CN.
• Sign the certificate using the server root certificate authority (CA). For instructions, see Generate TLS certificate requests.

Note

If you are using Aerospike Federal Edition (FE) you cannot use password authentication. Use PKI authentication or LDAP, which are available for both EE and FE.

Example

asadm -p 4333 --tls-enable --tls-name server \
--tls-certfile=/root/rootca/output/admin.pem --tls-keyfile=/root/rootca/output/admin.key \
--tls-cafile=/etc/aerospike/tls/server/rootCA.pem --auth=pki

Protecting SMD files

The /opt/aerospike/smd/security.smd file stores sensitive information about users and roles. For security reasons, we recommend you secure this file and restrict the permissions.

The default permission on all SMD files grants read access to everyone. To secure the file, change the permissions of the /opt/aerospike/smd directory and its contents.

1. Set permissions on the /opt/aerospike/smd directory:

chmod 700 /opt/aerospike/smd

2. Set permissions on the /opt/aerospike/smd/security.smd file:

chmod 600 /opt/aerospike/smd/security.smd

3. Optional: Use chmod 600 to restrict permissions on other SMD files you want to protect in the /opt/aerospike directory.

chmod 600 /opt/aerospike/smd/FILENAME

Replace FILENAME with the name of the file you want to protect.

4. To verify permissions in the /opt/aerospike directory, list its contents:

ls -la /opt/aerospike/

Expected output after permissions are set:

drwxr-xr-x 1 aerospike aerospike 4096 Apr 24 13:17 .
drwxr-xr-x 1 root      root      4096 Apr 24 13:17 ..
drwxr-xr-x 2 aerospike aerospike 4096 Apr 24 13:17 bin
drwxr-xr-x 2 aerospike aerospike 4096 Nov 10  2020 data
drwxr-xr-x 2 aerospike aerospike 4096 Apr 24 13:17 doc
drwxr-xr-x 4 aerospike aerospike 4096 Apr 24 13:17 lib
drwx------ 1 aerospike aerospike 4096 Jun 22 12:26 smd   <<<<
drwxr-xr-x 3 aerospike aerospike 4096 Apr 24 13:17 usr

5. To verify permissions in the /opt/aerospike/smd directory, list its contents:

ls -la /opt/aerospike/smd

Expected output after permissions are set:

drwx------ 1 aerospike aerospike 4096 Jun 22 12:26 .
drwxr-xr-x 1 aerospike aerospike 4096 Apr 24 13:17 ..
-rw-r--r-- 1 root      root       292 Jun 22 10:12 sindex.smd
-rw-r--r-- 1 root      root       289 Jun 22 12:26 truncate.smd
-rwx------ 1 root      root       289 Jun 22 12:26 security.smd

Audit trail

You can configure Aerospike EE to log security events to an audit log. Each cluster node has a separate audit trail. Refer to Configuring Log Streams for more information.

Aerospike supports an audit trail with granular control over the type of security events being logged:

• Security violations (including authentication or role violations).
• Successful authentications.
• Successful or attempted data commands including various write/read commands.
• User administration operations, including:
  • Creating/removing users.
  • Granting/revoking user roles.
  • Creating/removing roles.
  • Granting/revoking role privileges.
• System administration operation including:
  • Creating/removing secondary indexes.
  • Registering/removing UDFs.
  • Changing dynamic server configurations.

In general, auditing security violations and other rare events have minimal performance impact. However, logging every attempted or successful data commands on numerous data sets can slow runtime performance in systems under heavy load. This level of logging also increases storage requirements for the logs.

If you plan to maintain extensive audit records, we suggest you review potential performance impact and storage needs in a test environment first.

General

• Security violations, see report-violation.

Authentication

• Authentication failure, see report-violation.
• Successful authentications, see report-authentication.
• Successful data transactions, see report data transactions.

Users

• Role violation, report violation.
• User administration operations, see report user admin:
  • Create or drop user.
  • Change user password.
  • Grant roles to user.
  • Revoke roles from user.
  • Create or drop role.
  • Grant privileges to role.
  • Revoke privileges from role.
  • Set allowlist for role.
  • Set read/write rate quotas for role.
  • Query users and their roles.
  • Query roles and their privileges.

System administration

• System administration operations:
  • Create or drop index.
  • Register or remove UDFs.
  • Set dynamic server configuration variables.
  • Enable specialized logging.
  • Get server configuration, server statistics, and other information.

Configuring the audit trail in Database 6.3 and later

Starting with Database 6.3, the syslog subcontext of the security configuration context has been removed because any log message, including the audit logging context, can be sent to any log sink, including syslog-compatible socket log sinks. The following example shows how to configure an audit trail starting with Database 6.3.

security {
    log {
        report-authentication true
        report-user-admin true
        report-sys-admin true
        report-violation true
        report-data-op test demoset # report successful data transactions on set "demoset" in namespace "test"
    }
}

The logging configuration context defines log sinks, with each having the ability to filter log messages by context and level.

Logging audit trail messages to a syslog-compatible socket

Combined with the configuration above, audit context log messages will be sent to the local0 syslog facility.

logging {
    syslog {
        facility local0
        tag aerospike-audit
        context any critical
        context audit info
    }
}

Configuring the audit trail in versions prior to Database 6.3

Turning on the audit trail is done in the security configuration context. For details about these configuration parameters, see the Configuration Reference.

Logging audit trail messages to file sinks

The following configuration sends audit trail messages to the file log sinks defined in the logging configuration context, where log messages can be filtered by message context and log level.

security {
    log {
        report-authentication true
        report-user-admin true
        report-sys-admin true
        report-violation true
        report-data-op test demoset # report successful data transactions on set "demoset" in namespace "test"
    }
}

Logging audit trail messages to syslog

Prior to Database 6.3, only audit trail log messages could be sent to syslog, through a special configuration of the security config context. Destinations included:

• Local syslog facility (local file)
• Syslog daemon default sink

security {
    syslog {
        local 0 # write to "local0" facility
        # write audit trail messages to the default syslog facility
        report-authentication true
        report-user-admin true
        report-sys-admin true
        report-violation true
        report-data-op test demoset # report successful data transactions on set "demoset" in namespace "test"
    }
}

The following example configures rsyslog to send locally written audit information to syslog, with the following line added to /etc/rsyslog.conf:

 local0.**    /var/log/aerospike_security_audit.log

Then restart rsyslogd.

Parsing audit trail log messages

The log message says in plain text what security action was attempted if any, and whether it succeeded or failed, and which user if any was involved.

Namespaces and sets are in braces: {namespace|set} or just {namespace|}

Custom role privileges are letter codes that correspond to Aerospike pre-defined privileges, and are followed by {namespace|set} scoping if applicable.

The letter codes are:

• r = read
• rw = read-write
• rwf = read-write-udf
• t = truncate
• w = write
• d = data-admin (a global privilege, scoping not applicable).
• fa = udf-admin (a global privilege, scoping not applicable).
• ia = sindex-admin (a global privilege, scoping not applicable).
• s = sys-admin (a global privilege, scoping not applicable).
• u = user-admin (a global privilege, scoping not applicable).

For example:

• rw{} indicates read-write privileges across all namespaces.
• r{test},rw{ns2} indicates read privileges for the test namespace and read-write privileges for the ns2 namespace.
• u,rwf{test|demoset} indicates user-admin privileges as well as read-write-udf privileges for demoset in the test namespace.

If the key is stored, key data is logged with successfully-authenticated data transactions and data transactions that fail due to role violations. If the key is not stored, the digest is logged. The eventual success or failure of the transaction does not affect this behavior, since logging happens at the point at which authentication is checked.

Key data appears as:

• [S|mykey] if the key is a string.
• [I|78654] if the key is an integer.
• [B|AA C5 48] if the key is a blob of bytes.

If the key is not stored, the digest is logged as a string:

• [D|567895f996dd7dd3832222b57cd4a3031ecc6e24]

Example

The following is an example of audit trail output. The logging context for the audit trail output is “audit”.

Expected output:

Sep 01 2021 18:37:56 GMT: INFO (audit): (security.c:7608) permitted | client: 127.0.0.1:51378 | authenticated user: user2 | action: login | detail: user=user2
 Sep 01 2021 18:37:56 GMT: INFO (audit): (security.c:7608) permitted | client: 127.0.0.1:51380 | authenticated user: user2 | action: authentication | detail: user=user2
 Sep 01 2021 18:37:56 GMT: INFO (audit): (security.c:7608) permitted | client: 127.0.0.1:51380 | authenticated user: user2 | action: read | detail: {test|eg-set} [D|1142f0217ababf9fda5b1a4de66e6e8d4e51765e]

Security features by Database version

Support for various features and security modes has evolved as the Aerospike server and clients have evolved.

• Database 6.3: Removed the syslog subcontext of the security config context. Audit trail messages can be sent to any log sink type (file, console or syslog) that is defined in the logging config context.
• Database 6.0: The FIPS 140-2 compliant “Federal Edition” variant of Aerospike EE restricts access to PKI or LDAP authentication modes.
• Aerospike Admin, asadm, added support for mixed security modes in tools package 7.0.0 (asadm 2.7.0) which was packaged with Aerospike Database 6.0.
• Database 5.7: Added PKI auth as an alternative authentication mode for users created in Aerospike. You can restrict an internal user to PKI authentication by generating a strong random password for the user and not communicating it to the user. Create a user normally with asadm, then generate an SSL cert for the user, signed by the server’s root CA. The server must be configured for Mutual TLS (mTLS).

When access control is enabled with Cross-Datacenter Replication (XDR), a cluster with Aerospike EE 4.1.0.1 to 4.3.0.6 cannot ship to an Aerospike EE Database 4.6 or later. The simplest workaround is to avoid using incompatible Aerospike EE versions (4.1.0.1 to 4.3.0.6). Refer to this support article for more information.