> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Elasticsearch

> Connect an Elasticsearch cluster so Oleria can discover users, roles, role mappings, API keys, service accounts, and index access, and ingest the security audit log.

Connect Elasticsearch to Oleria to see who can read, write, or administer which indices and data streams, and the cluster itself, through which roles. Oleria also inventories every API key and service token with its owner, scope, expiry, and last use, and ingests the security audit log as activity. The integration works with Elastic Cloud Hosted and self-managed clusters.

## What Oleria discovers

* **Users** - native and reserved users, plus users from any other realm (SAML, OIDC, LDAP, Active Directory, file, JWT, PKI) who have a Kibana user profile or appear in the audit log. Oleria derives MFA, SSO, and authentication method from each user's realm.
* **Roles** - built-in and custom roles, the roles each user holds, and the cluster privileges each role grants.
* **Impersonation** - for each role with run-as privileges, the users its holders can submit requests as. A role that can run as any user (`run_as: ["*"]`) is noted in its description instead of being linked to every user.
* **Role mappings as groups** - each role mapping appears as a dynamic group, with its rules in the description and the roles it grants.
* **Resources** - the cluster, indices, and data streams, and the access each role grants to them, including document-level and field-level security. API keys created with their own role descriptors also show the cluster, index, and data stream access those descriptors grant; an API key without role descriptors inherits its owner's access. System indices, Elastic's own hidden indices and data streams (such as `.security-*` and `.kibana*`), data-stream backing indices, and aliases are not listed; hidden indices you create are.
* **Non-human identities** - service accounts, API keys (as personal access tokens when a person owns them, or API tokens when a service account or Elastic owns them), and service account tokens (as API tokens). Cross-cluster API keys, which a remote cluster holds to search or replicate your indices, appear as external API tokens with the access they grant. Each key and token appears as a credential with its owner, status, scope, creation date, expiry, and last use.
* **Activity** - authentications, access denials, run-as, user and role changes, password changes, and API key and service token creation and revocation, from the Elasticsearch security audit log.

## Prerequisites

* An Elasticsearch user who can create roles and API keys (for example, a user with the `superuser` role), to create Oleria's connector credential.
* The cluster's Elasticsearch endpoint URL. Elastic Cloud Hosted endpoints (`.cloud.es.io`, `.found.io`, `.elastic-cloud.com`) work as is. A self-managed cluster must be reachable from the public internet over HTTPS.
* Optional: an Elastic subscription that includes security audit logging, with auditing enabled, for activity. See [Enable audit logging](#enable-audit-logging).
* Admin access on the Oleria platform to add a new integration.

<Note>Standard integrations are configured with read-only permissions. Write privileges are needed only if you want Oleria to run remediation actions.</Note>

## Create the Oleria role

In Kibana, go to **Dev Tools** -> **Console** and run the following request as an administrator. It creates a role with the privileges Oleria needs. Oleria checks the cluster privileges and audit-index read access when you connect.

```json theme={null}
PUT /_security/role/oleria_connector
{
  "cluster": ["read_security", "monitor"],
  "indices": [
    {
      "names": ["elastic-cloud-logs-*", "logs-elasticsearch.audit-*", "filebeat-*"],
      "privileges": ["read", "view_index_metadata"]
    },
    {
      "names": ["*"],
      "privileges": ["view_index_metadata"]
    }
  ]
}
```

| Privilege | Required | Used for |
| - | - | - |
| `read_security` (cluster) | Yes | Reading users, user profiles, roles, role mappings, API keys, and service accounts. |
| `monitor` (cluster) | Yes | Reading the realm list (user IDs, MFA, and SSO) and the cluster's indices. |
| `read` on the audit indices | No | Activity, last activity, and API key last use. If you change the audit log index pattern, change these index names to match. |
| `view_index_metadata` on `*` | No | Listing indices and data streams. |

Oleria refuses the connection if `read_security` or `monitor` is missing. If the credential can't read the audit indices, Oleria still connects, but activity, last activity, and API key last use stay empty. Oleria doesn't show a warning, so check that activity appears after the first sync.

### Add privileges for remediation actions

To let Oleria run [remediation actions](#remediation-actions), add these cluster privileges to the `cluster` list. Each is required for actions only.

| Privilege | Required for actions |
| - | - |
| `manage_security` | Create, delete, disable, and enable native users; add to and remove from roles; remove a remote cluster's access. |
| `manage_token` | Revoke a user's sessions. Included in `manage_security`. |
| `manage_api_key` | Invalidate API keys owned by other users. Invalidating a cross-cluster API key also needs `manage_security`. |
| `manage_service_account` | Delete service account tokens. |

To remove a remote cluster's access, the connector role also needs `run_as` on the owners of your cross-cluster API keys, because Elasticsearch lets only a key's owner change it. Add those usernames to the role's `run_as` list, and to the `run_as` list of the API key's role descriptor if you restricted the key.

```json theme={null}
"cluster": ["read_security", "monitor", "manage_security", "manage_token", "manage_api_key", "manage_service_account"]
```

## Create the credential

Choose one of the three authentication methods. An API key is recommended.

<Tabs>
  <Tab title="API key (recommended)">
    Create a dedicated user that holds the `oleria_connector` role, then grant an API key to that user. Run as an administrator:

    ```json theme={null}
    POST /_security/user/oleria-connector
    {
      "password": "<a strong password>",
      "roles": ["oleria_connector"]
    }

    POST /_security/api_key/grant
    {
      "grant_type": "password",
      "username": "oleria-connector",
      "password": "<the same password>",
      "api_key": { "name": "oleria-connector" }
    }
    ```

    Copy the `encoded` value from the response. Oleria also accepts the key as `id:api_key`.

    Alternatively, sign in as a user who already holds the privileges and create a key restricted to them:

    ```json theme={null}
    POST /_security/api_key
    {
      "name": "oleria-connector",
      "role_descriptors": {
        "oleria_connector": {
          "cluster": ["read_security", "monitor"],
          "indices": [
            {
              "names": ["elastic-cloud-logs-*", "logs-elasticsearch.audit-*", "filebeat-*"],
              "privileges": ["read", "view_index_metadata"]
            },
            {
              "names": ["*"],
              "privileges": ["view_index_metadata"]
            }
          ]
        }
      }
    }
    ```

    An API key's privileges can never exceed its owner's. For remediation actions, add the action privileges, and the `run_as` list described in [Add privileges for remediation actions](#add-privileges-for-remediation-actions), to both the owner and the key's role descriptor.
  </Tab>

  <Tab title="Basic">
    Create a dedicated native user that holds the `oleria_connector` role:

    ```json theme={null}
    POST /_security/user/oleria-connector
    {
      "password": "<a strong password>",
      "roles": ["oleria_connector"]
    }
    ```

    You can also use a user from the file, LDAP, or Active Directory realm that holds the role.
  </Tab>

  <Tab title="Bearer token">
    Use a long-lived bearer token for a principal that holds the `oleria_connector` privileges. Oleria sends only the `Authorization: Bearer` header and doesn't refresh tokens, so:

    * Don't use token-service access tokens: they expire after 20 minutes by default.
    * A JWT works only from a JWT realm that doesn't require client authentication (`client_authentication.type: none`), because Oleria doesn't send the `ES-Client-Authentication` header, and only while the JWT is valid.

    For most clusters, an API key is simpler.

    <Warning>Built-in Elasticsearch service account tokens (for example, `elastic/kibana`) do not have the `read_security` privilege. Oleria refuses them when you connect. Use an API key or a user instead.</Warning>
  </Tab>
</Tabs>

## Enable audit logging

Activity requires security auditing, which is available only on Elastic subscriptions that include audit logging (see [Elastic subscriptions](https://www.elastic.co/subscriptions)). Skip this section if you do not need activity.

<Tabs>
  <Tab title="Elastic Cloud">
    1. In the Elastic Cloud console, find your deployment, select **Manage**, then open **Edit**.
    2. Turn on logs and metrics shipping, and select **this deployment** as the destination. Oleria reads audit logs only from the cluster it's connected to.
    3. In the **Elasticsearch** section, select **Manage user settings and extensions**, add `xpack.security.audit.enabled: true`, and select **Save changes**.

    Elastic Cloud ships the audit log to the destination deployment's `elastic-cloud-logs-*` indices. If logs ship to a separate monitoring deployment, Oleria can't read them.
  </Tab>

  <Tab title="Self-managed">
    1. Add `xpack.security.audit.enabled: true` to `elasticsearch.yml` on every node and restart the nodes.
    2. Ship the audit log into the cluster with the Filebeat `elasticsearch` module (audit fileset), which writes to `filebeat-*`, or with the Elastic Agent Elasticsearch integration, which writes to `logs-elasticsearch.audit-*`.
  </Tab>
</Tabs>

## Connect Elasticsearch to Oleria

<Steps>
  <Step title="Open the Elasticsearch integration">
    Go to your Oleria workspace, select **Integrations** -> select **Elasticsearch**.
  </Step>

  <Step title="Enter the connection details">
    Select **Continue** and provide the following:

    * **Elasticsearch URL** - the cluster's Elasticsearch endpoint, for example `https://my-deployment.es.us-central1.gcp.cloud.es.io`.
    * **Authentication method** - **API key** (recommended), **Basic**, or **Bearer token**.
    * **API key** - the encoded key, when you choose API key.
    * **Username** and **Password** - when you choose Basic.
    * **Bearer token** - when you choose Bearer token.
    * **Audit log index pattern** (optional) - a comma-separated list of indices that hold the audit log. Defaults to `elastic-cloud-logs-*,logs-elasticsearch.audit-*,filebeat-*`.
    * **Kibana URL** (optional) - your Kibana address. When set, each index and data stream in Oleria links to its Kibana index management page.
  </Step>

  <Step title="Confirm the connection">
    Select **Authenticate**. Oleria checks that the credential reaches the cluster and holds the required privileges before saving the integration.
  </Step>
</Steps>

<Note>Each cluster can be connected once. To connect a different cluster, add a new integration instead of changing the URL.</Note>

## Verify the integration

Confirm the Elasticsearch instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered users, roles, role mappings, non-human identities, and index access in your Oleria workspace.

## Remediation actions

Oleria can take the following actions in Elasticsearch. Each needs the privilege listed in [Add privileges for remediation actions](#add-privileges-for-remediation-actions).

| Action | Applies to | Required privilege | Revertible |
| - | - | - | - |
| **Disable a user account** | Native realm users | `manage_security` | Yes |
| **Enable a user account** | Native realm users | `manage_security` | Yes |
| **Add a user to a role** | Native realm users | `manage_security` | Yes |
| **Remove a user from a role** | Native realm users | `manage_security` | Yes |
| **Create a user** | Native realm | `manage_security` | Yes - the user is deleted, only if Oleria created it |
| **Delete a user** | Native realm users | `manage_security` | No - Elasticsearch cannot restore a deleted user |
| **Revoke user sessions** | Users from any realm except reserved users | `manage_token` | No - the user signs in again |
| **Disable a non-human identity** (API key) | API keys | `manage_api_key` (plus `manage_security` for a cross-cluster API key) | No - the key is invalidated |
| **Disable a non-human identity** (service token) | Service account tokens stored in the cluster | `manage_service_account` | No - the token is deleted |
| **Remove external access** | A cross-cluster API key's access to one index or data stream | `manage_security` and `run_as` on the key's owner | Yes - the index or data stream is added back to the key's access; changes made to the key since are kept |

Disabling or deleting a user from Oleria doesn't invalidate the API keys they own. To stop a leaver's keys, use **Disable a non-human identity** on each key.

**Create a user** creates a native user with no roles, disabled unless you choose to activate it. Groups chosen in the action aren't applied: Elasticsearch groups are role mappings, which grant roles by rule and have no members. Add roles with **Add a user to a role**. Oleria refuses a username that already exists. When Oleria generates the password, it is used once and never stored, logged, or shown; set a new one in Kibana or sign the user in through SSO.

**Revoke user sessions** invalidates the user's access and refresh tokens, which ends their SSO (SAML or OIDC) Kibana sessions. A Kibana session signed in with a username and password lasts until it expires. The action doesn't invalidate the user's API keys; use **Disable a non-human identity** for those.

**Remove external access** removes the index or data stream name from every search and replication entry of a cross-cluster API key that lists it by exact name. If the key grants access through a wildcard or regular-expression pattern that also matches that name, Oleria refuses rather than narrowing a pattern that covers other indices; edit the key in Elasticsearch. Oleria also refuses to remove the key's last grant (disable the key instead).

Oleria does not revoke a role's access to an index or data stream: Elasticsearch grants index access through roles that many users share, so changing a role would remove the access from all of them. To remove one user's access, remove the user from the role.

Oleria does not run actions on reserved built-in users, on users from other realms (except **Revoke user sessions**, which works for any realm; manage them in their directory or identity provider), or on the connection's own user, API key, or token. Service accounts themselves cannot be disabled; disable their tokens instead. File-based service tokens and API keys owned by service accounts or managed by Elastic cannot be disabled through Oleria.

## Known limitations

* **Authentication methods** - PKI client certificates, Kerberos, SAML, and OIDC cannot be used to connect. Users from these realms are still discovered.
* **Anonymous access** - roles granted to anonymous users are a node setting that the API does not expose, so Oleria does not show them.
* **File-based roles** - roles defined in a self-managed node's `roles.yml` are not returned by the Elasticsearch role API, so Oleria does not show them.
* **Role mapping membership** - Elasticsearch does not record which users match a role mapping rule, so groups have no members. The roles a mapping grants still appear on each user who has signed in.
* **Network access** - self-managed clusters must be reachable from the public internet. Clusters on private networks are not supported.
* **Audit logging** - activity requires an Elastic subscription that includes audit logging, with auditing enabled and shipped to an index in the connected cluster. On Elastic Cloud Hosted, audit logs that ship to a separate monitoring deployment can't be read.
* **Elastic Cloud Serverless** - Serverless projects aren't supported yet. They have no native users and no user-configurable audit logging.

## Remove the integration

After you remove the Elasticsearch integration from Oleria, invalidate the API key and delete the user and role you created:

```json theme={null}
DELETE /_security/api_key
{ "name": "oleria-connector" }

DELETE /_security/user/oleria-connector

DELETE /_security/role/oleria_connector
```

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.