Configuring LDAP and LDAPS

Conventions

• $OS_HOME — the home installation directory of SA Data Storage, typically /app/opensearch
• $OS_CONFIG — the directory for SA Data Storage configuration files, typically ${OS_HOME}/config

---

Creating a Backup

Perform the configuration on the node that stores the admin user's certificate and private key (usually the first node in the cluster). The configuration file is located at $OS_CONFIG/opensearch-security/config.yml.

Important

Create a separate directory for the backup, then run the command. This example uses $OS_CONFIG/security-backup:

mkdir -p $OS_CONFIG/security-backup
JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh -h 127.0.0.1 \
-cacert $OS_CONFIG/ca-cert.pem \
-cert $OS_CONFIG/admin-cert.pem \
-key $OS_CONFIG/admin-key.pem \
--accept-red-cluster -nhnv -icl \
-backup $OS_CONFIG/security-backup/

The backup will be saved in the separate $OS_CONFIG/security-backup directory.

For details about the securityadmin utility, see the Security plugin documentation.

---

Configuring LDAP

To sign in through LDAP, configure authc. To receive roles from LDAP groups, add authz. With authc alone, users can sign in but do not receive LDAP group roles. Make the changes in config.yml.

Set the ldap parameters from the LDAP Parameters table in the authc and authz sections.

Important

Do not put the password directly in config.yml. In the examples, <LDAP_PASSWORD> stands for the service account password; provide its value when setting up the chosen method.

Method 1

Option 1: Configuration via systemd

1. To edit the service settings, run:

sudo systemctl edit opensearch.service

2. Add the following lines, replacing <LDAP_PASSWORD> with the password value:

[Service]
Environment="LDAP_PASSWORD=<LDAP_PASSWORD>"

3. Reload the systemd configuration and restart the opensearch.service:

sudo systemctl daemon-reload
sudo systemctl restart opensearch.service

Option 2: Using an Environment File

1. Add the variable to the $OS_CONFIG/environment file:

LDAP_PASSWORD=<LDAP_PASSWORD>

2. Restart the opensearch.service:

sudo systemctl restart opensearch.service

Common Steps for Both Options:

1. In $OS_CONFIG/opensearch-security/config.yml, replace the placeholder value with password: "${env.LDAP_PASSWORD}"

2. Apply the configuration using securityadmin.sh:

JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh \
  -h <OPENSEARCH_NODE> \
  -icl \
  -nhnv \
  -cacert $OS_CONFIG/ca-cert.pem \
  -cert $OS_CONFIG/admin-cert.pem \
  -key $OS_CONFIG/admin-key.pem \
  -t config \
  -f $OS_CONFIG/opensearch-security/config.yml

Method 2

1. Export the environment variable:

export LDAP_PASSWORD='<LDAP_PASSWORD>'

2. In the config.yml file, specify a reference to the environment variable:

password: "${env.LDAP_PASSWORD}"

When applying the configuration, specify the --resolve-env-vars (or -rev) flag to substitute the environment variable. Without this flag, the literal string ${env.LDAP_PASSWORD} is sent instead of the password, and LDAP returns error 49 (Invalid Credentials).

Important

When creating a backup of the security configuration, please note that the password will be visible.

JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh \
  -h <OPENSEARCH_NODE> \
  -icl \
  -nhnv \
  -cacert $OS_CONFIG/ca-cert.pem \
  -cert $OS_CONFIG/admin-cert.pem \
  -key $OS_CONFIG/admin-key.pem \
  -t config \
  -f $OS_CONFIG/opensearch-security/config.yml \
  --resolve-env-vars

3. Remove the variable from the environment:

unset LDAP_PASSWORD

LDAP Parameters

Parameter	Description	Default value
http_enabled	Enables or disables authentication at the REST level.	true
transport_enabled	Enables or disables authentication at the transport level.	true
hosts	A list of LDAP server addresses and ports.	[]
bind_dn	The DN of the service account used to connect to the directory.
password	The service account password. The examples pass it through LDAP_PASSWORD. A password containing special characters is accepted when entered in YAML in single quotes; double any apostrophe inside such a value: ''.
userbase	The base DN from which user searches are performed.
usersearch	The LDAP filter used to search for a user. {0} is replaced with the user name entered at sign-in.
username_attribute	The LDAP attribute whose value is used as the user name for sign-in.
rolebase	The base DN from which groups are searched.
rolesearch	The LDAP filter used to search for groups containing a user.
userroleattribute	The user attribute. The example sets it to dn.
userrolename	The name of a user entry attribute that stores groups. This example uses none.
rolename	The group entry attribute whose value is used as the user's role.
resolve_nested_roles	Controls nested group searches. The example sets it to false.	false
skip_users	A list of users excluded when retrieving roles.	[]

Applying the Configuration

Example of a completed config.yml

authc:
  basic_internal_auth_domain:
    description: Authenticate via HTTP Basic against internal users database
    http_enabled: true
    transport_enabled: true
    order: 1
    http_authenticator:
      type: basic
      challenge: true
    authentication_backend:
      type: intern
  ldap:
    description: Authenticate via LDAP or Active Directory
    http_enabled: true
    transport_enabled: true
    order: 2
    http_authenticator:
      type: basic
      challenge: false
    authentication_backend:
      type: ldap
      config:
        enable_ssl: false
        enable_start_tls: false
        enable_ssl_client_auth: false
        verify_hostnames: false
        hosts:
          - 'primary.ldap.example.com:389'
          - 'secondary.ldap.example.com:389'
        bind_dn: admin@example.com
        password: "${env.LDAP_PASSWORD}"
        userbase: 'ou=people,dc=example,dc=com'
        usersearch: '(sAMAccountName={0})'
        username_attribute: sAMAccountName
        skip_users:
          - kibanaserver
          - 'cn=Jane Doe,ou*people,o=TEST'
          - /\S*/

This example configures authentication (authc) only. To retrieve LDAP group roles, configure authorization (authz) as well; an example with both sections is provided below.

To apply the configuration, run securityadmin.sh and specify values for OPENSEARCH_NODE and CLUSTER_NAME.

JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh \
-cacert $OS_CONFIG/ca-cert.pem \
-cert $OS_CONFIG/admin-cert.pem \
-key $OS_CONFIG/admin-key.pem \
--accept-red-cluster --clustername <CLUSTER_NAME> \
-f $OS_CONFIG/opensearch-security/config.yml \
-t config -h <OPENSEARCH_NODE>

note

Only the config type configuration from the config.yml file will be updated.

FreeIPA Integration

The example below has been tested with FreeIPA 4.9.13 and Search Anywhere Framework 5.1.3. The server address and DN domain components are placeholders; replace them with values from your installation.

Parameter	Active Directory example above	FreeIPA example
User name attribute	sAMAccountName	uid
User search filter	(sAMAccountName={0})	(uid={0})
User base DN	ou=people,dc=example,dc=com	cn=users,cn=accounts,dc=example,dc=com
bind_dn format	admin@example.com	uid=sm-bind,cn=sysaccounts,cn=etc,dc=example,dc=com
Group base DN	Not specified in the example above	cn=groups,cn=accounts,dc=example,dc=com

For this FreeIPA example, use uid instead of sAMAccountName: usersearch: "(uid={0})" and username_attribute: "uid".

The example keeps basic_internal_auth_domain at order: 1. The service account password is provided through the LDAP_PASSWORD environment variable; configure it using one of the methods described above.

FreeIPA authc and authz configuration example

authc:
  basic_internal_auth_domain:
    description: "Authenticate via HTTP Basic against internal users database"
    http_enabled: true
    transport_enabled: true
    order: 1
    http_authenticator:
      type: basic
      challenge: true
    authentication_backend:
      type: intern
  ldap:
    http_enabled: true
    order: 2
    http_authenticator:
      challenge: false
      type: basic
      config: {}
    authentication_backend:
      type: ldap
      config:
        enable_ssl: true
        enable_start_tls: false
        enable_ssl_client_auth: false
        pemtrustedcas_filepath: "/app/opensearch/config/ipa-ca.crt"
        verify_hostnames: true
        hosts:
          - "ipa.example.com:636"
        bind_dn: "uid=sm-bind,cn=sysaccounts,cn=etc,dc=example,dc=com"
        password: "${env.LDAP_PASSWORD}"
        userbase: "cn=users,cn=accounts,dc=example,dc=com"
        usersearch: "(uid={0})"
        username_attribute: "uid"
authz:
  roles_with_ldap_groups:
    http_enabled: true
    transport_enabled: false
    authorization_backend:
      type: "ldap"
      config:
        enable_ssl: true
        enable_start_tls: false
        enable_ssl_client_auth: false
        pemtrustedcas_filepath: "/app/opensearch/config/ipa-ca.crt"
        verify_hostnames: true
        hosts:
          - "ipa.example.com:636"
        bind_dn: "uid=sm-bind,cn=sysaccounts,cn=etc,dc=example,dc=com"
        password: "${env.LDAP_PASSWORD}"
        rolebase: "cn=groups,cn=accounts,dc=example,dc=com"
        rolesearch: "(member={0})"
        userroleattribute: "dn"
        userrolename: "none"
        rolename: "cn"
        resolve_nested_roles: false
        userbase: "cn=users,cn=accounts,dc=example,dc=com"
        usersearch: "(uid={0})"
        skip_users: ["admin", "sme", "kibanaserver", "logstash", "snapshotrestore"]

Nested group searches are disabled in this example (resolve_nested_roles: false).

---

Configuring LDAPS

Important

If LDAP uses a separate certificate authority, set pemtrustedcas_filepath to the CA file path in every LDAP section in authc and authz. The parameter is required for STARTTLS if plugins.security.ssl.transport.truststore_filepath is not set.

To connect to LDAP over SSL, set the ldap configuration parameters in the table below.

Parameter	Description	Default value
enable_ssl	Enables LDAPS. For LDAPS, set this to true, set enable_start_tls: false, and use port 636.	false
enable_start_tls	Enables STARTTLS. For this mode, set enable_ssl: false, set enable_start_tls: true, and use port 389. The pemtrustedcas_filepath parameter is required if plugins.security.ssl.transport.truststore_filepath is not set.	false
enable_ssl_client_auth	Determines whether to send the client certificate to the LDAP server.	false
verify_hostnames	Determines whether to verify the hostnames of the server certificate.	false

Use one of these connection modes:

1. LDAPS: enable_ssl: true, enable_start_tls: false, port 636
2. STARTTLS: enable_ssl: false, enable_start_tls: true, port 389; the pemtrustedcas_filepath parameter is required if plugins.security.ssl.transport.truststore_filepath is not set

Do not enable LDAPS and STARTTLS together: this combination is not supported.

Certificate Verification

If the LDAP settings do not specify a certificate authority, the Security plugin refers to plugins.security.ssl.transport.truststore_filepath in opensearch.yml.

If the server certificate is signed by a different CA, add that CA to the truststore or specify it in the LDAP settings using one of these options:

• pemtrustedcas_filepath — the absolute path to a PEM file containing the root CA certificate
• pemtrustedcas_content — the root CA certificate content; do not use it together with pemtrustedcas_filepath

The plugins.security.ssl.transport.pemtrustedcas_filepath setting in opensearch.yml does not replace specifying the CA path in the LDAP configuration.

If sign-in fails, check the SA Data Storage log: the interface shows the same message for a missing STARTTLS CA and an unresolved password variable.

Client Authentication

For TLS client authentication, the Security plugin sends the node's PEM certificate according to the settings in opensearch.yml. Set the configuration parameters required by your chosen method of providing the certificate and key:

• pemkey_filepath - the absolute path to the file containing the private key of your certificate, used in conjunction with pemkey_password and pemcert_filepath
• pemkey_password - the password of your private key, if any
• pemcert_filepath - the absolute path to the client certificate, used in conjunction with pemkey_password and pemkey_filepath
• pemkey_content - the content of the private key of your certificate, used in conjunction with pemkey_password and pemcert_content, not used together with pemkey_filepath
• pemcert_content - the content of the client certificate, used in conjunction with pemkey_password and pemkey_content, not used together with pemcert_filepath

Enabled Ciphers and Protocols

You can restrict the allowed TLS ciphers and protocols for the LDAP connection. For example, the following parameters let you allow only strong ciphers and recent TLS versions:

• enabled_ssl_ciphers - a list of enabled TLS ciphers in Java format
• enabled_ssl_protocols - a list of enabled TLS protocols in Java format

Applying the Configuration

Example of a completed config.yml

authc:
  basic_internal_auth_domain:
    description: "Authenticate via HTTP Basic against internal users database"
    http_enabled: true
    transport_enabled: true
    order: 1
    http_authenticator:
      type: basic
      challenge: true
    authentication_backend:
      type: intern
  ldap:
    http_enabled: true
    order: 2
    http_authenticator:
      challenge: false
      type: basic
      config: {}
    authentication_backend:
      type: ldap
      config:
        enable_ssl: true
        enable_start_tls: false
        enable_ssl_client_auth: false
        pemtrustedcas_filepath: "/app/opensearch/config/ipa-ca.crt"
        verify_hostnames: true
        hosts:
          - "ipa.example.com:636"
        bind_dn: "uid=sm-bind,cn=sysaccounts,cn=etc,dc=example,dc=com"
        password: "${env.LDAP_PASSWORD}"
        userbase: "cn=users,cn=accounts,dc=example,dc=com"
        usersearch: "(uid={0})"
        username_attribute: "uid"
authz:
  roles_with_ldap_groups:
    http_enabled: true
    transport_enabled: false
    authorization_backend:
      type: "ldap"
      config:
        enable_ssl: true
        enable_start_tls: false
        enable_ssl_client_auth: false
        pemtrustedcas_filepath: "/app/opensearch/config/ipa-ca.crt"
        verify_hostnames: true
        hosts:
          - "ipa.example.com:636"
        bind_dn: "uid=sm-bind,cn=sysaccounts,cn=etc,dc=example,dc=com"
        password: "${env.LDAP_PASSWORD}"
        rolebase: "cn=groups,cn=accounts,dc=example,dc=com"
        rolesearch: "(member={0})"
        userroleattribute: "dn"
        userrolename: "none"
        rolename: "cn"
        resolve_nested_roles: false
        userbase: "cn=users,cn=accounts,dc=example,dc=com"
        usersearch: "(uid={0})"
        skip_users: ["admin", "sme", "kibanaserver", "logstash", "snapshotrestore"]

To apply the configuration, run securityadmin.sh and specify values for OPENSEARCH_NODE and CLUSTER_NAME.

JAVA_HOME=$OS_HOME/jdk/ $OS_HOME/plugins/opensearch-security/tools/securityadmin.sh \
-cacert $OS_CONFIG/ca-cert.pem \
-cert $OS_CONFIG/admin-cert.pem \
-key $OS_CONFIG/admin-key.pem \
--accept-red-cluster --clustername <CLUSTER_NAME> \
-f $OS_CONFIG/opensearch-security/config.yml \
-t config -h <OPENSEARCH_NODE>

note

Only the config type configuration from the config.yml file will be updated.

Assigning Roles

To assign roles to users:

1. Go to Main Menu - Settings - Security - Roles
2. Select an existing role or create a new one
3. Go to the Mapped Users - Manage Mapping tab and add the domain user or security group to the Backend roles parameter
4. Save the new settings