Skip to content

Opendistro Guide


Opendistro Security for Elasticsearch is a plugin from Amazon that allows you to protect your data from users. By defining various fine-grained role-based access control rules with actions on indices, and binding users to roles, your able to provide data to allowed users only.


How it works

Opendistro Security architecture is compatible with a single Kibana instance for several users :

  • Each user is linked to a role
  • Each role is allowed to process actions on indices
  • Each role can be configured to filter queries on documents, but also on fields

Thus, each role has its own level of access to Elasticsearch data.

Furthermore, Opendistro Security provides a Kibana plugin for tenant-based access control for dashboard's data :

  • Each role can be linked to a tenant
  • Each tenant has permissions to read or write permissions on index patterns, visualizations and dashboards
  • Each tenant can be shared between multiple roles
  • Each role sharing a tenant can access to the same dashboards


Learn more about these feature by following our Getting Started guide on Opendistro Security

This tutorial explains how to add install Opendistro Security plugin for Elasticsearch and Kibana to your existing platform to protect your Elasticsearch cluter's data from external applications.

You need at least one server to host an Elasticsearch node, the same node or another one to host a Kibana instance, and a machine to deploy your node with Modsecurity.

How to deploy Opendistro Security

Configure Elasticsearch

Opendistro Security plugin comes with an existing Elasticsearch configuration in punchplatform-deployment.settings :

  "elasticsearch": {                                                                                                                  
    "elasticsearch_version": "7.8.0",                                                                                                 
    "clusters": {                                                                                                                     
      "es_search": {                                                                                                                  
        "nodes": {                                                                                                                    
          "server2": {                                                                                                                
            "http_api_address": "server2",                                                                                            
            "transport_address": "server2",                                                                                           
            "bind_address": "_eth1_",                                                                                                 
            "rack_id": "1"                                                                                                            
        "http_api_port": 9200,                                                                                                        
        "cluster_production_transport_address": "server2",                                                                            
        "transport_port": 9300,                                                                                                       
        "minimum_master_nodes": 1,                                                                                                    
        "settings_by_type": {                                                                                                         
          "data_node": {                                                                                                              
            "max_memory": "512m",                                                                                                     
            "modsecurity_enabled": false,                                                                                             
            "modsecurity_blocking_requests": false,                                                                                   
            "script_execution_authorized": true,                                                                                      
            "http_cors_enabled": true,                                                                                                
            "readonly": true                                                                                                          
        "plugins": {
          "opendistro_security": {                                 
            "opendistro_security_version": "",              
            "local_ssl_certs_dir": "/data/certs",
            "admin_pemkey_name": "admin-key.pem",
            "admin_pemcert_name": "admin-cert.pem",
            "admin_pemtrustedcas_name": "cachain.pem",
            "ssl_transport_pemkey_name": "node-key.pem",
            "ssl_transport_pemcert_name": "node-cert.pem",
            "ssl_transport_pemtrustedcas_name": "cachain.pem",
            "ssl_http_enabled": false,
            "ssl_http_pemkey_name": "server2-key.pem",
            "ssl_http_pemcert_name": "server2-cert.pem",
            "ssl_http_pemtrustedcas_name": "server2-cachain.pem",
            "authcz_admin_dn": [
            "nodes_dn": [
            "kibana_index": ".kibana-admin"


Opendistro Security needs at least one admin certificate for security configuration management and one node certificate for SSL transport layer. They MUST be different (by their dn configuration). Otherwise, Elasticsearch will not start properly because of Opendistro Security plugin.


Opendistro documentation provides a guide to generate proper certificates for Security plugin here We strongly recommand to follow their guide to install certificates compatible for production environments


To check more about configurations, visit our documentation about Opendistro Security plugin for Elasticsearch in punchplatform-deployment.settings and

Configure Kibana

Opendistro Security plugin comes with an existing Kibana configuration in punchplatform-deployment.settings :

  "kibana": {
    "kibana_version": "7.8.0",
    "domains": {
      "admin": {
        "es_cluster_target": "es_search",
        "es_type_of_nodes_targeted": "data_node",
        "kibana_port": 5601,
        "type": "administration", 
        "server_ssl_enabled": false,
        "local_ssl_certs_dir": "/home/lca/Projects/punch/punchbox/bin/../punch/resources/security/certs/kibana",
        "server_ssl_key_name": "kibana-server-key.pem",
        "server_ssl_certificate_name": "kibana-server-cert.pem",
        "elasticsearch_ssl_enabled": false,
        "elasticsearch_ssl_verificationMode": "none",
        "elasticsearch_ssl_certificateAuthorities_names": [
    "servers": {
      "server1": {
        "address": "server1"
    "plugins": {
      "opendistro_security": {
        "opendistro_security_version": ""


To check more about configurations, visit our documentation about Opendistro Security plugin for Kibana in punchplatform-deployment.settings and

Check and generate your configuration

First execute this command on your deployer machine :

$ --generate-inventory

This command generates a complete set of so-called inventories from your two configuration files.
If that succeeds, you can proceed.


From the deployer, make sure you can access your target server using ssh. Depending on your ssh configuration this may require a ssh password. Simply execute the following command : --deploy -Kk --tags elasticsearch --deploy -Kk --tags kibana

Check your deployment

Elasticsearch should be now protected by an authentication :

curl -v GET server1:9200/_cat/indices 

< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: Basic realm="Open Distro Security"
< content-type: text/plain; charset=UTF-8
< content-length: 12

The credentials are admin:admin by default :

curl -v GET server1:9200/_cat/indices -u admin:admin

< HTTP/1.1 200 OK
< content-type: text/plain; charset=UTF-8
< content-length: 172
green open .opendistro_security         qP3mkA9ZS_uzk3EPt5hqkg 1 0 6 0 25.3kb 25.3kb


For production deployement purposes, you MUST change the default credentials.
Follow the next section to properly configure the server protected by the plugin

Configure the server for a proper production environment

Connect to the server hosting the Elasticsearch node, and generate a new password for :

  • admin user
  • kibana server's user

To do that, use the security tools and update Opendistro config files :

cd /data/opt/elasticsearch-7.8.0/plugins/opendistro_security/tools
sudo chmod +x
sudo ./
> [Password:]

Type the new password for admin user, then copy the hashed result.
Execute the same procedure for kibana server's user.

Update :

  • /data/opt/elasticsearch-7.8.0/plugins/opendistro_security/securityconfig/internal_users.yml with the new password hashes
  • /data/kibana/admin/kibana-7.8.0-linux-x86_64/config/kibana.yml with the new Kibana server's password

Finally, to update your changes you can :

  • restart Elasticsearch
  • execute with admin certificates

To execute, run :

cd /data/opt/elasticsearch-7.8.0/plugins/opendistro_security/tools
sudo chmod +x
sudo ./ -cd ../securityconfig/ -icl -nhnv \
    -h server1 \
    -cacert ../../../config/rootca-cert.pem \
    -cert ../../../config/admin-cert.pem \
    -key ../../../config/admin-key.pem

Try now to authenticate with your new credentials with curl, or by connecting to Kibana on server1:5601