From a14315e701f2404cdcf9b979e12ec9be01538b1d Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Sat, 9 Aug 2025 12:06:57 -0600 Subject: [PATCH 01/10] Expand filebased user for recovering security --- .../cluster-or-deployment-auth/file-based.md | 293 ++++++++++-------- 1 file changed, 168 insertions(+), 125 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index 6aace3d93a..20c8fe7fdd 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -14,107 +14,156 @@ products: # File-based user authentication [file-realm] -You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users are defined in local files on each node in the cluster. +You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users and roles are defined in local files on each node. -The `file` realm is useful as a fallback or recovery realm. For example in cases where the cluster is unresponsive or the security index is unavailable, or when you forget the password for your administrative users. In this type of scenario, the `file` realm is a convenient workaround: you can define a new `admin` user in the `file` realm and use it to log in and reset the credentials of all other users. +The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. -You can configure only one file realm on {{es}} nodes. +Therefore, the `file` realm is commonly used as a fallback or recovery realm. It is helpful in cases where the -Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. +* Cluster is unresponsive +* {{stack}} {{security-features}} is unavailable to the current node +* {{stack}} {{security-features}} is [lost and needs restored](/troubleshoot/elasticsearch/red-yellow-cluster-status#fix-cluster-status-restore) +* Administrative users' passwords are lost and [need reset](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password) -::::{important} -* In self-managed deployments, as the administrator of the cluster, it is your responsibility to ensure the same users are defined on every node in the cluster. The {{stack}} {{security-features}} do not deliver any mechanism to guarantee this. -* You can't add or manage users in the `file` realm using the [user APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security), or using the {{kib}} **Management > Security > Users** page. -:::: +The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administators of self-managed deployments are responsible to ensure that either + +* The same users and roles are defined across every node in the cluster. + * Frequently administrators choose to apply the change on one of the {{es}} nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). +* The related API requests are directed to the local node rather than any cluster-level load balancer or proxy URL. -## Configure a file realm [file-realm-configuration] +Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. + +## Configure realm [file-realm-configuration] -You don’t need to explicitly configure a `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm per node. +You don’t need to explicitly configure the `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm per node. To override the default `file` realm configuration 1. (Optional) Add a realm configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md) under the `xpack.security.authc.realms.file` namespace. At a minimum, you must set the realm’s `order` attribute. For example, the following snippet shows a `file` realm configuration that sets the `order` to zero so the realm is checked first: ```yaml - xpack: - security: - authc: - realms: - file: - file1: - order: 0 + xpack.security.authc.realms.file.file1.order: 0 ``` -2. If you're using a self-managed {{es}} cluster, optionally change how often the `users` and `users_roles` files are checked. +2. (Optional) For self-managed deployments, you may change how often `file` realm backing files are checked. - By default, {{es}} checks these files for changes every 5 seconds. You can change this default behavior by changing the `resource.reload.interval.high` setting in the [`elasticsearch.yml`](/deploy-manage/stack-settings.md) file. + By default, {{es}} checks these files for changes every 5 seconds. You can override this default behavior by changing the `resource.reload.interval.high` setting's value in the [`elasticsearch.yml`](/deploy-manage/stack-settings.md) file. :::{{warning}} - Because `resource.reload.interval.high` is a common setting in {{es}}, changing its value may effect other schedules in the system. + Because `resource.reload.interval.high` is a foundational setting for {{es}}, changing its value may effect other schedules in the system. ::: -3. Restart {{es}}. +3. In self-managed deployments, if either prior setting is modified, you will need to [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures#restart-cluster-rolling) those {{es}} nodes for your changes to take effect. In {{eck}}, changes are automatically propagated. - In {{eck}}, this change is propagated automatically. +## Configure files [file-realm-files] +The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch#config-files-location) and contain -## Add users +* `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles) +* `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles) +* `users` for [user password-based authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication) +* `user_roles` for [user role-based authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles) -**In a self-managed {{es}} cluster**, all the data about the users for the `file` realm is stored in two files on each node in the cluster: [`users` and `users_roles`](#using-users-and-users_roles-files). Both files are located in `ES_PATH_CONF` and are read on startup. +### Define roles [file-realm-roles] -**In an {{eck}} deployment**, you can pass file realm user information in two ways: +Before granting a `file` realm user its roles, you will want to ensure those desired roles exists. Roles can be defined from -1. Using [`users` and `user_roles`](#using-users-and-users_roles-files) files, which are passed using file realm content secrets -2. [Using Kubernetes basic authentication secrets](#k8s-basic) +* [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles) +* [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles) defined under the {{stack}} {{security-features}} +* `roles.yml`per [File-based Role Management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles#roles-management-file) -You can reference several secrets in the {{es}} specification. ECK aggregates their content into a single secret, mounted in every {{es}} Pod. +{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users). While recovering {{stack}} {{security-features}}, you may need to temporarily define a role with `allow_restricted_indices` access enabled. For example, expanding the `superuser` role to include `allow_restricted_indices: true` would appear like like new role `superduperuser` definition -::::{important} -In a self-managed cluster, the `users` and `users_roles` files are managed locally by the node and are **not** managed globally by the cluster. This means that with a typical multi-node cluster, the exact same changes need to be applied on each and every node in the cluster. +```yaml +superduperuser: + cluster: [ 'all' ] + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true +``` -A safer approach would be to apply the change on one of the nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). -:::: +:::{{warning}} +Restricted indices are a special category of indices that are used to store cluster configuration data and should not normally be directly accessed. **Toggling this flag is normally very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If `allow_restricted_indices` needs temporarily enabled for a user in order to recover the {{stack}} {{security-features}}, {{es}} recommends ensuring to remove this role with sensitive access from the user upon task completion. +::: -### Using `users` and `users_roles` files +### Define role mappings [file-realm-role-mappings] -`users` and `users_roles` files contain all of the information about users in the file realm. +For clusters with high authentication volume or with extremely large [role mappings](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles), you may potentially find performance improvement by defining custom `role_mapping.yml` locally on each node in the cluster. For more information, see [using role mapping files](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles#mapping-roles-file). -#### `users` +### Add users [file-realm-users] -The `users` file stores all the users and their passwords. Each line in the file represents a single user entry consisting of the username and hashed and salted password. +The `file` realm can [define users](#file-realm-user-files) from files -``` -rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W -alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS -jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= -``` +* `users` for password-based authentication +* `users_roles` for role-based authorization -:::{tip} -To limit exposure to credential theft and mitigate credential compromise, the file realm stores passwords and caches user credentials according to security best practices. By default, a hashed version of user credentials is stored in memory, using a salted sha-256 hash algorithm and a hashed version of passwords is stored on disk salted and hashed with the bcrypt hash algorithm. To use different hash algorithms, see [User cache and password hash algorithms](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#hashing-settings). -::: +For {{eck}} deployments, these can also be passed through [{{k8s}} basic authentication secrets](#file-realm-user-k8s). -#### `users_roles` +#### Defining user files [file-realm-user-files] -The `users_roles` file stores the roles associated with the users. For example: +For most administrators, {{es}} recommends using the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command) which compiles the `users` and `users_roles` files on your behalf. + +Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced administrative user in order to recover the {{stack}} {{security-features}}, you would run + +::::{tab-set} + +:::{tab-item} Self-managed ``` -admin:rdeniro -power_user:alpacino,jacknich -user:jacknich +bin/elasticsearch-users useradd admin -p changeme -r superduperuser ``` +::: -Each row maps a role to a comma-separated list of all the users that are associated with that role. +:::{tab-item} {{eck}} +The following is an example of invoking the `elasticsearch-users` tool in a Docker container: -#### Editing `users` and `users_roles` files +```sh +# create a folder with the 2 files +mkdir filerealm +touch filerealm/users filerealm/users_roles -You can edit files and secrets that contain `users` and `users_roles` manually, or you can edit them using a tool. +# create user 'admin' with role 'superduperuser' +docker run \ + -v $(pwd)/filerealm:/usr/share/elasticsearch/config \ + docker.elastic.co/elasticsearch/elasticsearch:9.1.0 \ + bin/elasticsearch-users useradd admin -p changeme -r superduperuser + +# create a Kubernetes secret with the file realm content +kubectl create secret generic my-file-realm-secret --from-file filerealm +``` +::: + +:::: -**Manually** +For advanced users, you may choose to edit the `users` and `users_roles` files directly. ::::{tab-set} :::{tab-item} Self-managed -In a self-managed cluster, you can edit the contents of `ES_PATH_CONF/users` and `ES_PATH_CONF/users_roles` directly. +In a self-managed cluster, you can edit the contents of `$ES_PATH_CONF/users` and `$ES_PATH_CONF/users_roles` directly. + +* `users` + + The `users` file stores all the users and their passwords. Each line in the file represents a single user entry consisting of the username and hashed and salted password. For example: + + ``` + rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W + alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS + jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= + ``` + + To limit exposure to credential theft and mitigate credential compromise, the file realm stores passwords and caches user credentials according to security best practices. By default, a hashed version of user credentials is stored in memory, using a salted sha-256 hash algorithm and a hashed version of passwords is stored on disk salted and hashed with the bcrypt hash algorithm. To use different hash algorithms, see [User cache and password hash algorithms](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#hashing-settings). + +* `users_roles` + + The `users_roles` file stores the roles associated with the users. Each row maps a role to a comma-separated list of all the users that are associated with that role. For example: + + ``` + admin:rdeniro + superduperuser:alpacino,jacknich + user:jacknich + ``` ::: :::{tab-item} {{eck}} @@ -140,7 +189,7 @@ A file realm secret is composed of two entries: a `users` entry and a `users_rol If you specify multiple users with the same name in more than one secret, the last one takes precedence. If you specify multiple roles with the same name in more than one secret, a single entry per role is derived from the concatenation of its corresponding users from all secrets. -The following secret specifies three users and their respective roles: +The following secret specifies three users and their respective built-in and custom roles: ```yaml kind: Secret @@ -148,90 +197,84 @@ apiVersion: v1 metadata: name: my-filerealm-secret stringData: + roles.yml: |- + superduperuser: + cluster: + - all + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true users: |- rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= users_roles: |- admin:rdeniro - power_user:alpacino,jacknich + superduperuser:alpacino,jacknich user:jacknich ``` ::: :::: -**Using a tool** - -To avoid editing these files manually, you can use the [elasticsearch-users](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md) tool: - -::::{tab-set} - -:::{tab-item} Self-managed - -``` -bin/elasticsearch-users useradd myuser -p mypassword -r monitoring_user -``` -::: - -:::{tab-item} {{eck}} -The following is an example of invoking the `elasticsearch-users` tool in a Docker container: - -```sh -# create a folder with the 2 files -mkdir filerealm -touch filerealm/users filerealm/users_roles - -# create user 'myuser' with role 'monitoring_user' -docker run \ - -v $(pwd)/filerealm:/usr/share/elasticsearch/config \ - docker.elastic.co/elasticsearch/elasticsearch:8.16.1 \ - bin/elasticsearch-users useradd myuser -p mypassword -r monitoring_user - -# create a Kubernetes secret with the file realm content -kubectl create secret generic my-file-realm-secret --from-file filerealm -``` -::: - -:::: - -### Using {{k8s}} basic authentication secrets [k8s-basic] +#### Using {{k8s}} basic authentication secrets [file-realm-user-k8s] ```{applies_to} eck: all ``` -You can also add file-based authentication users using [Kubernetes basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). - -A basic authentication secret can optionally contain a [`roles`](#users_roles) entry. It must contain a comma separated list of roles to be associated with the user. The following example illustrates this combination: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: secret-basic-auth -type: kubernetes.io/basic-auth -stringData: - username: rdeniro # required field for kubernetes.io/basic-auth - password: mypassword # required field for kubernetes.io/basic-auth - roles: kibana_admin,ingest_admin # optional, not part of kubernetes.io/basic-auth -``` +You can also add `file` realm users using [{{k8s}} basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). You can reference several secrets in the {{es}} specification. {{eck}} aggregates their content into a single secret, mounted in every {{es}} Pod. -You can make this file available to {{eck}} by adding it as a file realm secret: - -```yaml -apiVersion: elasticsearch.k8s.elastic.co/v1 -kind: Elasticsearch -metadata: - name: elasticsearch-sample -spec: - version: 8.16.1 - auth: - fileRealm: - - secretName: secret-basic-auth - nodeSets: - - name: default - count: 1 -``` - -::::{note} If you specify the password for the `elastic` user through a basic authentication secret, then the secret holding the password described in [](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md) will not be created by the operator. -:::: + +Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced user in order to recover the {{stack}} {{security-features}}, you would + +1. Create a secret `my-roles-secret` adding our `superduperuser` role definition: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: my-roles-secret + stringData: + roles.yml: |- + superduperuser: + cluster: + - all + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true + ``` + +2. Setup a basic authentication secret `secret-basic-auth` which contains its `username`, `password`, and a comma-separated list of `roles`: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: secret-basic-auth + type: kubernetes.io/basic-auth + stringData: + username: admin # required field for kubernetes.io/basic-auth + password: changeme # required field for kubernetes.io/basic-auth + roles: superduperuser,superuser # optional, not part of kubernetes.io/basic-auth + ``` + +3. then make these available to {{eck}} by adding them to your {{es}} manifest: + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: elasticsearch-sample + spec: + version: 8.16.1 + auth: + fileRealm: + - secretName: secret-basic-auth + roles: + - secretName: my-roles-secret + nodeSets: + - name: default + count: 1 + ``` From 886c64233457ca61b02da77dac45c7daed18bff6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 14 Aug 2025 16:13:39 -0400 Subject: [PATCH 02/10] fix malformed links --- .../cluster-or-deployment-auth/file-based.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index 20c8fe7fdd..d165e83829 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -16,16 +16,16 @@ products: You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users and roles are defined in local files on each node. -The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. +The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. Therefore, the `file` realm is commonly used as a fallback or recovery realm. It is helpful in cases where the * Cluster is unresponsive * {{stack}} {{security-features}} is unavailable to the current node -* {{stack}} {{security-features}} is [lost and needs restored](/troubleshoot/elasticsearch/red-yellow-cluster-status#fix-cluster-status-restore) +* {{stack}} {{security-features}} is [lost and needs restored](/troubleshoot/elasticsearch/red-yellow-cluster-status.md#fix-cluster-status-restore) * Administrative users' passwords are lost and [need reset](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password) -The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administators of self-managed deployments are responsible to ensure that either +The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administrators of self-managed deployments are responsible to ensure that either * The same users and roles are defined across every node in the cluster. * Frequently administrators choose to apply the change on one of the {{es}} nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). @@ -53,26 +53,26 @@ You don’t need to explicitly configure the `file` realm. The `file` and `nativ Because `resource.reload.interval.high` is a foundational setting for {{es}}, changing its value may effect other schedules in the system. ::: -3. In self-managed deployments, if either prior setting is modified, you will need to [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures#restart-cluster-rolling) those {{es}} nodes for your changes to take effect. In {{eck}}, changes are automatically propagated. +3. In self-managed deployments, if either prior setting is modified, you will need to [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) those {{es}} nodes for your changes to take effect. In {{eck}}, changes are automatically propagated. ## Configure files [file-realm-files] -The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch#config-files-location) and contain +The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain -* `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles) -* `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles) -* `users` for [user password-based authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication) -* `user_roles` for [user role-based authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles) +* `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) +* `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) +* `users` for [user password-based authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md) +* `user_roles` for [user role-based authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) ### Define roles [file-realm-roles] Before granting a `file` realm user its roles, you will want to ensure those desired roles exists. Roles can be defined from -* [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles) -* [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles) defined under the {{stack}} {{security-features}} -* `roles.yml`per [File-based Role Management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles#roles-management-file) +* [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) +* [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined under the {{stack}} {{security-features}} +* `roles.yml`per [File-based role management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file) -{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users). While recovering {{stack}} {{security-features}}, you may need to temporarily define a role with `allow_restricted_indices` access enabled. For example, expanding the `superuser` role to include `allow_restricted_indices: true` would appear like like new role `superduperuser` definition +{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). While recovering {{stack}} {{security-features}}, you may need to temporarily define a role with `allow_restricted_indices` access enabled. For example, expanding the `superuser` role to include `allow_restricted_indices: true` would appear like like new role `superduperuser` definition ```yaml superduperuser: @@ -89,7 +89,7 @@ Restricted indices are a special category of indices that are used to store clus ### Define role mappings [file-realm-role-mappings] -For clusters with high authentication volume or with extremely large [role mappings](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles), you may potentially find performance improvement by defining custom `role_mapping.yml` locally on each node in the cluster. For more information, see [using role mapping files](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles#mapping-roles-file). +For clusters with high authentication volume or with extremely large [role mappings](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md), you may potentially find performance improvement by defining custom `role_mapping.yml` locally on each node in the cluster. For more information, see [using role mapping files](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). ### Add users [file-realm-users] @@ -102,7 +102,7 @@ For {{eck}} deployments, these can also be passed through [{{k8s}} basic authent #### Defining user files [file-realm-user-files] -For most administrators, {{es}} recommends using the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command) which compiles the `users` and `users_roles` files on your behalf. +For most administrators, {{es}} recommends using the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md) which compiles the `users` and `users_roles` files on your behalf. Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced administrative user in order to recover the {{stack}} {{security-features}}, you would run From 7dd134bd854c549ed7ae4616188dff4b5971321a Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Sat, 13 Sep 2025 10:00:52 -0600 Subject: [PATCH 03/10] feedback, creating new troubleshooting page instead --- .../cluster-or-deployment-auth/file-based.md | 287 ++++++++---------- troubleshoot/elasticsearch.md | 1 + .../elasticsearch/file-based-recovery.md | 213 +++++++++++++ troubleshoot/toc.yml | 1 + 4 files changed, 334 insertions(+), 168 deletions(-) create mode 100644 troubleshoot/elasticsearch/file-based-recovery.md diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index d165e83829..fd80b241d4 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -14,28 +14,20 @@ products: # File-based user authentication [file-realm] -You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users and roles are defined in local files on each node. +You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users are defined in local files on each node in the cluster. -The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. - -Therefore, the `file` realm is commonly used as a fallback or recovery realm. It is helpful in cases where the - -* Cluster is unresponsive -* {{stack}} {{security-features}} is unavailable to the current node -* {{stack}} {{security-features}} is [lost and needs restored](/troubleshoot/elasticsearch/red-yellow-cluster-status.md#fix-cluster-status-restore) -* Administrative users' passwords are lost and [need reset](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password) - -The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administrators of self-managed deployments are responsible to ensure that either - -* The same users and roles are defined across every node in the cluster. - * Frequently administrators choose to apply the change on one of the {{es}} nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). -* The related API requests are directed to the local node rather than any cluster-level load balancer or proxy URL. +The `file` realm is useful as a fallback or recovery realm. For example in cases where the cluster is unresponsive or the security index is unavailable, or when you forget the password for your administrative users. In this type of scenario, the `file` realm is a convenient workaround: you can define a new `admin` user in the `file` realm and use it to log in and reset the credentials of all other users. For more information, see [file-based recovery](troubleshoot/elasticsearch/file-based-recovery.md). Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. -## Configure realm [file-realm-configuration] +::::{important} +* In self-managed deployments, as the administrator of the cluster, it is your responsibility to ensure the same users are defined on every node in the cluster. The {{stack}} {{security-features}} do not deliver any mechanism to guarantee this. +* You can't add or manage users in the `file` realm using the [user APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security), or using the {{kib}} **Management > Security > Users** page. +:::: + +## Configure a file realm [file-realm-configuration] -You don’t need to explicitly configure the `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm per node. To override the default `file` realm configuration +You don’t need to explicitly configure a `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm per node. 1. (Optional) Add a realm configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md) under the `xpack.security.authc.realms.file` namespace. At a minimum, you must set the realm’s `order` attribute. @@ -45,125 +37,74 @@ You don’t need to explicitly configure the `file` realm. The `file` and `nativ xpack.security.authc.realms.file.file1.order: 0 ``` -2. (Optional) For self-managed deployments, you may change how often `file` realm backing files are checked. +2. (Optional) For self-managed deployments, you may change how often the `users` and `users_roles` files are checked. - By default, {{es}} checks these files for changes every 5 seconds. You can override this default behavior by changing the `resource.reload.interval.high` setting's value in the [`elasticsearch.yml`](/deploy-manage/stack-settings.md) file. + By default, {{es}} checks these files for changes every 5 seconds. You can change this default behavior by changing the `resource.reload.interval.high` setting in the [`elasticsearch.yml`](/deploy-manage/stack-settings.md) file. :::{{warning}} - Because `resource.reload.interval.high` is a foundational setting for {{es}}, changing its value may effect other schedules in the system. + Because `resource.reload.interval.high` is a common setting in {{es}}, changing its value may effect other schedules in the system. ::: 3. In self-managed deployments, if either prior setting is modified, you will need to [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) those {{es}} nodes for your changes to take effect. In {{eck}}, changes are automatically propagated. -## Configure files [file-realm-files] - -The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain -* `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) -* `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) -* `users` for [user password-based authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md) -* `user_roles` for [user role-based authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) +## Add users -### Define roles [file-realm-roles] +**In a self-managed {{es}} cluster**, all the data about the users for the `file` realm is stored in two files on each node in the cluster: [`users` and `users_roles`](#using-users-and-users_roles-files). Both files are located in `ES_PATH_CONF` and are read on startup. -Before granting a `file` realm user its roles, you will want to ensure those desired roles exists. Roles can be defined from +**In an {{eck}} deployment**, you can pass file realm user information in two ways: -* [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) -* [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined under the {{stack}} {{security-features}} -* `roles.yml`per [File-based role management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file) - -{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). While recovering {{stack}} {{security-features}}, you may need to temporarily define a role with `allow_restricted_indices` access enabled. For example, expanding the `superuser` role to include `allow_restricted_indices: true` would appear like like new role `superduperuser` definition - -```yaml -superduperuser: - cluster: [ 'all' ] - indices: - - names: [ '*' ] - privileges: [ 'all' ] - allow_restricted_indices: true -``` - -:::{{warning}} -Restricted indices are a special category of indices that are used to store cluster configuration data and should not normally be directly accessed. **Toggling this flag is normally very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If `allow_restricted_indices` needs temporarily enabled for a user in order to recover the {{stack}} {{security-features}}, {{es}} recommends ensuring to remove this role with sensitive access from the user upon task completion. -::: +1. Using [`users` and `user_roles`](#using-users-and-users_roles-files) files, which are passed using file realm content secrets +2. [Using Kubernetes basic authentication secrets](#k8s-basic) -### Define role mappings [file-realm-role-mappings] +You can reference several secrets in the {{es}} specification. ECK aggregates their content into a single secret, mounted in every {{es}} Pod. -For clusters with high authentication volume or with extremely large [role mappings](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md), you may potentially find performance improvement by defining custom `role_mapping.yml` locally on each node in the cluster. For more information, see [using role mapping files](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md#mapping-roles-file). +::::{important} +In a self-managed cluster, the `users` and `users_roles` files are managed locally by the node and are **not** managed globally by the cluster. This means that with a typical multi-node cluster, the exact same changes need to be applied on each and every node in the cluster. -### Add users [file-realm-users] +A safer approach would be to apply the change on one of the nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). +:::: -The `file` realm can [define users](#file-realm-user-files) from files +### Using `users` and `users_roles` files -* `users` for password-based authentication -* `users_roles` for role-based authorization +`users` and `users_roles` files contain all of the information about users in the file realm. -For {{eck}} deployments, these can also be passed through [{{k8s}} basic authentication secrets](#file-realm-user-k8s). +#### `users` -#### Defining user files [file-realm-user-files] +The `users` file stores all the users and their passwords. Each line in the file represents a single user entry consisting of the username and hashed and salted password. -For most administrators, {{es}} recommends using the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md) which compiles the `users` and `users_roles` files on your behalf. +``` +rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W +alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS +jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= +``` -Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced administrative user in order to recover the {{stack}} {{security-features}}, you would run +:::{tip} +To limit exposure to credential theft and mitigate credential compromise, the file realm stores passwords and caches user credentials according to security best practices. By default, a hashed version of user credentials is stored in memory, using a salted sha-256 hash algorithm and a hashed version of passwords is stored on disk salted and hashed with the bcrypt hash algorithm. To use different hash algorithms, see [User cache and password hash algorithms](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#hashing-settings). +::: -::::{tab-set} +#### `users_roles` -:::{tab-item} Self-managed +The `users_roles` file stores the roles associated with the users. For example: ``` -bin/elasticsearch-users useradd admin -p changeme -r superduperuser +admin:rdeniro +power_user:alpacino,jacknich +user:jacknich ``` -::: -:::{tab-item} {{eck}} -The following is an example of invoking the `elasticsearch-users` tool in a Docker container: +Each row maps a role to a comma-separated list of all the users that are associated with that role. -```sh -# create a folder with the 2 files -mkdir filerealm -touch filerealm/users filerealm/users_roles - -# create user 'admin' with role 'superduperuser' -docker run \ - -v $(pwd)/filerealm:/usr/share/elasticsearch/config \ - docker.elastic.co/elasticsearch/elasticsearch:9.1.0 \ - bin/elasticsearch-users useradd admin -p changeme -r superduperuser - -# create a Kubernetes secret with the file realm content -kubectl create secret generic my-file-realm-secret --from-file filerealm -``` -::: +#### Editing `users` and `users_roles` files -:::: +You can edit files and secrets that contain `users` and `users_roles` manually, or you can edit them using a tool. -For advanced users, you may choose to edit the `users` and `users_roles` files directly. +**Manually** ::::{tab-set} :::{tab-item} Self-managed -In a self-managed cluster, you can edit the contents of `$ES_PATH_CONF/users` and `$ES_PATH_CONF/users_roles` directly. - -* `users` - - The `users` file stores all the users and their passwords. Each line in the file represents a single user entry consisting of the username and hashed and salted password. For example: - - ``` - rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W - alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS - jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= - ``` - - To limit exposure to credential theft and mitigate credential compromise, the file realm stores passwords and caches user credentials according to security best practices. By default, a hashed version of user credentials is stored in memory, using a salted sha-256 hash algorithm and a hashed version of passwords is stored on disk salted and hashed with the bcrypt hash algorithm. To use different hash algorithms, see [User cache and password hash algorithms](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#hashing-settings). - -* `users_roles` - - The `users_roles` file stores the roles associated with the users. Each row maps a role to a comma-separated list of all the users that are associated with that role. For example: - - ``` - admin:rdeniro - superduperuser:alpacino,jacknich - user:jacknich - ``` +In a self-managed cluster, you can edit the contents of `ES_PATH_CONF/users` and `ES_PATH_CONF/users_roles` directly. ::: :::{tab-item} {{eck}} @@ -189,7 +130,7 @@ A file realm secret is composed of two entries: a `users` entry and a `users_rol If you specify multiple users with the same name in more than one secret, the last one takes precedence. If you specify multiple roles with the same name in more than one secret, a single entry per role is derived from the concatenation of its corresponding users from all secrets. -The following secret specifies three users and their respective built-in and custom roles: +The following secret specifies three users and their respective roles: ```yaml kind: Secret @@ -197,84 +138,94 @@ apiVersion: v1 metadata: name: my-filerealm-secret stringData: - roles.yml: |- - superduperuser: - cluster: - - all - indices: - - names: [ '*' ] - privileges: [ 'all' ] - allow_restricted_indices: true users: |- rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= users_roles: |- admin:rdeniro - superduperuser:alpacino,jacknich + power_user:alpacino,jacknich user:jacknich ``` ::: :::: -#### Using {{k8s}} basic authentication secrets [file-realm-user-k8s] +**Using a tool** + +To avoid editing these files manually, you can use the [elasticsearch-users](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md) tool: + +::::{tab-set} + +:::{tab-item} Self-managed + +``` +bin/elasticsearch-users useradd myuser -p mypassword -r monitoring_user +``` +::: + +:::{tab-item} {{eck}} +The following is an example of invoking the `elasticsearch-users` tool in a Docker container: + +```sh +# create a folder with the 2 files +mkdir filerealm +touch filerealm/users filerealm/users_roles + +# create user 'myuser' with role 'monitoring_user' +docker run \ + -v $(pwd)/filerealm:/usr/share/elasticsearch/config \ + docker.elastic.co/elasticsearch/elasticsearch:8.16.1 \ + bin/elasticsearch-users useradd myuser -p mypassword -r monitoring_user + +# create a Kubernetes secret with the file realm content +kubectl create secret generic my-file-realm-secret --from-file filerealm +``` +::: + +:::: + +### Using {{k8s}} basic authentication secrets [k8s-basic] ```{applies_to} eck: all ``` -You can also add `file` realm users using [{{k8s}} basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). You can reference several secrets in the {{es}} specification. {{eck}} aggregates their content into a single secret, mounted in every {{es}} Pod. +You can also add file-based authentication users using [Kubernetes basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). -If you specify the password for the `elastic` user through a basic authentication secret, then the secret holding the password described in [](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md) will not be created by the operator. +A basic authentication secret can optionally contain a [`roles`](#users_roles) entry. It must contain a comma separated list of roles to be associated with the user. The following example illustrates this combination: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: secret-basic-auth +type: kubernetes.io/basic-auth +stringData: + username: rdeniro # required field for kubernetes.io/basic-auth + password: mypassword # required field for kubernetes.io/basic-auth + roles: kibana_admin,ingest_admin # optional, not part of kubernetes.io/basic-auth +``` + +::::{tip} +To create custom roles that can be referenced in this list refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file). +:::: + +You can make this file available to {{eck}} by adding it as a file realm secret: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + auth: + fileRealm: + - secretName: secret-basic-auth + nodeSets: + - name: default + count: 1 +``` -Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced user in order to recover the {{stack}} {{security-features}}, you would - -1. Create a secret `my-roles-secret` adding our `superduperuser` role definition: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: my-roles-secret - stringData: - roles.yml: |- - superduperuser: - cluster: - - all - indices: - - names: [ '*' ] - privileges: [ 'all' ] - allow_restricted_indices: true - ``` - -2. Setup a basic authentication secret `secret-basic-auth` which contains its `username`, `password`, and a comma-separated list of `roles`: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: secret-basic-auth - type: kubernetes.io/basic-auth - stringData: - username: admin # required field for kubernetes.io/basic-auth - password: changeme # required field for kubernetes.io/basic-auth - roles: superduperuser,superuser # optional, not part of kubernetes.io/basic-auth - ``` - -3. then make these available to {{eck}} by adding them to your {{es}} manifest: - - ```yaml - apiVersion: elasticsearch.k8s.elastic.co/v1 - kind: Elasticsearch - metadata: - name: elasticsearch-sample - spec: - version: 8.16.1 - auth: - fileRealm: - - secretName: secret-basic-auth - roles: - - secretName: my-roles-secret - nodeSets: - - name: default - count: 1 - ``` +::::{note} +If you specify the password for the `elastic` user through a basic authentication secret, then the secret holding the password described in [](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md) will not be created by the operator. +:::: diff --git a/troubleshoot/elasticsearch.md b/troubleshoot/elasticsearch.md index 0bc62bf4ad..dac135b651 100644 --- a/troubleshoot/elasticsearch.md +++ b/troubleshoot/elasticsearch.md @@ -35,6 +35,7 @@ If you're using {{ech}}, you can use AutoOps to monitor your cluster. AutoOps si * [](/troubleshoot/elasticsearch/start-ilm.md) * [](/troubleshoot/elasticsearch/index-lifecycle-management-errors.md) +* [](/troubleshoot/elasticsearch/file-based-recovery.md) ## Capacity [troubleshooting-capacity] diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md new file mode 100644 index 0000000000..ee12e4457e --- /dev/null +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -0,0 +1,213 @@ +--- +navigation_title: File-Based Recovery +applies_to: + stack: + deployment: + eck: + self: +products: + - id: elasticsearch +--- + +# File-based Recovery [file-based-recovery] + +The [built-in `file` realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md) is commonly used as a fallback or recovery realm. + +The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. + +The `file` realm is helpful in cases where the + +* Node services are running but cluster is unresponsive +* {{stack}} {{security-features}} is unavailable to the current node +* {{stack}} {{security-features}} is [lost and needs restored](/troubleshoot/elasticsearch/red-yellow-cluster-status.md#fix-cluster-status-restore) +* Administrative users' passwords are lost and [need reset](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password) + +The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administrators of self-managed deployments are responsible to ensure that either + +* The same users and roles are defined across every node in the cluster. + * Frequently administrators choose to apply the change on one of the {{es}} nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). +* The related API requests are directed to the local node rather than any cluster-level load balancer or proxy URL. + +Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. + +## Configure realm [file-realm-recovery-configuration] + +The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. The `file` realm can only be added once per node. To override the default `file` realm configuration, see [Configure a file realm](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#file-realm-configuration). + +The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain + +* `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) +* `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) +* `users` for [user password-based authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md) +* `user_roles` for [user role-based authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) + +### Choose roles [file-realm-recovery-roles] + +Before granting a `file` realm user its roles, you will want to ensure those desired roles exist. Roles can be defined from + +* [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) +* [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined under the {{stack}} {{security-features}} +* `roles.yml`per [file-based role management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file) + +{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). + +While recovering {{stack}} {{security-features}}, you may need to temporarily define a custom role with [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. For example, expanding the `superuser` role to include `allow_restricted_indices: true` would appear like like new role `superduperuser` definition + +```yaml +superduperuser: + cluster: [ 'all' ] + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true +``` + +Once role authorization criteria is decided, you will be ready to add this role into your local node's configuration. We will demonstrate this below. + +:::{{warning}} +Restricted indices are a special category of indices that are used to store cluster configuration data and should not normally be directly accessed. **Toggling this flag is normally _strongly_ discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If `allow_restricted_indices` needs temporarily enabled for a user in order to recover the {{stack}} {{security-features}}, {{es}} recommends ensuring to remove this role with sensitive access from the user upon task completion. +::: + +#### Defining files [file-realm-recovery-files] + +For most administrators, {{es}} recommends using the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md) which compiles the `users` and `users_roles` files on your behalf. + +Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced administrative user in order to recover the {{stack}} {{security-features}}, you would run + +::::{tab-set} + +:::{tab-item} Self-managed + +``` +bin/elasticsearch-users useradd admin -p changeme -r superduperuser +``` +::: + +:::{tab-item} {{eck}} secrets +The following is an example of invoking the `elasticsearch-users` tool in a Docker container: + +```sh +# create a folder with the 2 files +mkdir filerealm +touch filerealm/users filerealm/users_roles + +# create user 'admin' with role 'superduperuser' +docker run \ + -v $(pwd)/filerealm:/usr/share/elasticsearch/config \ + docker.elastic.co/elasticsearch/elasticsearch:9.1.0 \ + bin/elasticsearch-users useradd admin -p changeme -r superduperuser + +# create a Kubernetes secret with the file realm content +kubectl create secret generic my-file-realm-secret --from-file filerealm +``` + +You can pass `users` and `user_roles` files to {{eck}} using a file realm secret: + +```yaml +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: elasticsearch-sample +spec: + version: 8.16.1 + auth: + fileRealm: + - secretName: my-filerealm-secret-1 + - secretName: my-filerealm-secret-2 + nodeSets: + - name: default + count: 1 +``` + +A file realm secret is composed of two entries: a `users` entry and a `users_roles` entry. You can provide either one entry or both entries in each secret. + +If you specify multiple users with the same name in more than one secret, the last one takes precedence. If you specify multiple roles with the same name in more than one secret, a single entry per role is derived from the concatenation of its corresponding users from all secrets. + +The following secret specifies three users and their respective built-in and custom roles: + +```yaml +kind: Secret +apiVersion: v1 +metadata: + name: my-filerealm-secret +stringData: + roles.yml: |- + superduperuser: + cluster: + - all + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true + users: |- + rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W + alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS + jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg= + users_roles: |- + admin:rdeniro + superduperuser:alpacino,jacknich + user:jacknich +``` +::: + + +:::{tab-item} {{eck}} basic auth + +You can also add `file` realm users using [{{k8s}} basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). For more information, see [`file` realm](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#k8s-basic) + +Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced user in order to recover the {{stack}} {{security-features}}, you would + +1. Create a secret `my-roles-secret` adding our `superduperuser` role definition: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: my-roles-secret + stringData: + roles.yml: |- + superduperuser: + cluster: + - all + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true + ``` + +2. Setup a basic authentication secret `secret-basic-auth` which contains its `username`, `password`, and a comma-separated list of `roles`: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: secret-basic-auth + type: kubernetes.io/basic-auth + stringData: + username: admin # required field for kubernetes.io/basic-auth + password: changeme # required field for kubernetes.io/basic-auth + roles: superduperuser,superuser # optional, not part of kubernetes.io/basic-auth + ``` + +3. then make these available to {{eck}} by adding them to your {{es}} manifest: + + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: elasticsearch-sample + spec: + version: 8.16.1 + auth: + fileRealm: + - secretName: secret-basic-auth + roles: + - secretName: my-roles-secret + nodeSets: + - name: default + count: 1 + ``` + +::: + +:::: \ No newline at end of file diff --git a/troubleshoot/toc.yml b/troubleshoot/toc.yml index da48207bb5..d5fe0bcc22 100644 --- a/troubleshoot/toc.yml +++ b/troubleshoot/toc.yml @@ -54,6 +54,7 @@ toc: - file: elasticsearch/troubleshooting-searches.md - file: elasticsearch/start-ilm.md - file: elasticsearch/index-lifecycle-management-errors.md + - file: elasticsearch/file-based-recovery.md - file: elasticsearch/security.md children: - file: elasticsearch/security/security-trb-settings.md From 903fac9cbdaa3995c71eeb9792f7cb07ad34d76a Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 16 Sep 2025 15:55:19 -0400 Subject: [PATCH 04/10] Apply suggestions from code review --- .../users-roles/cluster-or-deployment-auth/file-based.md | 2 +- troubleshoot/elasticsearch/file-based-recovery.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index fd80b241d4..699d4c62e4 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -16,7 +16,7 @@ products: You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users are defined in local files on each node in the cluster. -The `file` realm is useful as a fallback or recovery realm. For example in cases where the cluster is unresponsive or the security index is unavailable, or when you forget the password for your administrative users. In this type of scenario, the `file` realm is a convenient workaround: you can define a new `admin` user in the `file` realm and use it to log in and reset the credentials of all other users. For more information, see [file-based recovery](troubleshoot/elasticsearch/file-based-recovery.md). +The `file` realm is useful as a fallback or recovery realm. For example in cases where the cluster is unresponsive or the security index is unavailable, or when you forget the password for your administrative users. In this type of scenario, the `file` realm is a convenient workaround: you can define a new `admin` user in the `file` realm and use it to log in and reset the credentials of all other users. For more information, see [file-based recovery](/troubleshoot/elasticsearch/file-based-recovery.md). Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index ee12e4457e..370fee3b1e 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -9,9 +9,9 @@ products: - id: elasticsearch --- -# File-based Recovery [file-based-recovery] +# File-based recovery [file-based-recovery] -The [built-in `file` realm](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md) is commonly used as a fallback or recovery realm. +The [built-in `file` realm](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md) is commonly used as a fallback or recovery realm. The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. From ab09f8ff84c192770dac46ab391d949c44843579 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 16 Sep 2025 17:05:02 -0400 Subject: [PATCH 05/10] style edits --- .../cluster-or-deployment-auth/file-based.md | 20 +- .../elasticsearch/file-based-recovery.md | 174 +++++++++--------- 2 files changed, 99 insertions(+), 95 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index 699d4c62e4..2302c7c689 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -5,8 +5,8 @@ mapped_pages: - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-users-and-roles.html applies_to: deployment: - self: all - eck: all + self: ga + eck: ga products: - id: elasticsearch - id: cloud-kubernetes @@ -16,9 +16,7 @@ products: You can manage and authenticate users with the built-in `file` realm. With the `file` realm, users are defined in local files on each node in the cluster. -The `file` realm is useful as a fallback or recovery realm. For example in cases where the cluster is unresponsive or the security index is unavailable, or when you forget the password for your administrative users. In this type of scenario, the `file` realm is a convenient workaround: you can define a new `admin` user in the `file` realm and use it to log in and reset the credentials of all other users. For more information, see [file-based recovery](/troubleshoot/elasticsearch/file-based-recovery.md). - -Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. +The `file` realm is useful as a fallback or recovery realm. For example, you might use this realm in cases where the cluster is unresponsive or the security index is unavailable, or when you forget the password for your administrative users. In this type of scenario, the `file` realm is a convenient workaround: you can define a new `admin` user in the `file` realm and use it to log in and reset the credentials of all other users. For a walkthrough of this process, refer to [](/troubleshoot/elasticsearch/file-based-recovery.md). Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. ::::{important} * In self-managed deployments, as the administrator of the cluster, it is your responsibility to ensure the same users are defined on every node in the cluster. The {{stack}} {{security-features}} do not deliver any mechanism to guarantee this. @@ -27,7 +25,7 @@ Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch ## Configure a file realm [file-realm-configuration] -You don’t need to explicitly configure a `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm per node. +You don’t need to explicitly configure a `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm on each node. 1. (Optional) Add a realm configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md) under the `xpack.security.authc.realms.file` namespace. At a minimum, you must set the realm’s `order` attribute. @@ -37,7 +35,7 @@ You don’t need to explicitly configure a `file` realm. The `file` and `native` xpack.security.authc.realms.file.file1.order: 0 ``` -2. (Optional) For self-managed deployments, you may change how often the `users` and `users_roles` files are checked. +2. (Optional) For self-managed deployments, you can change how often the `users` and `users_roles` files are checked. By default, {{es}} checks these files for changes every 5 seconds. You can change this default behavior by changing the `resource.reload.interval.high` setting in the [`elasticsearch.yml`](/deploy-manage/stack-settings.md) file. @@ -45,7 +43,9 @@ You don’t need to explicitly configure a `file` realm. The `file` and `native` Because `resource.reload.interval.high` is a common setting in {{es}}, changing its value may effect other schedules in the system. ::: -3. In self-managed deployments, if either prior setting is modified, you will need to [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) those {{es}} nodes for your changes to take effect. In {{eck}}, changes are automatically propagated. +3. In self-managed deployments, if of these settings is modified, perform a [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) of the {{es}} nodes for your changes to take effect. + + In {{eck}}, changes are automatically propagated. ## Add users @@ -110,13 +110,13 @@ In a self-managed cluster, you can edit the contents of `ES_PATH_CONF/users` and :::{tab-item} {{eck}} You can pass `users` and `user_roles` files to {{eck}} using a file realm secret: -```yaml +```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: name: elasticsearch-sample spec: - version: 8.16.1 + version: {{version.stack}} auth: fileRealm: - secretName: my-filerealm-secret-1 diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index 370fee3b1e..9aa557a9c0 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -1,57 +1,61 @@ --- -navigation_title: File-Based Recovery applies_to: - stack: deployment: - eck: - self: + eck: ga + self: ga products: - id: elasticsearch + - id: cloud-kubernetes --- -# File-based recovery [file-based-recovery] +# File-based recovery The [built-in `file` realm](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md) is commonly used as a fallback or recovery realm. -The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. The `file` realm cannot be managed using the cluster's [security APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) nor using {{kib}} **Management > Security** pages. +The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). The `file` realm acts as a failsafe to expand this feature's functionality from the cluster level down to each individual node. -The `file` realm is helpful in cases where the +The `file` realm is especially helpful for recovery scenarios where normal security mechanisms aren't accessible: * Node services are running but cluster is unresponsive -* {{stack}} {{security-features}} is unavailable to the current node -* {{stack}} {{security-features}} is [lost and needs restored](/troubleshoot/elasticsearch/red-yellow-cluster-status.md#fix-cluster-status-restore) -* Administrative users' passwords are lost and [need reset](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password) +* {{stack}} {{security-features}} are unavailable to the current node +* {{stack}} {{security-features}} are [lost and need to be restored](/troubleshoot/elasticsearch/red-yellow-cluster-status.md#fix-cluster-status-restore) +* Administrative users' passwords are lost and [need to be reset](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password) -The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administrators of self-managed deployments are responsible to ensure that either +The {{stack}} {{security-features}} only apply the `file` realm to the modified local node and do not apply changes across all nodes within the cluster. Administrators of self-managed deployments are responsible for ensuring one of the following: * The same users and roles are defined across every node in the cluster. - * Frequently administrators choose to apply the change on one of the {{es}} nodes and have the files distributed or copied to all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef). -* The related API requests are directed to the local node rather than any cluster-level load balancer or proxy URL. + + Frequently, administrators choose to apply the change on one {{es}} node and then distribute or copy the files to all other nodes in the cluster. Files can be distributed either manually or using a configuration management system such as Puppet or Chef. +* The related API requests are directed to the local node rather than to any cluster-level load balancer or proxy URL. Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. -## Configure realm [file-realm-recovery-configuration] +## Step 1 (Optional): Configure the realm [file-realm-recovery-configuration] + +You don’t need to explicitly configure a `file` realm. The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. You can define only one `file` realm on each node. -The `file` and `native` realms are added to the realm chain by default. Unless configured otherwise, the `file` realm is added first, followed by the `native` realm. The `file` realm can only be added once per node. To override the default `file` realm configuration, see [Configure a file realm](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#file-realm-configuration). +To learn how to override the default `file` realm configuration, refer to [Configure a file realm](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#file-realm-configuration). -The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain +The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain the following information: * `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) * `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) * `users` for [user password-based authentication](/deploy-manage/users-roles/cluster-or-deployment-auth/user-authentication.md) * `user_roles` for [user role-based authorization](/deploy-manage/users-roles/cluster-or-deployment-auth/user-roles.md) -### Choose roles [file-realm-recovery-roles] +## Step 2: Choose roles for recovery [file-realm-recovery-roles] -Before granting a `file` realm user its roles, you will want to ensure those desired roles exist. Roles can be defined from +Before granting a `file` realm user any roles, you need to ensure that those desired roles exist. You can use the following types of roles: -* [built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) -* [custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined under the {{stack}} {{security-features}} -* `roles.yml`per [file-based role management](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file) +* [Built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) +* [Custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined under the {{stack}} {{security-features}} +* Roles defined in [`roles.yml`](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file) {{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). -While recovering {{stack}} {{security-features}}, you may need to temporarily define a custom role with [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. For example, expanding the `superuser` role to include `allow_restricted_indices: true` would appear like like new role `superduperuser` definition +When recovering {{stack}} {{security-features}}, you might need to temporarily define a custom role with the [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. + +For example, to grant all of the privileges of `superuser` role alongside `allow_restricted_indices: true` you can create a new role called `superduperuser` with the following definition: ```yaml superduperuser: @@ -62,17 +66,19 @@ superduperuser: allow_restricted_indices: true ``` -Once role authorization criteria is decided, you will be ready to add this role into your local node's configuration. We will demonstrate this below. +After you decide on your role definitions, you can add your users and any custom roles to your local node's configuration. :::{{warning}} -Restricted indices are a special category of indices that are used to store cluster configuration data and should not normally be directly accessed. **Toggling this flag is normally _strongly_ discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** If `allow_restricted_indices` needs temporarily enabled for a user in order to recover the {{stack}} {{security-features}}, {{es}} recommends ensuring to remove this role with sensitive access from the user upon task completion. +Restricted indices are a special category of indices that are used to store cluster configuration data and should not normally be directly accessed. **Toggling this flag is normally _strongly_ discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information.** + +If `allow_restricted_indices` needs temporarily enabled for a user in order to recover the {{stack}} {{security-features}}, {{es}} recommends ensuring to remove this role with sensitive access from the user upon task completion. ::: -#### Defining files [file-realm-recovery-files] +## Step 3: Add the recovery user and role to the node [file-realm-recovery-files] -For most administrators, {{es}} recommends using the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md) which compiles the `users` and `users_roles` files on your behalf. +For most administrators, {{es}} recommends that you use the [`elasticsearch-users` tool](elasticsearch://reference/elasticsearch/command-line-tools/users-command.md), which compiles the `users` and `users_roles` files on your behalf. -Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced administrative user in order to recover the {{stack}} {{security-features}}, you would run +In this example, we create an advanced administrative user with the `superduperuser` role we designed [in the previous step](#file-realm-recovery-roles). ::::{tab-set} @@ -83,10 +89,10 @@ bin/elasticsearch-users useradd admin -p changeme -r superduperuser ``` ::: -:::{tab-item} {{eck}} secrets +:::{tab-item} ECK secrets The following is an example of invoking the `elasticsearch-users` tool in a Docker container: -```sh +```sh subs=true # create a folder with the 2 files mkdir filerealm touch filerealm/users filerealm/users_roles @@ -94,7 +100,7 @@ touch filerealm/users filerealm/users_roles # create user 'admin' with role 'superduperuser' docker run \ -v $(pwd)/filerealm:/usr/share/elasticsearch/config \ - docker.elastic.co/elasticsearch/elasticsearch:9.1.0 \ + docker.elastic.co/elasticsearch/elasticsearch:{{version.stack}} \ bin/elasticsearch-users useradd admin -p changeme -r superduperuser # create a Kubernetes secret with the file realm content @@ -103,13 +109,13 @@ kubectl create secret generic my-file-realm-secret --from-file filerealm You can pass `users` and `user_roles` files to {{eck}} using a file realm secret: -```yaml +```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: name: elasticsearch-sample spec: - version: 8.16.1 + version: {{version.stack}} auth: fileRealm: - secretName: my-filerealm-secret-1 @@ -151,62 +157,60 @@ stringData: ::: -:::{tab-item} {{eck}} basic auth - -You can also add `file` realm users using [{{k8s}} basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). For more information, see [`file` realm](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#k8s-basic) +:::{tab-item} ECK basic auth -Expanding on our earlier `superduperuser` role example as part of demonstrating creating an advanced user in order to recover the {{stack}} {{security-features}}, you would +You can also add `file` realm users using [{{k8s}} basic authentication secrets](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). For more information, refer to [](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md#k8s-basic). -1. Create a secret `my-roles-secret` adding our `superduperuser` role definition: +1. Create a secret `my-roles-secret` that adds the `superduperuser` role definition: - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: my-roles-secret - stringData: - roles.yml: |- - superduperuser: - cluster: - - all - indices: - - names: [ '*' ] - privileges: [ 'all' ] - allow_restricted_indices: true - ``` - -2. Setup a basic authentication secret `secret-basic-auth` which contains its `username`, `password`, and a comma-separated list of `roles`: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: secret-basic-auth - type: kubernetes.io/basic-auth - stringData: - username: admin # required field for kubernetes.io/basic-auth - password: changeme # required field for kubernetes.io/basic-auth - roles: superduperuser,superuser # optional, not part of kubernetes.io/basic-auth - ``` - -3. then make these available to {{eck}} by adding them to your {{es}} manifest: - - ```yaml - apiVersion: elasticsearch.k8s.elastic.co/v1 - kind: Elasticsearch - metadata: - name: elasticsearch-sample - spec: - version: 8.16.1 - auth: - fileRealm: - - secretName: secret-basic-auth - roles: - - secretName: my-roles-secret - nodeSets: - - name: default - count: 1 - ``` + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: my-roles-secret + stringData: + roles.yml: |- + superduperuser: + cluster: + - all + indices: + - names: [ '*' ] + privileges: [ 'all' ] + allow_restricted_indices: true + ``` + +2. Set up a basic authentication secret `secret-basic-auth` which contains its `username`, `password`, and a comma-separated list of `roles`: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: secret-basic-auth + type: kubernetes.io/basic-auth + stringData: + username: admin # required field for kubernetes.io/basic-auth + password: changeme # required field for kubernetes.io/basic-auth + roles: superduperuser,superuser # optional, not part of kubernetes.io/basic-auth + ``` + +3. Make the secrets available to {{eck}} by adding them to your {{es}} manifest: + + ```yaml subs=true + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: elasticsearch-sample + spec: + version: {{version.stack}} + auth: + fileRealm: + - secretName: secret-basic-auth + roles: + - secretName: my-roles-secret + nodeSets: + - name: default + count: 1 + ``` ::: From 549ae199fadbe306716c707bcd23e0825f7ba588 Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Tue, 16 Sep 2025 15:37:01 -0600 Subject: [PATCH 06/10] =?UTF-8?q?feedback=20=F0=9F=99=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- troubleshoot/elasticsearch/file-based-recovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index 9aa557a9c0..24f36fc080 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -8,7 +8,7 @@ products: - id: cloud-kubernetes --- -# File-based recovery +# File-based access recovery The [built-in `file` realm](/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md) is commonly used as a fallback or recovery realm. From 0fd6668c79f5d21f59b0e68b4dfeb3bbac2e5c0a Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Thu, 18 Sep 2025 17:29:48 -0600 Subject: [PATCH 07/10] =?UTF-8?q?feedback=20=F0=9F=99=8F,=20+step4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../elasticsearch/file-based-recovery.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index 24f36fc080..d2a92f1341 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -53,7 +53,7 @@ Before granting a `file` realm user any roles, you need to ensure that those des {{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). -When recovering {{stack}} {{security-features}}, you might need to temporarily define a custom role with the [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. +The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). When recovering {{stack}} {{security-features}}, you will likely need to temporarily define a custom role with the [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. For example, to grant all of the privileges of `superuser` role alongside `allow_restricted_indices: true` you can create a new role called `superduperuser` with the following definition: @@ -214,4 +214,22 @@ You can also add `file` realm users using [{{k8s}} basic authentication secrets] ::: -:::: \ No newline at end of file +:::: + +## Step 4: Recover {{security-features}} [file-realm-recovery-curl] + +At this point, the local {{es}} node will accept [Elasticsearch API requests](https://www.elastic.co/docs/reference/elasticsearch/rest-apis) with the created `file` based username and password. Assuming username `admin` was created with password `changeme` and role `superduperuser`, then you could curl the [Get cluster info API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-info) from the node's local shell +```bash +curl -X GET -sk -u "admin:changeme" "https://localhost:9200/" +``` + +:::{{tip}} +The related API requests need to be directed to the local node(s) where `file` has been configured rather than to any cluster-level load balancer or proxy URL. +::: + +You can confirm desired `superduperuser` role is applied to your `admin` username with [Authenticate a user API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-authenticate) +```bash +curl -X GET -sk -u "admin:changeme" "https://localhost:9200/_security/_authenticate?pretty=true" +``` + +Now that you have regained recovery access to the cluster you can investigate and recover the {{stack}} {{security-features}} as needed. \ No newline at end of file From ad8d712b58cb5c72994df6f8ceec72713436a0ac Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Fri, 19 Sep 2025 14:23:48 -0400 Subject: [PATCH 08/10] Apply suggestions from code review --- troubleshoot/elasticsearch/file-based-recovery.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index d2a92f1341..6e2dd3c56e 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -28,7 +28,9 @@ The {{stack}} {{security-features}} only apply the `file` realm to the modified Frequently, administrators choose to apply the change on one {{es}} node and then distribute or copy the files to all other nodes in the cluster. Files can be distributed either manually or using a configuration management system such as Puppet or Chef. * The related API requests are directed to the local node rather than to any cluster-level load balancer or proxy URL. -Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough. +:::{tip} +Refer to [enabling a file realm user for recovery](https://www.youtube.com/watch?v=sueO7sz1buw) for a video walkthrough of this process. +::: ## Step 1 (Optional): Configure the realm [file-realm-recovery-configuration] @@ -218,18 +220,20 @@ You can also add `file` realm users using [{{k8s}} basic authentication secrets] ## Step 4: Recover {{security-features}} [file-realm-recovery-curl] -At this point, the local {{es}} node will accept [Elasticsearch API requests](https://www.elastic.co/docs/reference/elasticsearch/rest-apis) with the created `file` based username and password. Assuming username `admin` was created with password `changeme` and role `superduperuser`, then you could curl the [Get cluster info API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-info) from the node's local shell +At this point, the local {{es}} node will accept [Elasticsearch API requests](https://www.elastic.co/docs/reference/elasticsearch/rest-apis) with the created `file` based username and password. + +For example, if you created a user with the username `admin`, password `changeme`, and role `superduperuser`, then you can now send a cURL request to the [Get cluster info API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-info) from the node's local shell: ```bash curl -X GET -sk -u "admin:changeme" "https://localhost:9200/" ``` :::{{tip}} -The related API requests need to be directed to the local node(s) where `file` has been configured rather than to any cluster-level load balancer or proxy URL. +The related API requests need to be directed to the local nodes where `file` has been configured, rather than to any cluster-level load balancer or proxy URL. ::: -You can confirm desired `superduperuser` role is applied to your `admin` username with [Authenticate a user API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-authenticate) +You can confirm that the desired `superduperuser` role is applied to your `admin` username using the [Authenticate a user API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-authenticate): ```bash curl -X GET -sk -u "admin:changeme" "https://localhost:9200/_security/_authenticate?pretty=true" ``` -Now that you have regained recovery access to the cluster you can investigate and recover the {{stack}} {{security-features}} as needed. \ No newline at end of file +Now that you have regained recovery access to the cluster, you can investigate and recover the {{stack}} {{security-features}} as needed. \ No newline at end of file From 9b2f1f4016bd6469c155308b759d1894de42e9cb Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Fri, 19 Sep 2025 14:27:30 -0400 Subject: [PATCH 09/10] fix links --- troubleshoot/elasticsearch/file-based-recovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index 6e2dd3c56e..6c78871f03 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -49,11 +49,11 @@ The `file` realm reads its files upon the local node's initial startup and as pe Before granting a `file` realm user any roles, you need to ensure that those desired roles exist. You can use the following types of roles: -* [Built-in roles](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md) +* [Built-in roles](elasticsearch://reference/elasticsearch/roles.md) * [Custom roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) defined under the {{stack}} {{security-features}} * Roles defined in [`roles.yml`](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md#roles-management-file) -{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md#roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). +{{es}} recommends following the industry's [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when granting user permissions. {{es}} follows this guidance itself by [restricting system indices](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-indices-priv) by default, even from [`superuser` role](elasticsearch://reference/elasticsearch/roles.md#available-roles) administrators including the [`elastic` built-in user](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-users.md). The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). When recovering {{stack}} {{security-features}}, you will likely need to temporarily define a custom role with the [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. From cbca6149c7d834e9a195c805a4e7231772f0a1a0 Mon Sep 17 00:00:00 2001 From: Stef Nestor <26751266+stefnestor@users.noreply.github.com> Date: Fri, 26 Sep 2025 08:32:15 -0600 Subject: [PATCH 10/10] fe Co-authored-by: Tim Vernum --- .../users-roles/cluster-or-deployment-auth/file-based.md | 2 +- troubleshoot/elasticsearch/file-based-recovery.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md index 2302c7c689..ddba35c3b0 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/file-based.md @@ -43,7 +43,7 @@ You don’t need to explicitly configure a `file` realm. The `file` and `native` Because `resource.reload.interval.high` is a common setting in {{es}}, changing its value may effect other schedules in the system. ::: -3. In self-managed deployments, if of these settings is modified, perform a [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) of the {{es}} nodes for your changes to take effect. +3. In self-managed deployments, if either of these settings is modified, perform a [rolling restart](/deploy-manage/maintenance/start-stop-services/full-cluster-restart-rolling-restart-procedures.md#restart-cluster-rolling) of the {{es}} nodes for your changes to take effect. In {{eck}}, changes are automatically propagated. diff --git a/troubleshoot/elasticsearch/file-based-recovery.md b/troubleshoot/elasticsearch/file-based-recovery.md index 6c78871f03..56a0d6656a 100644 --- a/troubleshoot/elasticsearch/file-based-recovery.md +++ b/troubleshoot/elasticsearch/file-based-recovery.md @@ -38,7 +38,7 @@ You don’t need to explicitly configure a `file` realm. The `file` and `native` To learn how to override the default `file` realm configuration, refer to [Configure a file realm](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#file-realm-configuration). -The `file` realm reads its files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. Its files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain the following information: +{{es}} reads security-related files upon the local node's initial startup and as periodically refreshed based on the `resource.reload.interval.high` setting. You do not need to restart nodes for changes to take effect. These files are located under the [`ES_PATH_CONF` directory](/deploy-manage/deploy/self-managed/configure-elasticsearch.md#config-files-location) and contain the following information: * `roles.yml` for [defining roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md) * `role_mapping.yml` for [mapping external users and groups to roles](/deploy-manage/users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md) @@ -57,7 +57,7 @@ Before granting a `file` realm user any roles, you need to ensure that those des The main {{stack}} {{security-features}} rely on the `security` [feature state](/deploy-manage/tools/snapshot-and-restore.md) which is mostly composed of the `.security*` [system indices](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#system-indices). When recovering {{stack}} {{security-features}}, you will likely need to temporarily define a custom role with the [`allow_restricted_indices` setting](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role) enabled. -For example, to grant all of the privileges of `superuser` role alongside `allow_restricted_indices: true` you can create a new role called `superduperuser` with the following definition: +For example, to grant the administrative privileges of `superuser` role alongside `allow_restricted_indices: true` you can create a new role called `superduperuser` with the following definition: ```yaml superduperuser: