Defining roles

ECE ECK Elastic Cloud Hosted Self Managed

If built-in roles do not address your use case, then you can create additional custom roles.

In this section, you'll learn about the data structure of a role, and about the methods for defining and managing custom roles.

You can also implement custom roles providers. If you need to integrate with another system to retrieve user roles, you can build a custom roles provider plugin. For more information, see Authorization plugins.

After you create your custom roles, you can learn how to assign them to users.

Custom roles follow a strict data structure. If you're working with custom roles using the role management API or role files, then you need to understand and follow the structure when parsing role information or making changes.

Learn about the data structure of a role and its entries.

You can manage custom roles using the following methods:

• Using the Kibana role management UI
• Using role management APIs
• Using local files.

When you use the UI or APIs to manage roles, the roles are stored in an internal Elasticsearch index. When you use local files, the roles are only stored in those files.

You can manage users and roles easily in Kibana.

To manage roles, log in to Kibana and go to Management > Security > Roles.

Learn more about using the role management UI.

The Role Management APIs enable you to add, update, remove and retrieve roles dynamically. For more information and examples, see Roles.

ECK Self Managed

Roles can also be defined in local roles.yml file. This is a YAML file where each role definition is keyed by its name.

While role management APIs and the role management UI are the preferred mechanism to define roles, using the roles.yml file becomes useful if you want to define fixed roles that no one, beside an administrator having access to the Elasticsearch nodes or Kubernetes cluster, would be able to change. However, the roles.yml file is provided as a minimal administrative function and is not intended to cover and be used to define roles for all use cases.

The following snippet shows an example of the roles.yml file configuration, specifying one role named click_admins:

click_admins:
  run_as: [ 'clicks_watcher_1' ]
  cluster: [ 'monitor' ]
  indices:
    - names: [ 'events-*' ]
      privileges: [ 'read' ]
      field_security:
        grant: ['category', '@timestamp', 'message' ]
      query: '{"match": {"category": "click"}}'

To configure file-based role management:

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

kind: Secret
apiVersion: v1
metadata:
  name: my-roles-secret
stringData:
  roles.yml: |-
    click_admins:
      run_as: [ 'clicks_watcher_1' ]
      cluster: [ 'monitor' ]
      indices:
      - names: [ 'events-*' ]
        privileges: [ 'read' ]
        field_security:
          grant: ['category', '@timestamp', 'message' ]
        query: '{"match": {"category": "click"}}'