ACL & security

Active contributors: antirez, Itamar Haber, Madelyn Olson, Oran Agra, Yossi Gottlieb.

Purpose

The Access Control List (ACL) subsystem replaced single-password authentication in Redis 6. It introduces named users with per-command, per-keyspace, per-channel permissions. The TLS subsystem provides encrypted transport. Together they form the security layer.

Source layout

File	Role
src/acl.c	The whole ACL implementation: user store, command/key/channel rules, Pub/Sub gating, password hashing, ACL log. ~130 KB.
src/acl-v2.tcl (test)	Tcl test for ACL v2 behaviour.
src/tls.c	OpenSSL-backed connection type. ~43 KB.
src/sha256.c	Used for password hashing.
src/sha1.c	Used for legacy script SHA1 + some auth paths.
src/connection.c, src/connection.h	Connection abstraction; TLS plugs in here.

ACL model

Every connection authenticates as a user. By default, that's the default user, which can be configured to require a password. The user object holds:

• A list of allowed/denied commands and command categories.
• A list of allowed/denied key patterns (glob).
• A list of allowed/denied Pub/Sub channel patterns (glob).
• Password hashes (SHA256).
• The nopass flag (auth-less).
• The on/off flag (account enabled or disabled).

Permissions are evaluated additively from a set of selectors attached to the user. A user can have multiple selectors that each grant a subset of permissions, evaluated in order.

The wire syntax for ACL SETUSER:

ACL SETUSER alice on >password ~objects:* &chat:* +@read +@write -DEBUG

That makes alice enabled, sets a password, allows reads and writes on keys matching objects:*, allows Pub/Sub on channels matching chat:*, allows the read and write categories, and explicitly denies DEBUG.

ACL CAT lists permission categories; ACL GETUSER alice returns the rule list; ACL WHOAMI returns the current user.

Categories

ACL categories are command groups: @read, @write, @admin, @dangerous, @keyspace, @string, @list, @set, @sortedset, @hash, @stream, @scripting, @pubsub, @blocking, @transaction, @connection, @geo, @bitmap, @fast, @slow. Each command has a static set of categories declared in its JSON spec under the acl_categories field.

Modules can register their own categories via RedisModule_AddACLCategory.

ACL log

Recent failed authorisations are recorded in a ring buffer. ACL LOG returns them with timestamps, user, command, reason, and originating client. Useful for debugging auth issues without enabling MONITOR.

ACL persistence

Two storage modes:

• aclfile <path> — named user definitions live in a separate file that the server writes via ACL SAVE and reads at startup via ACL LOAD. Recommended.
• Inline user ... directives in redis.conf — stored alongside the regular config. Limits operations: ACL SAVE/LOAD are disabled in this mode.

The user database is in-memory (server.acl_users); the file is just a snapshot.

Authentication

AUTH <password> is a backward-compatible shortcut for AUTH default <password>. The full form is AUTH <user> <password>. After auth, the connection's client.user pointer is updated; subsequent ACL checks use that.

Auth failure increments a per-IP counter and is logged in the ACL log. Brute-force protection is the operator's responsibility (rate-limit upstream).

Module-defined auth

RedisModule_RegisterAuthCallback lets a module take over auth for a specific user. Used for SSO, LDAP, or custom token schemes. The callback returns a verdict (OK, ERR, BLOCK); BLOCK lets the module finish auth asynchronously.

Client-cert auth (TLS)

When tls-auth-clients yes is set, the server validates the client certificate against the configured CA and uses the certificate's CN as the implied ACL user (or applies a custom mapping). Combined with tls-protocols, this gives mTLS-only deployments.

TLS

src/tls.c implements a connection vtable on top of OpenSSL. Features:

• TLSv1.2 and TLSv1.3.
• Optional client cert verification (tls-auth-clients yes/no/optional).
• OCSP stapling.
• Session resumption (with caveats — disabled by default for replication).
• Configurable cipher list (tls-ciphers, tls-ciphersuites).
• TLS for the cluster bus (tls-cluster yes).
• TLS for replication (tls-replication yes).

TLS can be linked into redis-server (make BUILD_TLS=yes) or built as a loadable module (make BUILD_TLS=module, producing redis-tls.so). The module variant uses the same src/tls.c code; only the linkage differs.

Encrypted at rest

Redis does not encrypt RDB/AOF files. Operators are expected to encrypt the underlying disk if they need data-at-rest encryption.

Network exposure controls

Directive	Effect
bind <addr> [<addr> ...]	The set of interfaces to listen on. Defaults to 127.0.0.1 -::1.
protected-mode yes	If unset password and bound to all interfaces, refuse external connections with a clear error message. Default yes.
enable-protected-configs no	Refuse CONFIG SET of dangerous keys (e.g. dir, dbfilename) at runtime.
enable-debug-command no	Hide DEBUG.
enable-module-command no	Hide MODULE LOAD.
requirepass <pass>	Legacy: sets the password for the default user.

Where to start modifying

• Add an ACL flag — extend the userFlag enum in src/acl.c and update the parser in aclParseUserFlag.
• Add a new category — append to ACLCommandCategories[] in src/acl.c and add acl_categories references in the relevant JSON specs.
• Modify TLS handshake — src/tls.c's connTLSAccept and connTLSConnect are the entry points.
• Pluggable auth — RedisModule_RegisterAuthCallback is the right hook (see Modules).

Related pages

• Networking — connection abstraction.
• Modules — auth callbacks and module-defined ACL categories.