RousselTMLEARNING

Observability

Advanced OpenSearch security: authentication, roles and audit

Securing OpenSearch in depth: transport and API TLS, internal, LDAP, OpenID Connect and SAML authentication, roles and mappings, document- and field-level security, masking, console tenants, audit log and the securityadmin tool.

1. The security model #

Six steps for each request.

The path #

A secured request's path
Good to know : Requests are written in the OpenSearch Dashboards Dev Tools console format (GET _cluster/health). On the command line, the same request is curl -sk -u 'admin:Str0ng!Passw0rd-2026' https://localhost:9200/_cluster/health, with -H 'Content-Type: application/json' -d '…' when there is a body.

The files #

File (config/opensearch-security/)Content
config.ymlauthentication and authorization methods (basic, OIDC, SAML, LDAP)
internal_users.ymlinternal users and hashed passwords
roles.ymlroles and permissions
roles_mapping.ymlwho gets which role
action_groups.ymlreusable permission groups
tenants.ymlconsole spaces
allowlist.yml, audit.ymlallowed APIs, audit log

These files initialize the security index; afterwards, you change configuration through the REST API or the console, or reapply the files with securityadmin.sh.

2. TLS #

Two layers to encrypt.

Transport and REST #

LayerPortRequired?
Transport (between nodes)9300yes, with the security plugin
REST (clients)9200strongly advised
plugins.security.ssl.transport.pemcert_filepath: node1.pem
plugins.security.ssl.transport.pemkey_filepath: node1-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: node1.pem
plugins.security.ssl.http.pemkey_filepath: node1-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
plugins.security.nodes_dn:
  - "CN=node*.logs.example.com,OU=SRE,O=Exemple,C=FR"
plugins.security.authcz.admin_dn:
  - "CN=admin,OU=SRE,O=Exemple,C=FR"

nodes_dn says which certificates are cluster nodes; admin_dn designates the admin certificate used by securityadmin.sh. Start OpenSearch with DISABLE_INSTALL_DEMO_CONFIG=true so demo certificates are not reinstalled.

3. Authentication #

Who are you?

The methods #

MethodForNote
Internal userstechnical accounts (collectors, applications)hashed password (hash.sh)
OpenID Connecthuman SSO (Keycloak, Entra ID, Okta…)token groups → backend roles
SAMLconsole SSOmainly for OpenSearch Dashboards
LDAP / Active Directoryexisting directoryauthentication and groups
Client certificateservice to servicethe certificate DN becomes the user
config:
  dynamic:
    authc:
      basic_internal_auth_domain:
        order: 0
        http_enabled: true
        http_authenticator: {type: basic, challenge: false}
        authentication_backend: {type: intern}
      openid_auth_domain:
        order: 1
        http_enabled: true
        http_authenticator:
          type: openid
          challenge: false
          config:
            openid_connect_url: https://sso.example.com/realms/sre/.well-known/openid-configuration
            subject_key: preferred_username
            roles_key: groups
        authentication_backend: {type: noop}

4. Fine-grained authorization #

Roles, documents and fields.

Mappings #

Users, roles and mappings

A role with DLS, FLS and masking #

PUT _plugins/_security/api/roles/support_panier
{
  "cluster_permissions": ["cluster_composite_ops_ro"],
  "index_permissions": [{
    "index_patterns": ["logs-app-*"],
    "dls": "{\"term\": {\"service\": \"panier\"}}",
    "fls": ["~duree_ms"],
    "masked_fields": ["utilisateur"],
    "allowed_actions": ["read"]
  }]
}

PUT _plugins/_security/api/rolesmapping/support_panier
{"backend_roles": ["support"], "users": []}
OptionEffect
dlsonly cart service documents are visible
fls~duree_ms: all fields except duree_ms (without ~: allow list)
masked_fieldsvalue replaced by a hash: distinct users can still be counted
Best practice : Grant roles to backend roles (directory or SSO groups) rather than named users: people joining or leaving are then handled in the directory.

Console tenants #

Tenants separate console saved objects: Global (shared), Private (personal) and custom per-team tenants. A role grants read or write access to a tenant.

5. Auditing and administering #

Tracing and applying.

Audit log #

plugins.security.audit.type: internal_opensearch
plugins.security.audit.config.disabled_rest_categories: NONE
plugins.security.audit.config.disabled_transport_categories: GRANTED_PRIVILEGES

Events (failed logins, denied access, security changes) are written to security-auditlog-* indexes, to watch with a monitor. Compliance logging can also trace reads or changes of sensitive fields.

securityadmin.sh #

cd /usr/share/opensearch/plugins/opensearch-security/tools
./hash.sh -p 'Nouveau!MotDePasse-2026'          # hacher un mot de passe pour internal_users.yml
./securityadmin.sh -cd ../../../config/opensearch-security/ \
  -cacert ../../../config/root-ca.pem -cert ../../../config/admin.pem -key ../../../config/admin-key.pem -icl -nhnv
./securityadmin.sh -backup /tmp/secu-sauvegarde ...  # sauvegarder la configuration actuelle
Watch out : securityadmin.sh -cd replaces the whole security configuration with the files' content: changes made through the console or API and missing from the files are lost. Back up with -backup first.

Commands to know #

Commands to know
  • GET _plugins/_security/authinfo : who am I, which roles?
  • GET _plugins/_security/api/roles/<rôle> : role details
  • PUT _plugins/_security/api/rolesmapping/<rôle> : map a role
  • ./hash.sh -p <mot de passe> : hash a password
  • ./securityadmin.sh -cd <dossier> … : apply security files

Sources #

Checked in November 2026 (OpenSearch 3.x, Data Prepper 2.x): OpenSearch ships a minor release about every six weeks, check the release notes before relying on a detail.

Related articles

The OpenSearch cluster in depth: nodes, shards and replication

Understanding how an OpenSearch cluster works inside: node roles, cluster manager election, shard allocation,…

Full-text search in OpenSearch: analyzers and relevance

Mastering full-text search: inverted index, analyzers (including French), the _analyze API, match, multi_matc…

Advanced aggregations, PPL and SQL in OpenSearch

Analyzing data in OpenSearch: bucket, metric and pipeline aggregations, date histograms, approximate cardinal…

Keep learning

Support us

♥ SUPPORT US

Support RousselTM Learning

Courses, articles, labs and certificates stay free with no intrusive ads. A voluntary contribution, of any amount you choose, pays for hosting, lab environments and new content.

Contribute with PayPal Any amount · card or PayPal accountLearn more
QR code PayPal
Or scan this QR code with your phone

Thank you, every contribution counts!