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
You can enable RBAC in Aerospike EE with a rolling restart.
In a running cluster, execute the following steps node-by-node. If the node isn’t running, skip to step 3:
-
Verify that a
security
stanza is present in the configuration file(aerospike.conf
).a. In Database 5.7 and later, the presence of a
security
stanza enables security and access control. The server does not recognizeenable-security
and will not start if it is present.b. Prior to Database 5.7, set
enable-security
totrue
in thesecurity
stanza. -
(Optional) Set
enable-quotas
totrue
in thesecurity
stanza to enable rate quotas.Terminal window security {# enable-security true # versions < 5.7 onlyenable-quotas true# Other security-related configuration...} -
Verify that access control is enabled on the cluster.
-
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.
-
Change the admin user’s password with
manage acl set-password user admin password NEW-PASSWORD
. -
Grant the sys-admin role to the admin user with
manage acl grant user admin roles sys-admin
.
Secure SMD files
The /opt/aerospike/smd/security.smd
file 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.
-
Set permissions on the
/opt/aerospike/smd
directory.Terminal window chmod 700 /opt/aerospike/smd -
Set permissions on the
/opt/aerospike/smd/security.smd
file.Terminal window chmod 600 /opt/aerospike/smd/security.smd -
Optional: Use
chmod 600
to restrict permissions on other SMD files you want to protect in the/opt/aerospike
directory.Terminal window chmod 600 /opt/aerospike/smd/FILENAME -
List the contents of the
/opt/aerospike
directory to verify permissions:Terminal window 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 bindrwxr-xr-x 2 aerospike aerospike 4096 Nov 10 2020 datadrwxr-xr-x 2 aerospike aerospike 4096 Apr 24 13:17 docdrwxr-xr-x 4 aerospike aerospike 4096 Apr 24 13:17 libdrwx------ 1 aerospike aerospike 4096 Jun 22 12:26 smd <<<<drwxr-xr-x 3 aerospike aerospike 4096 Apr 24 13:17 usr -
To verify permissions in the
/opt/aerospike/smd
directory, list its contents:Terminal window ls -la /opt/aerospike/smdExpected 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. See 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 that you first review the potential performance impact and storage needs in a test environment.
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 was 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
You can enable the audit trail 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
Restart rsyslogd
to activate any changes.
Parsing audit trail log messages
Log messages are plain text descriptions of attempted security actions, whether or not the action succeeded, and any user that 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
= readrw
= read-writerwf
= read-write-udft
= truncatew
= writed
= 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 thetest
namespace and read-write privileges for thens2
namespace.u,rwf{test|demoset}
indicates user-admin privileges as well as read-write-udf privileges fordemoset
in thetest
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.
Stored key data appears as follows:
[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]
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=user2Sep 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=user2Sep 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 changed with new versions of Aerospike server and clients.
- Database 6.3: Removed the
syslog
subcontext of thesecurity
config context. Audit trail messages can be sent to any log sink type (file
,console
orsyslog
) that is defined in thelogging
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).
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 - 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]
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]]>
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]]>
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 [...]]
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
manage acl allowlist role demo-users clear
Delete a role
The asadm
command to delete a role is:
manage acl delete user USERNAME
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 thedefault-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]
Create a user
The asadm
command to create a user is:
manage acl create user USERNAME [password PASSWORD] [roles ROLE1 ROLE2 ...]
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 [...]]
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 [...]]
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
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.
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
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 (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 | - | - | - |
Related information
Aerospike supports LDAP, PKI, and password-based authentication modes that are described in detail in Access Control with LDAP and PKI.