Documentation

InfluxDB Enterprise

Configure LDAP authentication

Configure InfluxDB Enterprise to use LDAP (Lightweight Directory Access Protocol) to:

  • Validate user permissions
  • Synchronize InfluxDB and LDAP so each LDAP request doesn’t need to be queried

LDAP requires JWT authentication. For more information, see Configure authentication using JWT tokens.

To configure InfluxDB Enterprise to support LDAP, all users must be managed in the remote LDAP service. If LDAP is configured and enabled, users must authenticate through LDAP, including users who may have existed before enabling LDAP.

Configure LDAP for an InfluxDB Enterprise cluster

To use LDAP with an InfluxDB Enterprise cluster, do the following:

  1. Configure data nodes
  2. Configure meta nodes
  3. Create, verify, and upload the LDAP configuration file
  4. Restart meta and data nodes

Configure data nodes

Update the following settings in each data node configuration file (/etc/influxdb/influxdb.conf):

  1. Under [http], enable HTTP authentication by setting auth-enabled to true. (Or set the corresponding environment variable INFLUXDB_HTTP_AUTH_ENABLED to true.)
  2. Configure the HTTP shared secret to validate requests using JSON web tokens (JWT) and sign each HTTP payload with the secret and username. Set the [http] configuration setting for shared-secret, or the corresponding environment variable INFLUXDB_HTTP_SHARED_SECRET.
  3. If you’re enabling authentication on meta nodes, you must also include the following configurations:
    • INFLUXDB_META_META_AUTH_ENABLED environment variable, or [http] configuration setting meta-auth-enabled, is set to true. This value must be the same value as the meta node’s meta.auth-enabled configuration.
    • INFLUXDB_META_META_INTERNAL_SHARED_SECRET, or the corresponding [meta] configuration setting meta-internal-shared-secret, is set a secret value. This value must be the same value as the meta node’s meta.internal-shared-secret.

Configure meta nodes

Update the following settings in each meta node configuration file (/etc/influxdb/influxdb-meta.conf):

  1. Configure the meta node META shared secret to validate requests using JSON web tokens (JWT) and sign each HTTP payload with the username and shared secret.
  2. Set the [meta] configuration setting internal-shared-secret to "<internal-shared-secret>". (Or set the INFLUXDB_META_INTERNAL_SHARED_SECRET environment variable.)
  3. Set the [meta] configuration setting meta.ldap-allowed to true on all meta nodes in your cluster. (Or set the INFLUXDB_META_LDAP_ALLOWEDenvironment variable.)

Authenticate your connection to InfluxDB

To authenticate your InfluxDB connection, run the following command, replacing username:password with your credentials:

curl -u username:password -XPOST "http://localhost:8086/..."
  • Copy
  • Fill window

For more detail on authentication, see Authentication and authorization in InfluxDB.

Create, verify, and upload the LDAP configuration file

  1. To create a sample LDAP configuration file, run the following command:

    influxd-ctl ldap sample-config
    • Copy
    • Fill window

  2. Save the sample file and edit as needed for your LDAP server. For detail, see the sample LDAP configuration file below.

    To use fine-grained authorization (FGA) with LDAP, you must map InfluxDB Enterprise roles to key-value pairs in the LDAP database. For more information, see Fine-grained authorization in InfluxDB Enterprise. The InfluxDB admin user doesn’t include permissions for InfluxDB Enterprise roles.

  3. Restart all meta and data nodes in your InfluxDB Enterprise cluster to load your updated configuration.

    On each meta node, run:

    sysvinit systemd

    service influxdb-meta restart
    • Copy
    • Fill window
    sudo systemctl restart influxdb-meta
    • Copy
    • Fill window

    On each data node, run:

    sysvinit systemd

    service influxdb restart
    • Copy
    • Fill window
    sudo systemctl restart influxdb
    • Copy
    • Fill window

  4. To verify your LDAP configuration, run:

    influxd-ctl ldap verify -ldap-config /path/to/ldap.toml
    • Copy
    • Fill window

  5. To load your LDAP configuration file, run the following command:

    influxd-ctl ldap set-config /path/to/ldap.toml
    • Copy
    • Fill window

Sample LDAP configuration

The following is a sample configuration file that connects to a publicly available LDAP server.

A DN (“distinguished name”) uniquely identifies an entry and describes its position in the directory information tree (DIT) hierarchy. The DN of an LDAP entry is similar to a file path on a file system. DNs refers to multiple DN entries.

enabled = true

[[servers]]
  host = "ldap.example.com"
  port = 389

  # Security mode for LDAP connection to this server.
  # Valid settings: none, starttls, starttls+insecure, ldaps, ldaps+insecure.
  # The recommended security is "starttls", which is the default. This uses
  # an initial unencrypted connection and upgrades to TLS as the first action
  # against the server, per the LDAPv3 standard.
  # Another secure option is "ldaps", which starts the connection over
  # TLS instead of upgrading like "starttls". This generally requires a
  # dedicated port (usually 636).  "starttls" is generally preferred
  # to "ldaps".
  # Other options are "starttls+insecure" and "ldaps+insecure" which behave
  # the same as "starttls" and and "ldaps" respectively, except they ignore
  # server certificate verification errors.
  # Finally, "none" does not use TLS. This is not recommended for
  # production systems.
  security = "starttls"
  
  # Client certificates to present to the LDAP server are supported with
  # "client-tls-certificate" and  "client-tls-private-key" configurations.
  # These are paths to the X.509 client certificate and corresponding private
  # key, respectively. If "client-tls-certificate" is set but 
  # "client-tls-private-key" is not, then "client-tls-certificate" is assumed
  # to bundle both the certificate and private key.
  # The LDAP server may request and require valid client certificates
  # even when InfluxDB is configured with an insecure TLS mode that ignores
  # LDAP server certificate errors.
  # Not all LDAP servers will request a client certificate. It is not
  # necessary to set "client-tls-certificate" and "client-tls-private-key"
  # if the LDAP server does not require client certificates.
  client-tls-certificate = "/var/run/secrets/ldapClient.pem"
  client-tls-private-key = "/var/run/secrets/ldapClient.key"

  # Client certificates to present to the LDAP server are supported with
  # "client-tls-certificate" and  "client-tls-private-key" configurations.
  # These are paths to the X.509 client certificate and corresponding private
  # key, respectively. If "client-tls-certificate" is set but 
  # "client-tls-private-key" is not, then "client-tls-certificate" is assumed
  # to bundle both the certificate and private key.
  # The LDAP server may request and require valid client certificates
  # even when InfluxDB is configured with an insecure TLS mode that ignores
  # LDAP server certificate errors.
  # Not all LDAP servers will request a client certificate. It is not
  # necessary to set "client-tls-certificate" and "client-tls-private-key"
  # if the LDAP server does not require client certificates.
  client-tls-certificate = "/var/run/secrets/ldapClient.pem"
  client-tls-private-key = "/var/run/secrets/ldapClient.key"

  # Credentials to use when searching for a user or group.
  bind-dn = "cn=read-only-admin,dc=example,dc=com"
  bind-password = "read-only-admin's password"

  # Base DNs to use when applying the search-filter to discover an LDAP user.
  search-base-dns = [
    "dc=example,dc=com",
  ]

  # LDAP filter to discover a user's DN.
  # %%s will be replaced with the provided username.
  search-filter = "(uid=%%s)"
  # On Active Directory you might use "(sAMAccountName=%%s)".

  # Base DNs to use when searching for groups.
  group-search-base-dns = ["ou=groups,dc=example,dc=com"]

  # LDAP filter to identify groups that a user belongs to.
  # %%s will be replaced with the user's DN.
  group-membership-search-filter = "(&(objectClass=groupOfUniqueNames)(uniqueMember=%%s))"
  # On Active Directory you might use "(&(objectClass=group)(member=%%s))".

  # Attribute to use to determine the "group" in the group-mappings section.
  group-attribute = "ou"
  # On Active Directory you might use "cn".

  # LDAP filter to search for groups during cache warming.
  # %%s will be replaced with the "group" value in the group-mappings section.
  group-search-filter = "(&(objectClass=groupOfUniqueNames)(ou=%%s))"

  # Attribute on group objects indicating membership.
  # Used during cache warming, should be same as part of the group-membership-search-filter.
  group-member-attribute = "uniqueMember"

  # Groups whose members have admin privileges on the influxdb servers.
  admin-groups = ["influx-admins"]

  # Mappings of LDAP groups to Influx roles.
  # All Influx roles need to be manually created to take effect.
  [[servers.group-mappings]]
    group = "app-developers"
    role = "app-metrics-rw"

  [[servers.group-mappings]]
    group = "web-support"
    role = "web-traffic-ro"
  • Copy
  • Fill window

Troubleshoot LDAP in InfluxDB Enterprise

InfluxDB Enterprise does not recognize a new LDAP server

If you ever replace an LDAP server with a new one, you need to update your InfluxDB Enterprise LDAP configuration file to point to the new server. However, InfluxDB Enterprise may not recognize or honor the updated configuration.

For InfluxDB Enterprise to recognize an LDAP configuration pointing to a new LDAP server, do the following:

Performing the following process on a production cluster may have unintended consequences. Moving to a new LDAP server constitutes and infrastructure change and may better be handled through a cluster migration. For assistance, reach out to InfluxData support.

  1. On each meta node, update the auth-enabled setting to false in your influxdb-meta.conf configuration file to temporarily disable authentication.

    [meta]
  auth-enabled = false
    • Copy
    • Fill window

  2. Restart all meta nodes to load the updated configuration. On each meta node, run:

    sysvinit systemd

    service influxdb-meta restart
    • Copy
    • Fill window
    sudo systemctl restart influxdb-meta
    • Copy
    • Fill window

  3. On each meta node, create, verify, and upload the new LDAP configuration file.

  4. On each meta node, update the auth-enabled setting to true in your influxdb-meta.conf configuration file to reenable authentication.

    [meta]
  auth-enabled = true
    • Copy
    • Fill window

  5. Restart all meta nodes to load the updated configuration. On each meta node, run:

    sysvinit systemd

    service influxdb-meta restart
    • Copy
    • Fill window
    sudo systemctl restart influxdb-meta
    • Copy
    • Fill window

User cannot log in after updating their password in the LDAP server

LDAP credentials are cached on InfluxDB Enterprise data nodes. If credentials change in the LDAP server, the cached credentials need to be purged and the cache refreshed to add the updated credentials.

  1. Use the influxd-ctl ldap purge-cache command to purge LDAP credential caches on data nodes.

    influxd-ctl ldap purge-cache
    • Copy
    • Fill window

  2. Use the influxd-ctl ldap warm-cache command to warm LDAP credential caches on data nodes.

    influxd-ctl ldap warm-cache
    • Copy
    • Fill window

Was this page helpful?

Thank you for your feedback!

© 2025 InfluxData, Inc.

Where are you running InfluxDB?

Customize your InfluxDB Enterprise URL and we’ll update code examples for you.

Default
Custom

For more information, see InfluxDB Enterprise HTTP settings.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB 3 Core and Enterprise are now in Beta

InfluxDB 3 Core and Enterprise are now available for beta testing, available under MIT or Apache 2 license.

InfluxDB 3 Core is a high-speed, recent-data engine that collects and processes data in real-time, while persisting it to local disk or object storage. InfluxDB 3 Enterprise is a commercial product that builds on Core’s foundation, adding high availability, read replicas, enhanced security, and data compaction for faster queries. A free tier of InfluxDB 3 Enterprise will also be available for at-home, non-commercial use for hobbyists to get the full historical time series database set of capabilities.

For more information, check out:

Ask AI