Skip to content

Configuring Opendistro Security binding with LDAP and associated Elastic/Kibana Role-Based Access Control mappings

The advised integration process is in 3 steps:

  • Step 1: Design and test your Opendistro/LDAP communication and LDAP attributes mapping, using a STANDALONE punchplatform with active opendistro security
  • Step 2: Prepare your LDAP backend Role / Opendistro roles / Access rights configuration on the standalone bound to your test LDAP
  • Step 3: Transport your Opendistro configuration AND roles bindings from your test/integration instance of punchplatform to a deployed Punchplatform

Step 1 : Standalone tests for basic OpenDistro/LDAP binding (identity authentication + roles membership)


The purpose of this section is testing the validity of your Open Distro Security plugin configuration with and LDAP service inside a standalone environment.
You will need to deploy your own LDAP service (OpenLDAP or AD) and add user object entries for tests.

LDAP structure for standalone

Install an OpenLDAP or AD backend on your local machine.


You can use this solution with docker-compose to install and test your own OpenLDAP backend :


Install ldap-utils package on your standalone environment before going further.
Example for Ubuntu : sudo apt install ldap-utils

Once your LDAP service is up, you must add the memberOf overlay to get a reverse-membership attribute computation on user accounts. This will help Open Distro Security plugin for Elasticsearch to query a user and automatically obtain its group membership for role mappings :

ldapadd -Y EXTERNAL -H ldapi:/// < overlay.ldif

SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
adding new entry "olcOverlay=memberof,olcDatabase={1}mdb,cn=config"


Get more information about the memberOf overlay on


Make sure you pushed the overlay before any ldap new entry command. If not, you will have to remove every group and start again after the memberOf overlay has been applied.

You may inject some test user entries inside your LDAP service to proceed to tests :


With this sample ldif file, the password associated to Alice, Bill and Carol are 'punch'.

ldapadd -a -H ldap://${ldap_host}:${ldap_port} -D "cn=admin,dc=punch,dc=io" -w punchpwd -f multiroles.ldif

adding new entry "ou=People,dc=punch,dc=io"
adding new entry "cn=Alice ARTON,ou=People,dc=punch,dc=io"
adding new entry "cn=Bill BARROW,ou=People,dc=punch,dc=io"
adding new entry "cn=Carol CORNWALL,ou=People,dc=punch,dc=io"
adding new entry "ou=groups,dc=punch,dc=io"
adding new entry "cn=analysts,ou=groups,dc=punch,dc=io"
adding new entry "cn=punchadmin,ou=groups,dc=punch,dc=io"
adding new entry "cn=sshuser,ou=groups,dc=punch,dc=io"

Test your new entries by verifying the memberOf overlay is properly working :

ldapsearch -x -H ldap:// -b cn="Alice ARTON",ou=People,dc=punch,dc=io -D "cn=admin,dc=punch,dc=io" -w punchpwd +| grep -i memberOF

#      memberOf: cn=analysts,ou=groups,dc=punch,dc=io

Open Distro configuration for LDAP binding

Install a fresh Punchplatform standalone with Open Distro Security :

./ --with-opendistro-security

Start and verify Elasticsearch is secured with Open Distro Security :

# start standalone --start

# check ES cluster security
curl localhost:9200

# >> Unauthorized

curl localhost:9200 -u admin:admin

# >> works !

Configure Open Distro Security for LDAP by editing the config.yml file :

edit <Punchplatform Standalone install dir>/../external/elasticsearch-7.8.0/plugins/opendistro_security/securityconfig/config.yml


Learn how to configure Open Distro Security with LDAP : Open Distro Security plugin's LDAP configuration docs


You may use this sample with your standalone to configure Open Distro Security with LDAP : config.yml.
Replace the old one by this one (after making a backup copy).

Do not use this configuration in any production environment !

Push the new Open Distro configuration in Elasticsearch using :

cd $PUNCHPLATFORM_CONF_DIR/../external/elasticsearch-7.8.0/plugins/opendistro_security/tools
sudo chmod +x
sudo ./ -cd ../securityconfig/ -icl -nhnv \
    -cacert ../../../config/punch-ca.pem \
    -cert ../../../config/es-admin-super-1-cert.pem \
    -key ../../../config/es-admin-super-1-key-pkcs8.pem

Go to Kibana and create the role mapping to bind the LDAP groups (backend roles) with the Open Distro Security roles :

  1. Go to localhost:5601 in your browser
  2. Connect as admin:admin
  3. Go to Security (tab inside the left padlock) > Role Mappings
  4. Select Role > kibana_user
  5. write the LDAP group of your choice in Backend role > +Add. The users of this group will be considered as simple users by Open Distro Security (no administration permissions, but they can connect to kibana.) The name you give the 'backend role' must match the name attribute you have configured in the opendistro configuration file ('rolename' setting) on the role group ldap object.
  6. Click Submit and logout


If you downloaded the multirole.ldif file example for your LDAP structure, you can bind kibana_user with analysts group for example. In this case 'Alice' should be able to connect to kibana.

Do not use this configuration in any production environment !

Test a user using curl in a terminal :

# cluster nodes with default Open Distro Security 'admin' user
curl 'localhost:9200/_cat/nodes?pretty' -u admin:admin

# cluster nodes with LDAP analysts 'alice' user, bound as a simple kibana user with Open Distro Security
curl 'localhost:9200/_cat/nodes?pretty' -u alice:punch

  "error" : {
    "root_cause" : [
        "type" : "security_exception",
        "reason" : "no permissions for [cluster:monitor/state] and User [name=alice, backend_roles=[analysts], requestedTenant=null]"
    "type" : "security_exception",
    "reason" : "no permissions for [cluster:monitor/state] and User [name=alice, backend_roles=[analysts], requestedTenant=null]"
  "status" : 403

Finally, export your Open Distro Security configuration file inside a dedicated directory to be used in an integration environment :

mkdir ~/opendistro_config
cp $PUNCHPLATFORM_CONF_DIR/../external/elasticsearch-7.8.0/plugins/opendistro_security/securityconfig/config.yml ~/opendistro_config

Step 2 : Prepare your production LDAP/RBAC mappings in integration environment (or yet on standalone)


Using your configurations ready to bind Open Distro Security with your LDAP backend, you will need :

  • A fresh Punchplatform Deployer (except if you do this step using a standalone in integration environment)
  • To deploy Elasticsearch with Open Distro Security using the Punchplatform deployer
  • To deploy Kibana with Open Distro Security using the Punchplatform deployer
  • To get your OpenLDAP or AD backend ready and up

Once the previous services are up and functional, the overall process is :

  • Import your prepared Open Distro Security configuration in ES cluster
  • Import your prepared LDAP configuration in OpenLDAP or AD
  • Use Open Distro Security for Kibana HMI to configure actual security roles, matching your production usecase and your production elasticsearch indices to protect

  • Test your security measures and configurations for every role and enhance them if necessary.

  • Export this roles mapping for production platform deployment

LDAP integration use case

Get your LDAP service (OpenLDAP or AD for example) ready in an integration environment.

Make sure your service is up and verify you have :

  • The LDAP host and port open for Elasticsearch nodes
  • Loaded the memberOf overlay to your LDAP service. Check the previous section for more information about this step.
  • Structured your LDAP with users entries matching your use case
  • Structured your LDAP with groups These groups are mandatory for Open Distro Security roles mapping (they will be used as 'backend roles' from opendistro point of view).

Open Distro integration for LDAP binding

Inside your punchplatform-deployment.settings file, configure :

  • An operator environment
  • Elasticsearch with Open Distro Security
  • Kibana with Open Distro Security


Check how to configure these components in punchplatform-deployment.settings documentation

Deploy the operator environment, Elasticsearch then Kibana :

# verify your configuration -gi
# deploy deploy -Kk --tags operator,elasticsearch,kibana
# test Elasticsearch connexion
curl ${es_node}:${es_port}

Get the Open Distro Security configuration file you created during the previous section of this documentation.
Adapt the configuration if your LDAP environment have changed, then import it to one of your Elasticsearch nodes and finally push it inside your Elasticsearch cluster :

# import the opendistro security configuration to ONE es node. Check 'setups_root' value inside your puncplatform-deployment.settings
scp ~/opendistro_config/config.yml admin@esnode:/${setups_root}/${es_version}/plugins/opendistro_security/securityconfig
# push the Open configuration 
ssh admin@esnode
cd /${setups_root}/${es_version}/plugins/opendistro_security/tools
sudo chmod +x
sudo ./ -cd ../securityconfig/ -icl -nhnv \
    -h ${es_node}
    -cacert ../../../config/${admin_ca_file} \
    -cert ../../../config/${admin_cert} \
    -key ../../../config/${admin_key}


The admin_ca_file, admin_cert and admin_key files are mandatory for Open Distro Security configuration management. You Must provide them inside a folder and set its path inside the local_ssl_certs_dir configuration of each elasticsearch server : punchplatform-deployment.settings.

Warning REPLACES any configuration of opendistro roles mapping/ RBAC settings that you may have done using the kibana 'security' plugin. So before launching this command a second time, make sure you have backed up all the changes you did on the integration platform (see 'exporting' below)

Configure and Export the final Open Distro Security configuration (including RBAC roles mappings)

The next step is by far the most important :

  • Each group of users inside your LDAP model must relate to a restricted data access that you already defined with use cases
  • Create an Open Distro Security role for each user group
  • Configure a cluster, index and optionally document and field permissions for each Open Distro Security role to match the bound user group

Once you validated that every security role matches your data access use cases, export your Open Distro Security configurations, to be imported in a production environment :

# on es node, export Open Distro Security configurations
mkdir ~/opendistro_backup
cd /${setups_root}/${es_version}/plugins/opendistro_security/tools
sudo ./ -backup ~/opendistro_backup -icl -nhnv \
    -h ${es_node}
    -cacert ../../../config/${admin_ca_file} \
    -cert ../../../config/${admin_cert} \
    -key ../../../config/${admin_key}

Step 3 : Deploy opendistro security/LDAP binding and RBAC mappings for production


At this step, we consider your production platform was pre-deployed with the Punchplatform Deployer and currently runs with :

  • An LDAP service (OpenLDAP or AD) with the memberOf overlay
  • An Elasticsearch cluster with Open Distro Security (initial 'raw' deployed config with admin:admin as only known user)
  • At least one Kibana domain with Open Distro Security

Test every service is up and run properly before going further !

At this step, we consider you have :

  • All configuration files of Open Distro Security plugin exported at the end of the previous step
  • Users and groups properly structured inside your LDAP service

With your production platform ready, import your Open Distro Configuration files on one of the Elasticsearch node:

scp ~/opendistro_conf_export admin@coord_es_host:/${setups_root}/${es_version}/plugins/opendistro_security/securityconfig
ssh admin@coord_es_host
cd /${setups_root}/${es_version}/plugins/opendistro_security/tools
sudo chmod +x
sudo ./ -cd ../securityconfig/ -icl -nhnv \
    -h ${es_node}
    -cacert ../../../config/${admin_ca_file} \
    -cert ../../../config/${admin_cert} \
    -key ../../../config/${admin_key}


Make sure the Open Distro Security configuration files are imported on the Elasticsearch cluster node using an administrator technical user, and not a normal application operator account ! All Open Distro Security configuraion management action must be performed with this admin. No configuration file should remain scattered over the filesystem of your coordinating node ; should be located inside the Open Distro configuration folder only, protected with admin permissions for write and read access.

You should be able to use your production platform with the security roles created during the integration phase now.

In the future, to create or change security roles in production, restart from the integration phase of this process.