Skip to main content
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.
  • 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.
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

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.
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, remove the methods each action needs from the INTERNALUSERS, ROLESMAPPING, and APITOKENS lines. See API permissions in the OpenSearch documentation.
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.

​
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 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.
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, with the listed endpoints and methods not disabled. 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:
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.