Skip to content

Fix ACL documentation discrepancies from source code audit #305

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.

Sign up for GitHub

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
sscarduzio wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

Fix ACL documentation discrepancies from source code audit #305

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cd1dff
Fix ACL documentation discrepancies found via source code audit
sscarduzio Mar 18, 2026
8f1c4ee
Clarify group rule aliases scope per review feedback
sscarduzio Mar 18, 2026
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
44 changes: 42 additions & 2 deletions elasticsearch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -828,6 +828,21 @@ The groups rules use the user definitions from [the `users` section](#users-and-
- after this step, we have an authorized user with information about the authorized groups to which the user belongs
- then we check whether the authorized user groups are permitted in context of the rule

{% hint style="info" %}
**Groups rule aliases**: For backwards compatibility, the following YAML key aliases are recognized and treated identically to their canonical names:
Copy link
Copy Markdown
Collaborator

@coutoPL coutoPL Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We intentionally didn't mention it. We do care about backward compatibility, but we want our users to migrate to the new format. And most importantly, we don't want our new users (or existing users who are starting to use the feature) to not use the older format.

IMO, we should remove this section.


| Canonical Rule | Aliases |
|---------------|---------|
| `groups_any_of` | `groups`, `any_of`, `groups_or`, `roles` |
| `groups_all_of` | `all_of`, `groups_and`, `roles_and` |
| `groups_not_any_of` | `not_any_of` |
| `groups_not_all_of` | `not_all_of` |

Similarly, `headers_and` can be written as `headers`.

These aliases apply only to **ACL rule keys inside access control blocks** — they are unrelated to the `groups` field in the [`users` section](#users-and-groups).
{% endhint %}
Comment thread
sscarduzio marked this conversation as resolved.
Comment thread
sscarduzio marked this conversation as resolved.

##### `groups_any_of`

The ACL block will match when the user belongs to any of the specified groups (boolean OR logic).
Expand Down Expand Up @@ -1121,6 +1136,8 @@ For more information on the ROR's authorization rules, see [Authorization rules

#### `groups_provider_authorization`

Also available as the alias `external_authorization`.
Copy link
Copy Markdown
Collaborator

@coutoPL coutoPL Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as above


Used to delegate groups resolution for a user to a JSON microservice. See below, the dedicated [Groups Provider Authorization section](elasticsearch.md#custom-groups-providers)

[Impersonation](details/impersonation.md) support by this rule requires to add [an extra configuration](details/impersonation.md#defining-mocks-of-the-external-services-optional).
Expand Down Expand Up @@ -1804,9 +1821,9 @@ Match if **at least one** the specified HTTP headers `key:value` pairs is matche

Match if **at least one** specified regular expression matches requested URI.

#### `maxBodyLength`
#### `max_body_length`

`maxBodyLength: 0`
`max_body_length: 0`

Match requests having a request body length less or equal to an integer. Use `0` to match only requests without body.

Expand All @@ -1818,6 +1835,12 @@ Match requests having a request body length less or equal to an integer. Use `0`

A list of api keys expected in the header `X-Api-Key`

#### `response_headers`
Copy link
Copy Markdown
Collaborator

@coutoPL coutoPL Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no such rule in the ROR ES code 🙃


`response_headers: ["X-Custom-Header:value", "X-Another:123"]`

Add custom headers to the Elasticsearch HTTP response when this block matches. Useful for passing metadata (e.g. group names, routing hints) back to clients or proxies.

#### `session_max_idle`

`session_max_idle: 1h`
Expand Down Expand Up @@ -2104,6 +2127,23 @@ ldaps:

And ReadonlyREST ES will load "S3cr3tP4ss" as `bind_password`.

### Incompatible rule combinations

Certain rules cannot be used together within a single ACL block. ReadonlyREST will report a validation error if any of these combinations are detected:

| Rule A | Rule B | Reason |
|--------|--------|--------|
| `kibana_access` | `actions` | Kibana access internally manages action filtering |
Copy link
Copy Markdown
Collaborator

@coutoPL coutoPL Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The kibana_access rule is deprecated. We should not focus so much on it. The access level is now part of the kibana rule

| `kibana_access` | `filter` | Kibana access conflicts with Document Level Security |
| `kibana_access` | `fields` | Kibana access conflicts with Field Level Security |
| `kibana_access` | `response_fields` | Kibana access conflicts with response field filtering |

{% hint style="info" %}
The composite `kibana` rule does **not** have these conflicts — it replaces the legacy separate rules (`kibana_access`, `kibana_index`, `kibana_hide_apps`, `kibana_template_index`) and handles these interactions internally.
Copy link
Copy Markdown
Collaborator

@coutoPL coutoPL Mar 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not true.

The table should look like this:

Rule A Rule B Additional condition Reason
kibana actions when kibana.access != unrestricted Kibana access internally manages action filtering
kibana filter Kibana access conflicts with Document Level Security
kibana fields Kibana access conflicts with Field Level Security
kibana response_fields Kibana access conflicts with response field filtering

{% endhint %}

Additionally, a block with an **authorization-only** rule (e.g. `ldap_authorization`, `jwt_authorization`) must also contain an **authentication** rule in the same block. A block cannot have more than one authentication rule.

### Dynamic variables

One of the neatest features in ReadonlyREST is that you can use dynamic variables inside most values of the following rules: `data_streams`, `indices`, `users`, `fields`, `filter`, `repositories`, `hosts`, `hosts_local`, `snapshots`, `response_fields`, `uri_re`, `x_forwarded_for`, `hosts_local`, `hosts`, `kibana.index`, `kibana.template_index`, `kibana.metadata`, [groups rules](#groups-rules). The variables are related to different contexts:
Expand Down