Skip to content

Opendistro Guide

Abstract

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.

image

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

Info

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": "1.9.0.0",              
            "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": [
              "emailAddress=nodesuper1@thales.com,CN=nodesuper1,OU=ts,O=thales,L=paris,ST=idf,C=fr"
            ],
            "nodes_dn": [
              "emailAddress=nodesuper2@thales.com,CN=nodesuper2,OU=ts,O=thales,L=paris,ST=idf,C=fr"
            ],
            "kibana_index": ".kibana-admin"
          }
        }
      }
    }
  }
}

Warning

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.

Info

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

Info

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

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": [
          "cachain.pem"
        ]
      }
    },
    "servers": {
      "server1": {
        "address": "server1"
      }
    },
    "plugins": {
      "opendistro_security": {
        "opendistro_security_version": "1.9.0.0"
      }
    }
  }
}

Info

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

Check and generate your configuration

First execute this command on your deployer machine :

$ punchplatform-deployer.sh --generate-inventory

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

deploy

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 :

punchplatform-deployer.sh --deploy -Kk --tags elasticsearch
punchplatform-deployer.sh --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

Warning

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 hash.sh
sudo ./hash.sh
> [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 securityadmin.sh with admin certificates

To execute securityadmin.sh, run :

cd /data/opt/elasticsearch-7.8.0/plugins/opendistro_security/tools
sudo chmod +x securityadmin.sh
sudo ./securityadmin.sh -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