Configuring LDAP and LDAPS

Creating a Backup

All actions in this article are recommended to be performed on the first node created in the cluster. The configuration is usually located in the /app/opensearch/config/opensearch-security/config/yml directory.

warning

Back up your current configuration using the following command:

JAVA_HOME=/app/opensearch/jdk/ /app/opensearch/plugins/opensearch-security/tools/securityadmin.sh -h 127.0.0.1 \
-cacert /app/opensearch/config/ca-cert.pem \
-cert /app/opensearch/config/admin-cert.pem \
-key /app/opensearch/config/admin-key.pem \
--accept-red-cluster -nhnv -icl \
-backup /app/opensearch/config/opensearch-security/

The backup will be saved in the /app/opensearch/config/opensearch-security directory.

More information about the securityadmin utility can be found in the Security plugin documentation.

Configuring LDAP

Active Directory and LDAP can be used for both authentication and authorization (authc and authz configuration sections, respectively). Authentication verifies that the user has entered valid credentials. Authorization retrieves all server roles for the user. In most cases, you need to configure both authentication and authorization. You can also use only authentication and map users retrieved from LDAP directly to system roles. All changes are made in the config.yml configuration file.

In the authc and authz sections, you need to fill in the ldap configuration parameters listed in the table below.

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`	Used to configure the hostname and port of the Active Directory servers.	`[]`
`bind_dn`	The account to connect to Active Directory.
`password`	The password for the account to connect to Active Directory. If special characters are used in the password, it must be enclosed in single quotes.
`userbase`	The filter used in the LDAP query when retrieving users.
`skip_users`	A list of users to skip when retrieving roles. Wildcards and regular expressions are supported.	`[]`

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: p@ssword
        userbase: 'ou=people,dc=example,dc=com'
        usersearch: '(sAMAccountName={0})'
        username_attribute: sAMAccountName
        skip_users:
          - kibanaserver
          - 'cn=Jane Doe,ou*people,o=TEST'
          - /\S*/

To apply the new configuration, you need to run securityadmin.sh. Set your values for OPENSEARCH_NODE and CLUSTER_NAME.

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

note

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

Configuring LDAPS

warning

When configuring a separate root CA for LDAPS, be sure to include this setting in all LDAP configuration instances, including authc and authz settings.

To configure a connection to LDAP using SSL, you need to fill in the ldap configuration parameters listed in the table below.

Parameter	Description	Default Value
`enable_ssl`	Enables or disables SSL for LDAP (LDAPS).	`false`
`enable_start_tls`	Enables or disables `STARTTLS`. Cannot be used in conjunction with LDAPS.	`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`

Certificate Verification

By default, the Security plugin verifies the LDAP server certificate against the root CA configured in opensearch.yml (plugins.security.ssl.transport.pemtrustedcas_filepath and plugins.security.ssl.transport.truststore_filepath).

If your server uses a certificate signed by a different CA, import that CA into your truststore or add it to the trusted CA file on each node:

pemtrustedcas_filepath - The absolute path to the PEM file containing the root CAs of your Active Directory server.
pemtrustedcas_content - The content of the root CA of your Active Directory server, not used together with pemtrustedcas_filepath.

Client Authentication

If you are using TLS client authentication, the security plugin sends the node's PEM certificate as configured in opensearch.yml. Set one of the following configuration parameters:

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, you can allow only strong ciphers and restrict TLS versions to the latest ones by configuring the following parameters:

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:
    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: true
        enable_start_tls: true
        enable_ssl_client_auth: true
        verify_hostnames: true
        pemtrustedcas_filepath: /app/opensearch/config/trusted_cas.pem
        pemkey_filepath: /app/opensearch/config/private.key.pem
        pemkey_password: p@ssword
        pemcert_filepath: /app/opensearch/config/certificate.pem
        enabled_ssl_ciphers:
          - TLS_DHE_RSA_WITH_AES_256_CBC_SHA
          - TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
        enabled_ssl_protocols:
          - TLSv1.1
          - TLSv1.2
        hosts:
          - 'primary.ldap.example.com:389'
          - 'secondary.ldap.example.com:389'
        bind_dn: admin@example.com
        password: p@ssword
        userbase: 'ou=people,dc=example,dc=com'
        usersearch: '(sAMAccountName={0})'
        username_attribute: sAMAccountName
        skip_users:
          - kibanaserver
          - 'cn=Jane Doe,ou*people,o=TEST'
          - /\S*/

To apply the new configuration, you need to run securityadmin.sh. Set your values for OPENSEARCH_NODE and CLUSTER_NAME.

JAVA_HOME=/app/opensearch/jdk/ /app/opensearch/plugins/opensearch-security/tools/securityadmin.sh \
-cacert /app/opensearch/config/ca-cert.pem \
-cert /app/opensearch/config/admin-cert.pem \
-key /app/opensearch/config/admin-key.pem \
--accept-red-cluster --clustername <CLUSTER_NAME> \
-f /app/opensearch/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:

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

Creating a Backup​

Configuring LDAP​

Applying the Configuration​

Configuring LDAPS​

Certificate Verification​

Client Authentication​

Enabled Ciphers and Protocols​

Applying the Configuration​

Assigning Roles​

Creating a Backup

Configuring LDAP

Applying the Configuration

Configuring LDAPS

Certificate Verification

Client Authentication

Enabled Ciphers and Protocols

Applying the Configuration

Assigning Roles