1. The security model #
Six steps for each request.
The 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 iscurl -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.yml | authentication and authorization methods (basic, OIDC, SAML, LDAP) |
| internal_users.yml | internal users and hashed passwords |
| roles.yml | roles and permissions |
| roles_mapping.yml | who gets which role |
| action_groups.yml | reusable permission groups |
| tenants.yml | console spaces |
| allowlist.yml, audit.yml | allowed 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 #
| Layer | Port | Required? |
|---|---|---|
| Transport (between nodes) | 9300 | yes, with the security plugin |
| REST (clients) | 9200 | strongly 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 #
| Method | For | Note |
|---|---|---|
| Internal users | technical accounts (collectors, applications) | hashed password (hash.sh) |
| OpenID Connect | human SSO (Keycloak, Entra ID, Okta…) | token groups → backend roles |
| SAML | console SSO | mainly for OpenSearch Dashboards |
| LDAP / Active Directory | existing directory | authentication and groups |
| Client certificate | service to service | the 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 #
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": []}| Option | Effect |
|---|---|
| dls | only cart service documents are visible |
| fls | ~duree_ms: all fields except duree_ms (without ~: allow list) |
| masked_fields | value 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_PRIVILEGESEvents (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 actuelleWatch out :securityadmin.sh -cdreplaces 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-backupfirst.
Commands to know #
Commands to know
GET _plugins/_security/authinfo: who am I, which roles?GET _plugins/_security/api/roles/<rôle>: role detailsPUT _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.
