File-based access recovery

ECK Self-Managed

The built-in file realm is commonly used as a fallback or recovery realm.

The main Elastic Stack security features rely on the security feature state which is mostly composed of the .security* 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 especially helpful for recovery scenarios where normal security mechanisms aren't accessible:

• Node services are running but cluster is unresponsive
• Elastic Stack security features are unavailable to the current node
• Elastic Stack security features are lost and need to be restored
• Administrative users' passwords are lost and need to be reset

The Elastic 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 Elasticsearch 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.

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.

To learn how to override the default file realm configuration, refer to Configure a file realm.

Elasticsearch 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 and contain the following information:

• roles.yml for defining roles
• role_mapping.yml for mapping external users and groups to roles
• users for user password-based authentication
• user_roles for user role-based authorization

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
• Custom roles defined under the Elastic Stack security features
• Roles defined in roles.yml

Elasticsearch recommends following the industry's principle of least privilege when granting user permissions. Elasticsearch follows this guidance itself by restricting system indices by default, even from superuser role administrators including the elastic built-in user.

The main Elastic Stack security features rely on the security feature state which is mostly composed of the .security* system indices. When recovering Elastic Stack security features, you will likely need to temporarily define a custom role with the allow_restricted_indices setting enabled.

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:

superduperuser:
  cluster: [ 'all' ]
  indices:
    - names: [ '*' ]
      privileges: [ 'all' ]
      allow_restricted_indices: true
		

After you decide on your role definitions, you can add your users and any custom roles to your local node's configuration.

For most administrators, Elasticsearch recommends that you use the elasticsearch-users tool, which compiles the users and users_roles files on your behalf.

In this example, we create an advanced administrative user with the superduperuser role we designed in the previous step.

bin/elasticsearch-users useradd admin -p changeme -r superduperuser
		

# 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.4 \
    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
		

apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: elasticsearch-sample
spec:
  version: 9.1.4
  auth:
    fileRealm:
    - secretName: my-filerealm-secret-1
    - secretName: my-filerealm-secret-2
  nodeSets:
  - name: default
    count: 1
		

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
		

At this point, the local Elasticsearch node will accept Elasticsearch API requests 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 from the node's local shell:

curl -X GET -sk -u "admin:changeme" "https://localhost:9200/"
		

You can confirm that the desired superduperuser role is applied to your admin username using the Authenticate a user API:

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 Elastic Stack security features as needed.