Configure access control

This page describes how to enable authentication and assign roles and permissions in 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).

Requirements

• Aerospike Database Enterprise Edition (EE), or Aerospike Database Enterprise Edition for United States Federal (FE).
• Client version that supports the features necessary to do a rolling restart. See the Minimum client version matrix for details.

Enable access control

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

1. Quiesce the node.

2. Stop the Aerospike server.

3. Verify that a security section is present in aerospike.conf. The presence of a security section enables security and access control. The server does not recognize enable-security and will not start if it is present.

   Note

   Prior to Database 5.7.0, set enable-security to true in the security section.

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

       security {
           # enable-security true # versions 5.6.x and earlier only
           enable-quotas true
   
           # Other security-related configuration...
       }

5. Start the Aerospike server.

6. Verify that access control is enabled on the cluster. Run the asadm feature command to list the features running on the cluster.

7. Use asadm -U admin to connect to the server as the admin user.

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

8. Change the admin user’s password with manage acl set-password user admin password NEW-PASSWORD.

9. Grant the sys-admin role to the admin user with manage acl grant user admin roles sys-admin.

10. Execute a rolling restart.

    Note

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

PKI authentication

1. Verify that the server is using Mutual TLS (mTLS). If it is not, see TLS Configuration for configuration instructions.

2. Create a user and grant them privileges and roles.

3. Generate an SSL certificate for the user, with the username as the Common Name CN.

4. Sign the certificate using the server root certificate authority (CA). For instructions, see Generate TLS certificate requests.

5. (Optional) You can use pki-user-append-ou to include the certificate’s OU (Organizational Unit Name) value in the username for PKI authentication.

   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

Note

• Prior to Database 8.1.0, you could not use pki-user-append-ou to include the certificate’s OU (Organizational Unit Name) value in the username for PKI authentication.
• 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.

Secure system metadata (SMD) files

The system metadata (SMD) file, at /opt/aerospike/smd/security.smd, stores sensitive information about users and roles. The default permission on all SMD files grants read access to everyone.

When a new node is added to an existing cluster, it is a best practice to initialize it by copying SMD files from an active cluster node. This best practice is not checked at startup.

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

4. List the contents of the /opt/aerospike directory to verify permissions:

   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

Privileges

Privileges are a fundamental component 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 (sindex-admin) - Register and remove UDFs (udf-admin) - Use the scan-query job monitoring system - Abort scans and queries - Change user password - Truncate or undo a truncation of namespaces or sets (truncate)	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

The privilege checking interval

The server checks for user privileges when a connection is established and also periodically during the lifetime of the connection. The period of the check is defined by the server parameter privilege-refresh-period, which defaults to 300 seconds. The granting of new privileges and revoking of existing ones take effect after each periodic check. privilege-refresh-period is a dynamic parameter and can be changed during runtime.

Pre-defined 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 manage roles and users with the Admin tool, asadm, see Managing 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

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 [...]]

Example

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

Managing users

When RBAC is first enabled in an Aerospike EE cluster, Aerospike creates 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.0.
• 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

Valid passwords can contain alphanumeric characters and the symbols .*-:/_{}@. White space is not supported.

These restrictions do not apply when setting a user password with a hidden prompt in asadm.

Permanently disable password auth

In asadm, setting a user’s password to nopassword instructs the server to permanently disable password authentication for this user. When this happens, the user can never log in with a password or change their password, and users with a user-admin privilege cannot set a password for them. This feature requires Database 8.1.x.

manage acl set-password user USERNAME password nopassword

Create a user

The asadm command to create a user is:

manage acl create user USERNAME [password PASSWORD] [roles ROLE1 ROLE2 ...]

Example

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 [...]]

Example

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 [...]]

Example

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

Security features by Database version

Support for various features and security modes has changed with new versions of Aerospike server and clients.

• Database 8.1.0.: Added an ability to disable password authentication for an internal user. This allows a user administrator to restrict specific users to PKI authentication.
• Database 6.3.0: Removed the syslog subsection of the security section. Audit trail messages can be sent to any log sink type (file, console or syslog) that is defined in the logging subsection.
• Database 6.0.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 Database 6.0.0.
• Database 5.7.0: 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).

Caution

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.0 or later. The simplest workaround is to avoid using incompatible Aerospike EE versions (4.1.0.1 to 4.3.0.6). See this support article for more information.

Minimum client version matrix

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
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	-	-	-

Related information

• See Access control with LDAP and PKI to learn about Aerospike’s LDAP, PKI, and password-based authentication modes.

• See Audit trail to learn about configuring Aerospike EE to log security events to an audit log.