Redis ACL cheat sheet: users, key patterns, command categories and NOPERM errors

Goal: stop every application sharing one all-powerful Redis password, and fix permission errors quickly when a client starts failing.

Out of the box, every connection is the default user: on nopass ~* &* +@all. That means no password, all keys, all channels, all commands. Setting requirepass only gives that same user a password.

#See what you have

ACL WHOAMI                  # who am I connected as
ACL USERS                   # user names only
ACL LIST                    # every user with its rules (passwords shown as hashes)
ACL GETUSER app             # one user's flags, keys, channels and commands
ACL CAT                     # all command categories
ACL CAT dangerous           # commands in one category
ACL LOG 10                  # last 10 denied attempts
ACL LOG RESET               # clear the log
ACL GENPASS                 # generate a strong random password
ACL DRYRUN app GET app:1    # test a permission without running it (7.0+)

Connect as a named user without putting the password on the command line:

redis-cli -h redis01 --user app --askpass ping

#Users for common roles

New users start off, with no password, no commands and no keys. Add what they need. Rules apply left to right, so put removals such as -@dangerous last.

#Application with its own key prefix

ACL SETUSER app on >STRONG_PASSWORD ~app:* +@read +@write +@connection +@transaction -@dangerous

Add +@scripting or +@pubsub &app:* only if the application uses them.

#Monitoring agent with no key access

ACL SETUSER monitor on >STRONG_PASSWORD +ping +info +client|list +slowlog|get +latency|latest +memory|stats

If your exporter needs more, read ACL LOG and add only that.

#Replica

Run this on the primary:

ACL SETUSER replica-user on >STRONG_PASSWORD +psync +replconf +ping

Then set this in redis.conf on each replica:

masteruser replica-user
masterauth STRONG_PASSWORD

#Sentinel

Create this user on both the primary and the replicas:

ACL SETUSER sentinel-user on >STRONG_PASSWORD resetchannels &__sentinel__:hello +multi +slaveof +ping +exec +subscribe +config|rewrite +role +publish +info +client|setname +client|kill +script|kill

Then set this in sentinel.conf:

sentinel auth-user mymaster sentinel-user
sentinel auth-pass mymaster STRONG_PASSWORD

#Rule reference

#Three behaviours that catch people out

ACL SETUSER adds to an existing user. It doesn't replace the rules. To redefine a user, start with reset and include the password again:

ACL SETUSER app reset on >STRONG_PASSWORD ~app:* +@read +@connection -@dangerous

off doesn't disconnect anyone. Connections that have already authenticated keep working. To really cut a user off:

ACL SETUSER app off
CLIENT KILL USER app

Key patterns don't limit commands with no key argument. SCAN and RANDOMKEY can still expose names outside the user's prefix, and FLUSHALL wipes everything if it is allowed. -@dangerous removes FLUSHALL, FLUSHDB and KEYS, but not SCAN. On a shared instance, also block it for tenants that don't need it:

ACL SETUSER tenant1 -scan -randomkey

#Fix permission errors

Start with the log. It shows the user, the command or key that was denied, and the client address:

ACL LOG 5

reason is command, key, channel or auth, and object is the name that was refused. Error wording varies by version:

Test the fix with ACL DRYRUN app SET app:1 hello before the application team retries.

#Make the changes survive a restart

ACL SETUSER only changes memory. Save it using whichever method the instance is set up for:

ACL LOAD only succeeds if every user in the file is valid. Otherwise it returns an error and the old rules stay in place.

ACLs are per node. They don't replicate, so a failover to a replica without the user causes an immediate WRONGPASS. Run the same changes on every node, including replicas and all Redis Cluster nodes, and save on each. Cluster-aware clients also need topology commands such as +cluster|slots or +cluster|shards; check your client library's documentation.

#Rotate a password without downtime

A user can hold two passwords during the change:

ACL SETUSER app >NEW_PASSWORD
# deploy the new password to the application and restart it
ACL SETUSER app <OLD_PASSWORD

#Lock down the default user

First create an admin user:

ACL SETUSER admin on >STRONG_PASSWORD allkeys allchannels +@all

Log in as that user in a separate session, and check who still relies on default:

redis-cli --user admin --askpass CLIENT LIST | grep 'user=default'

When the only remaining connections are ones you expect to lose, switch default off from the admin session:

ACL SETUSER default off
CLIENT KILL USER default

Caution

Do this only after replicas and Sentinels have named users. Anything sending only masterauth or a password-only AUTH authenticates as default and fails, which can break replication and failover. If you lock yourself out, the fix is editing the ACL file or redis.conf and restarting Redis.

#Prevent it next time

• Give each application and agent its own user. ACL LOG and CLIENT LIST then show who did what.
• Alert on rising denials. INFO stats reports counters such as acl_access_denied_auth and acl_access_denied_cmd; names vary by version, so check your build's output.
• Compare ACL LIST across nodes on a schedule to catch drift before a failover finds it.
• On managed Redis, don't assume these commands work. Redis Cloud and Redis Software, for example, don't support ACL SETUSER.