Skip to content

DEV: document Redis 8 breaking changes to ACL handling #1669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions content/operate/oss_and_stack/management/security/acl.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,19 +289,19 @@ The following is a list of command categories and their meanings:
* **bitmap** - Data type: all bitmap related commands.
* **blocking** - Potentially blocking the connection until released by another
command.
* **bloom** - Data type: all Bloom filter related commands.
* **cms** - Data type: count-min sketch related commands.
* **bloom** - Data type: all Bloom filter related commands. <sup>[1](#cmd-note-1)</sup>
* **cms** - Data type: count-min sketch related commands. <sup>[1](#cmd-note-1)</sup>
* **connection** - Commands affecting the connection or other connections.
This includes [`AUTH`](/commands/auth), [`SELECT`](/commands/select), [`COMMAND`](/commands/command), [`CLIENT`](/commands/client), [`ECHO`](/commands/echo), [`PING`](/commands/ping), etc.
* **cuckoo** - Data type: all Cuckoo filter related commands.
* **cuckoo** - Data type: all Cuckoo filter related commands. <sup>[1](#cmd-note-1)</sup>
* **dangerous** - Potentially dangerous commands (each should be considered with care for
various reasons). This includes [`FLUSHALL`](/commands/flushall), [`MIGRATE`](/commands/migrate), [`RESTORE`](/commands/restore), [`SORT`](/commands/sort), [`KEYS`](/commands/keys),
[`CLIENT`](/commands/client), [`DEBUG`](/commands/debug), [`INFO`](/commands/info), [`CONFIG`](/commands/config), [`SAVE`](/commands/save), [`REPLICAOF`](/commands/replicaof), etc.
* **fast** - Fast O(1) commands. May loop on the number of arguments, but not the number of elements in the key.
* **geo** - Data type: all geospatial index related commands.
* **hash** - Data type: all hash related commands.
* **hyperloglog** - Data type: all hyperloglog related commands.
* **json** - Data type: all JSON related commands.
* **json** - Data type: all JSON related commands. <sup>[1](#cmd-note-1)</sup>
* **keyspace** - Writing or reading from keys, databases, or their metadata
in a type agnostic way. Includes [`DEL`](/commands/del), [`RESTORE`](/commands/restore), [`DUMP`](/commands/dump), [`RENAME`](/commands/rename), [`EXISTS`](/commands/exists), [`DBSIZE`](/commands/dbsize),
[`KEYS`](/commands/keys), [`SCAN`](/commands/scan), [`EXPIRE`](/commands/expire), [`TTL`](/commands/ttl), [`FLUSHALL`](/commands/flushall), etc. Commands that may modify the keyspace,
Expand All @@ -311,18 +311,20 @@ The following is a list of command categories and their meanings:
* **pubsub** - all pubsub related commands.
* **read** - Reading from keys (values or metadata). Note that commands that don't interact with keys, will not have either `read` or `write`.
* **scripting** - Scripting related.
* **search** - All search related commands. Only ACL users with access to a superset of the key prefixes defined during index creation can create, modify, or read the index. For example, a user with the key ACL pattern `h:*` can create an index with keys prefixed by `h:*` or `h:p*`, but not keys prefixed by `h*`, `k:*`, or `k*`, because these prefixes may involve keys to which the user does not have access.
* **search** - All search related commands. Only ACL users with access to a superset of the key prefixes defined during index creation can create, modify, or read the index. For example, a user with the key ACL pattern `h:*` can create an index with keys prefixed by `h:*` or `h:p*`, but not keys prefixed by `h*`, `k:*`, or `k*`, because these prefixes may involve keys to which the user does not have access. <sup>[1](#cmd-note-1)</sup>
* **set** - Data type: all set related commands.
* **sortedset** - Data type: all sorted set related commands.
* **slow** - All commands that are not `fast`.
* **stream** - Data type: all stream related commands.
* **string** - Data type: all string related commands.
* **tdigest** - Data type: all t-digest related commands.
* **timeseries** - Data type: all time series related commands.
* **topk** - Data type: all top-k related commands.
* **tdigest** - Data type: all t-digest related commands. <sup>[1](#cmd-note-1)</sup>
* **timeseries** - Data type: all time series related commands. <sup>[1](#cmd-note-1)</sup>
* **topk** - Data type: all top-k related commands. <sup>[1](#cmd-note-1)</sup>
* **transaction** - [`WATCH`](/commands/watch) / [`MULTI`](/commands/multi) / [`EXEC`](/commands/exec) related commands.
* **write** - Writing to keys (values or metadata). Note that commands that don't interact with keys, will not have either `read` or `write`.

1. <a name="cmd-note-1"></a> See the [Redis 8 release notes]({{< relref "/operate/oss_and_stack/stack-with-enterprise/release-notes/redisce/redisos-8.0-release-notes/#potentially-breaking-changes-to-acls" >}}) for more information about these command categories, which may introduce breaking changes to your Redis deployments.

NOTE: Redis can also show you a list of all categories and the exact commands each category includes using the Redis [`ACL CAT`](/commands/acl-cat) command.
It can be used in two forms:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,10 +71,8 @@ Stand alone RediSearch, RedisJSON, RedisTimeSeries, and RedisBloom modules are n

- See the [build instructions]({{< relref "/operate/oss_and_stack/install/build-stack" >}}) for information about building from source code.
- New configuration file: `redis-full.conf`, loads Redis with all components,
and contains new configuration parameters for Redis Query Engine and the new data structures .
- New ACL categories: `@search`, `@json`, `@timeseries`, `@bloom`, `@cuckoo`, `@cms`, `@topk`, and `@tdigest`.
- Commands are also included in the existing ACL categories such as `@read` and `@write`.

and contains new configuration parameters for Redis Query Engine and the new data structures.
- New ACL categories: `@search`, `@json`, `@timeseries`, `@bloom`, `@cuckoo`, `@cms`, `@topk`, and `@tdigest` commands are also included in the existing ACL categories such as `@read` and `@write`. See [below]({{< relref "/operate/oss_and_stack/stack-with-enterprise/release-notes/redisce/redisos-8.0-release-notes/#potentially-breaking-changes-to-acls" >}}) for information about potentially breaking changes.
- More than 30 performance and resource utilization improvements.
- A new I/O threading implementation, which enables throughput increase on multi-core environments
(set with the `io-threads` configuration parameter).
Expand Down Expand Up @@ -113,3 +111,74 @@ For more details, see the release notes for the [8.0-M01](https://github.com/red
- [#13966](https://github.com/redis/redis/pull/13966), [#13932](https://github.com/redis/redis/pull/13932) `CLUSTER SLOTS` - TLS port update not reflected.
- [#13958](https://github.com/redis/redis/pull/13958) `XTRIM`, `XADD` - incorrect lag due to trimming stream.
- [#13931](https://github.com/redis/redis/pull/13931) `HGETEX` - wrong order of keyspace notifications.

### Potentially breaking changes to ACLs

{{< note >}}
The following content is relevant to all Redis distributions (RS, RC, and ROS).
{{< /note >}}

Redis 8 includes Redis Query Engine, as well as JSON, time series, Bloom filter, cuckoo filter, top-k, count-min sketch, and t-digest data types.
The integration of these features into Redis also comes with improvements to Redis [ACL]({{< relref "/operate/oss_and_stack/management/security/acl" >}}) rules.

{{< warning >}}
These ACL changes may introduce breaking changes for some users, which must be analyzed carefully.
{{< /warning >}}

### Extension to the existing ACL categories

Before Redis 8, the existing ACL categories @read, @write, @dangerous, @admin, @slow, and @fast did not include commands for the Redis Query Engine and the JSON, time series, and probabilistic data structures.

Starting with Redis 8, Redis includes all Query Engine, JSON, time series, Bloom filter, cuckoo filter, top-k, count-min sketch, and t-digest commands in these existing ACL categories.

As a result:

- Existing ACL rules such as `+@read +@write` will allow access to more commands than in previous versions of Redis. Here are some examples:
- A user with `+@read` access will be able to execute `FT.SEARCH`.
- A user with `+@write` access will be able to execute `JSON.SET`.

- ACL rules such as `+@all -@write` will allow access to fewer commands than previous versions of Redis. For example:
- A user with `+@all -@write` will not be able to execute `JSON.SET`.

Note that the `@all` category did not change, as it always included all the commands.

Additionally, ACL rules such as `+@read +JSON.GET` can now be simplified as `+@read` because `JSON.GET` is included in the `@read` category.

### Who is affected by this change?

Users who currently use the Redis Query Engine and/or the JSON, time series, or probabilistic data structures, and use custom ACL rules.

You should reanalyze your ACL rules to make sure they are aligned with your security and access control requirements.

### Redis 8 introduces the following data structure and processing engine ACL categories.

| New ACL commands category names | Included commands |
| :---- | :---- |
| `search` | All Redis Query Engine commands |
| `json` | All JSON commands |
| `timeseries` | All time series commands |
| `bloom` | All Bloom filter commands |
| `cuckoo` | All cuckoo filter commands |
| `topk` | All top-k commands |
| `cms` | All count-min sketch commands |
| `tdigest` | All t-digest commands |

You can use these new categories in your ACL rules.

### Time series notes

The following time series commands retrieve data from all keys that match a given filter expression: `TS.MGET`, `TS.MRANGE`, and `TS.MREVRANGE`.

There can be a case where a user may have to only some of the matching keys. In such cases, the command’s result is an error message: “*current user doesn't have read permission to one or more keys that match the specified filter*”.

On the other hand, `TS.QUERYINDEX` does not require `@read` access to the keys that match the specified filter, as it accesses only time series metadata (name and labels) and not content (measurements).

### Redis Query Engine notes

The following Redis Query Engine commands may retrieve data from all keys that match the prefixes defined in the index (that is, all indexed documents, per-index):

- `FT.SEARCH`
- `FT.AGGREGATE` (may be followed by `FT.CURSOR`)
- `FT.PROFILE`

Only ACL users with access to a superset of the key prefixes defined during index creation can create, modify, or read the index. For example, a user with the key ACL pattern `h:*` can create an index with keys prefixed by `h:*` or `h:p*`, but not keys prefixed by `h*`, `k:*`, or `k*`, because these prefixes may involve keys to which the user does not have access.