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

# OpenSearch

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

Connect OpenSearch to Oleria to see who holds which security roles, directly or through backend roles, and which roles grant administrative access. Oleria also inventories service accounts, API keys, and ML Commons connector secrets as non-human identities, and ingests the security audit log as activity. The integration works with self-managed clusters that run the Security plugin and with Amazon OpenSearch Service domains that use fine-grained access control.

## What Oleria discovers

* **Users** - internal users, plus users from LDAP, SAML, OpenID Connect, JWT, and client certificates who appear in the audit log in the last 90 days. Oleria derives the authentication method, MFA, and SSO from how each user signs in.
* **Roles** - built-in and custom security roles, with the cluster permissions, index patterns, and tenant patterns each role grants in its description. Roles that grant full cluster or security administration are marked as admin roles.
* **Backend roles as groups** - each backend role appears as a group, with the internal users who hold it and the roles its role mappings grant. A role mapping that requires several backend roles together appears as a dynamic group.
* **Role memberships** - roles granted to a user directly, by name in a role mapping (including wildcard patterns), or through a backend role.
* **Non-human identities** - service accounts, the `kibanaserver` system user, API keys (OpenSearch 3.7 and later, shown in Oleria as API tokens) with their scope, creator, expiry, and last use, ML Commons connectors that hold a stored secret, and client certificates that appear in the audit log. Each API key, connector secret, and certificate appears as a credential.
* **Activity** - successful and failed logins, access denials, security configuration changes (users, roles, role mappings, action groups, settings), API token creation and revocation, and index and document changes, from the security audit log.

## Prerequisites

* An OpenSearch administrator who can create roles and users (for example, a user with the `all_access` role), to create Oleria's connector user.
* The cluster's HTTPS endpoint. A self-managed cluster must be reachable from the public internet over HTTPS. Amazon OpenSearch Service domain endpoints (`.es.amazonaws.com`) work as is.
* For a self-managed cluster, access to `opensearch.yml` on every node, to give the connector Security REST API access.
* For Amazon OpenSearch Service, a domain with fine-grained access control and the internal user database enabled (a master user created with a username and password, not an IAM ARN), and an access policy that doesn't require signed requests.
* Optional: audit logging written to an index in the connected cluster, for activity. See [Enable audit logging](#enable-audit-logging).
* Admin access on the Oleria platform to add a new integration.

## Create the Oleria role and user

In OpenSearch Dashboards, go to **Dev Tools** and run the following requests as an administrator. They create a role with the permissions Oleria needs and an internal user that holds it.

```json theme={null}
PUT _plugins/_security/api/roles/oleria_connector
{
  "cluster_permissions": [
    "cluster_monitor",
    "cluster:admin/opensearch/ml/connectors/search"
  ],
  "index_permissions": [
    {
      "index_patterns": ["security-auditlog-*"],
      "allowed_actions": ["read"]
    }
  ]
}

PUT _plugins/_security/api/internalusers/oleria-connector
{
  "password": "<a strong password>",
  "opendistro_security_roles": ["oleria_connector"]
}
```

| Permission | Required | Used for |
| - | - | - |
| Security REST API access | Yes | Reading internal users, roles, role mappings, action groups, API keys, and the authentication configuration. See [Give the connector Security REST API access](#give-the-connector-security-rest-api-access). |
| `cluster_monitor` | Yes | Reading the cluster name and ID. |
| `read` on the audit indices | No | Activity, users from external directories, and last activity. If you change the audit log index pattern, change the index pattern here to match. |
| `cluster:admin/opensearch/ml/connectors/search` | No | ML Commons connector secrets. |

Oleria refuses the connection if the user can't use the Security REST API, or if `GET` is disabled for it on the internal users, roles, role mappings, or action groups endpoints. If the user can't read the audit indices, Oleria still connects, but activity, last activity, and users from external directories stay empty.

## Give the connector Security REST API access

**Self-managed**

The Security REST API is open only to the roles listed in `plugins.security.restapi.roles_enabled` in `opensearch.yml`. Add `oleria_connector` to that list on every node, keeping the roles already listed, and disable the write methods for it so the connector stays read-only. Then restart the nodes.

```yaml theme={null}
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "oleria_connector"]
plugins.security.restapi.endpoints_disabled.oleria_connector.INTERNALUSERS: ["PUT", "PATCH", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.ROLES: ["PUT", "PATCH", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.ROLESMAPPING: ["PUT", "PATCH", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.ACTIONGROUPS: ["PUT", "PATCH", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.TENANTS: ["PUT", "PATCH", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.APITOKENS: ["POST", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.AUDIT: ["PUT", "PATCH"]
plugins.security.restapi.endpoints_disabled.oleria_connector.CONFIG: ["PUT", "PATCH"]
plugins.security.restapi.endpoints_disabled.oleria_connector.NODESDN: ["PUT", "PATCH", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.ALLOWLIST: ["PUT", "PATCH"]
plugins.security.restapi.endpoints_disabled.oleria_connector.AUTHTOKEN: ["POST"]
plugins.security.restapi.endpoints_disabled.oleria_connector.ROLLBACK_VERSION: ["POST"]
plugins.security.restapi.endpoints_disabled.oleria_connector.RATELIMITERS: ["PUT", "DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.CACHE: ["DELETE"]
plugins.security.restapi.endpoints_disabled.oleria_connector.RESOURCE_SHARING: ["POST"]
```

A node that doesn't know an endpoint name (for example `APITOKENS` before 3.7) logs it and skips it, so the block is safe on any 2.x or 3.x node.

These settings apply only to `oleria_connector`, not to your other administrators. To let Oleria run [remediation actions](#remediation-actions), remove the methods each action needs from the `INTERNALUSERS`, `ROLESMAPPING`, and `APITOKENS` lines. See [API permissions](https://docs.opensearch.org/latest/security/access-control/api/) in the OpenSearch documentation.

> [!WARNING]
>
> With those methods enabled, the connector can change any non-reserved internal user, including its own roles. Enable only the methods for the actions you plan to use.

**Amazon OpenSearch Service**

Amazon OpenSearch Service doesn't let you change `opensearch.yml`. Map the connector user to `security_manager`, the role AWS provides for Security plugin management: in OpenSearch Dashboards, go to **Security** -> **Roles** -> `security_manager` -> **Mapped users** -> **Manage mapping**, add `oleria-connector`, and select **Map**.

> [!WARNING]
>
> On Amazon OpenSearch Service the connector can't be restricted to read-only: `security_manager` can change users, roles, and role mappings.

## Enable audit logging

Activity requires the Security plugin's audit log, written to an index in the connected cluster. Skip this section if you do not need activity.

1. In `opensearch.yml` on every node, set `plugins.security.audit.type: internal_opensearch` and restart the nodes. The audit log is written to `security-auditlog-YYYY.MM.dd` indices.
2. In OpenSearch Dashboards, go to **Security** -> **Audit logs** and enable REST and transport auditing. By default, `AUTHENTICATED` and `GRANTED_PRIVILEGES` events aren't recorded; enable them to see successful logins and access.
3. To record security configuration changes, enable compliance auditing for internal config writes.

If you write the audit log to a different index, enter that pattern in Oleria. See [Audit logs](https://docs.opensearch.org/latest/security/audit-logs/index/) in the OpenSearch documentation.

## Connect OpenSearch to Oleria

**1. Open the OpenSearch integration**

Go to your Oleria workspace, select **Integrations** -> select **OpenSearch**.

**2. Enter the connection details**

Select **Continue** and provide the following:

* **Cluster URL** - the cluster's HTTPS endpoint, for example `https://opensearch.example.com:9200`.
* **Authentication method** - **Username and password** (recommended) or **Bearer token**.
* **Username** and **Password** - the connector user, when you choose Username and password.
* **Bearer token** - a JWT that the cluster's `jwt` or `openid` authentication domain accepts, when you choose Bearer token. Oleria doesn't refresh tokens, so use a long-lived JWT. OpenSearch API keys can't be used, because they can't read the Security REST API.
* **Audit log index pattern** (optional) - a comma-separated list of index patterns that hold the audit log. Defaults to `security-auditlog-*`.

**3. Confirm the connection**

Select **Authenticate**. Oleria checks that the credential reaches the cluster and can read the Security REST API before saving the integration.

> [!NOTE]
>
> Each cluster can be connected once. To connect a different cluster, add a new integration instead of changing the URL.

## Verify the integration

Confirm the OpenSearch 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, backend roles, and non-human identities in your Oleria workspace.

## Remediation actions

Oleria can take the following actions in OpenSearch. Each needs the Security REST API access described in [Give the connector Security REST API access](#give-the-connector-security-rest-api-access), with the listed endpoints and methods not disabled.

| Action | Applies to | Required endpoints | Revertible |
| - | - | - | - |
| **Create a user** | Internal users | `INTERNALUSERS` `GET`, `PUT` | Yes - the user is deleted, only if Oleria created it |
| **Delete a user** | Internal users | `INTERNALUSERS` `GET`, `DELETE`, `ROLESMAPPING` `GET`, `PATCH` | No - OpenSearch cannot restore a deleted user |
| **Add a user to a role** | Internal users, and users from external directories through the role mapping | `ROLES` `GET`, `INTERNALUSERS` `GET`, `PATCH`, `ROLESMAPPING` `GET`, `PATCH` | Yes |
| **Remove a user from a role** | Internal users, and users named in a role mapping | `ROLES` `GET`, `INTERNALUSERS` `GET`, `PATCH`, `ROLESMAPPING` `GET`, `PATCH` | Yes |
| **Add a user to a group** | Internal users (backend roles) | `INTERNALUSERS` `GET`, `PATCH` | Yes |
| **Remove a user from a group** | Internal users (backend roles) | `INTERNALUSERS` `GET`, `PATCH` | Yes |
| **Disable a non-human identity** (service account) | Service accounts | `INTERNALUSERS` `GET`, `PATCH` | Yes - the service account is enabled again |
| **Disable a non-human identity** (API token) | API keys | `APITOKENS` `GET`, `DELETE` | No - the token is revoked |

**Create a user** creates an internal user with no security roles. Groups chosen in the action are added as backend roles. Add roles with **Add a user to a role**. Oleria refuses a username that already exists. Enter a password or choose **Generate password**. When Oleria generates the password, it is used once and never stored, logged, or shown.

**Delete a user** also removes the username from every role mapping that names it, so a later user with the same name doesn't get its roles. If a mapping can't be updated, the action reports each mapping that still names the user. Remove the name from those mappings in OpenSearch.

**Add a user to a role** adds the role to an internal user's own roles. For a user from an external directory, Oleria adds the username to the role's role mapping, which must already exist. **Remove a user from a role** removes the role from the user's own roles and the username from the role mapping. If the user also holds the role through a backend role (by name or by a wildcard pattern), a rule that requires several backend roles together, or a wildcard user pattern in the role mapping, Oleria refuses rather than changing a rule that covers other users; change the role mapping in OpenSearch. For a user from an external directory, Oleria also refuses when the role mapping grants the role through backend roles, because it can't read that user's backend roles.

Oleria does not run actions on reserved, hidden, or static users, on the `kibanaserver` user, or on reserved role mappings. It doesn't delete the connection's own user, remove its roles or groups, or revoke its token. Oleria can't disable or enable a user, or end a user's sessions, because OpenSearch has no API for either. ML Commons connector secrets and client certificates can't be disabled through Oleria.

## Known limitations

* **Authentication methods** - AWS IAM (SigV4), SAML, Kerberos, proxy authentication, client certificates, and OpenSearch API keys cannot be used to connect. An OpenID Connect token works only as a bearer token, and only while it is valid, because Oleria doesn't refresh it. Users from these backends are still discovered from the audit log.
* **Amazon OpenSearch Service** - domains with an IAM master user, or with an access policy that requires signed requests, reject username-and-password sign-in, so they can't be connected. On other domains the connector needs `security_manager`, which can't be restricted to read-only.
* **Users from external directories** - users who sign in through LDAP, SAML, OpenID Connect, or JWT are discovered only once they appear in the audit log, and their backend roles are not listed.
* **Impersonation** - impersonation rules are set in `opensearch.yml` and can't be read through the API. Impersonated requests appear in activity.
* **Super-admin certificates** - the admin certificate DNs in `opensearch.yml` can't be read through the API, so a super-admin certificate appears as a non-admin certificate unless the audit log marks it as admin.
* **Last password change** - not reported. The audit log records changes to internal users without naming the changed user.
* **Network access** - self-managed clusters must be reachable from the public internet. Clusters on private networks are not supported.
* **Audit logging** - activity requires the audit log in an index of the connected cluster. Amazon OpenSearch Service publishes audit logs to CloudWatch Logs, so activity isn't available for those domains. If reading the audit log fails for another reason, such as a timeout, roles and groups still sync, while users, API keys, and role memberships keep their previous data until the next successful sync.
* **OpenSearch versions before 2.4** - activity isn't collected, because Oleria reads the audit log with point-in-time search, which OpenSearch added in 2.4. Users, roles, and groups are still discovered. API keys require OpenSearch 3.7 or later, with API keys enabled in the security configuration.
* **OpenSearch Serverless** - Serverless collections aren't supported. They don't run the Security plugin.

## Remove the integration

After you remove the OpenSearch integration from Oleria, delete the user and role you created:

```json theme={null}
DELETE _plugins/_security/api/internalusers/oleria-connector

DELETE _plugins/_security/api/roles/oleria_connector
```

Then remove the Security REST API access, so no future principal named `oleria-connector` inherits it:

* **Self-managed** - remove `oleria_connector` from `plugins.security.restapi.roles_enabled`, delete its `endpoints_disabled` lines in `opensearch.yml` on every node, and restart the nodes.
* **Amazon OpenSearch Service** - in OpenSearch Dashboards, go to **Security** -> **Roles** -> `security_manager` -> **Mapped users** -> **Manage mapping**, and remove `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.