File-based user authentication

ECK Self Managed

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.

You can configure only one file realm on Elasticsearch nodes.

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 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:

   xpack:
     security:
       authc:
         realms:
           file:
             file1:
               order: 0
   

2. If you're using a self-managed Elasticsearch cluster, optionally change how often the users and users_roles files are checked.

   By default, Elasticsearch 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 file.

   Warning

   Because resource.reload.interval.high is a common setting in Elasticsearch, changing its value may effect other schedules in the system.

3. Restart Elasticsearch.

   In Elastic Cloud on Kubernetes, this change is propagated automatically.

In a self-managed Elasticsearch 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. Both files are located in ES_PATH_CONF and are read on startup.

In an Elastic Cloud on Kubernetes deployment, you can pass file realm user information in two ways:

1. Using users and user_roles files, which are passed using file realm content secrets
2. Using Kubernetes basic authentication secrets

You can reference several secrets in the Elasticsearch specification. ECK aggregates their content into a single secret, mounted in every Elasticsearch Pod.

users and users_roles files contain all of the information about users in the file realm.

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.

rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=

The users_roles file stores the roles associated with the users. For example:

admin:rdeniro
power_user:alpacino,jacknich
user:jacknich

Each row maps a role to a comma-separated list of all the users that are associated with that role.

You can edit files and secrets that contain users and users_roles manually, or you can edit them using a tool.

Manually

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

kind: Secret
apiVersion: v1
metadata:
  name: my-filerealm-secret
stringData:
  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
    user:jacknich

Using a tool

To avoid editing these files manually, you can use the elasticsearch-users tool:

bin/elasticsearch-users useradd myuser -p mypassword -r monitoring_user

# 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

ECK

You can also add file-based authentication users using Kubernetes basic authentication secrets.

A basic authentication secret can optionally contain a roles entry. It must contain a comma separated list of roles to be associated with the user. The following example illustrates this combination:

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 make this file available to Elastic Cloud on Kubernetes by adding it as a file realm secret:

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