Configure LDAP authentication

LDAP authentication signs users in by binding their credentials against an LDAP or Active Directory server. Telegraf Controller can read user attributes and group membership from the directory and use them to assign roles and provision accounts.

• Prerequisites
• Configure LDAP at startup
• Configure provisioning
• Configure group-to-role mapping
• Bootstrap the owner against LDAP
• Provider examples
• Disable LDAP
• Audit events

Prerequisites

• A valid Telegraf Enterprise license applied to your Telegraf Controller instance.
• A reachable LDAP server (ldap:// or ldaps://) and a service-account bind DN that can search the user subtree.
• Permission to modify the Telegraf Controller startup environment.
• The Owner role to change LDAP settings from the Settings page.

Configure LDAP at startup

Set the LDAP environment variables before starting Telegraf Controller. The variables in the following table are the minimum required to enable LDAP authentication.

For the full description of each variable, including defaults, see Authentication and security configuration options.

Apply the configuration

[Service]
Environment=AUTH_LDAP_ENABLED=true
Environment=AUTH_LDAP_URL=ldaps://ldap.example.com:636
Environment=AUTH_LDAP_BIND_DN=cn=svc-controller,ou=services,dc=example,dc=com
Environment=AUTH_LDAP_BIND_PASSWORD=changeme
Environment=AUTH_LDAP_USER_SEARCH_BASE=ou=people,dc=example,dc=com
Environment=AUTH_LDAP_USER_SEARCH_FILTER=(uid={{username}})

sudo systemctl daemon-reload
sudo systemctl restart telegraf-controller

export AUTH_LDAP_ENABLED=true
export AUTH_LDAP_URL=ldaps://ldap.example.com:636
export AUTH_LDAP_BIND_DN='cn=svc-controller,ou=services,dc=example,dc=com'
export AUTH_LDAP_BIND_PASSWORD=changeme
export AUTH_LDAP_USER_SEARCH_BASE='ou=people,dc=example,dc=com'
export AUTH_LDAP_USER_SEARCH_FILTER='(uid={{username}})'

telegraf_controller --no-interactive

$env:AUTH_LDAP_ENABLED="true"
$env:AUTH_LDAP_URL="ldaps://ldap.example.com:636"
$env:AUTH_LDAP_BIND_DN="cn=svc-controller,ou=services,dc=example,dc=com"
$env:AUTH_LDAP_BIND_PASSWORD="changeme"
$env:AUTH_LDAP_USER_SEARCH_BASE="ou=people,dc=example,dc=com"
$env:AUTH_LDAP_USER_SEARCH_FILTER="(uid={{username}})"

./telegraf_controller.exe --no-interactive

After Telegraf Controller starts, sign in as an owner and confirm:

• Settings > LDAP Authentication shows the redacted connection details.
• The sign-in page offers an LDAP option.

Call the public status endpoint to confirm the provider is registered:

curl -s http://localhost:8888/api/auth/status

Configure provisioning

Provisioning rules decide what happens the first time an LDAP user signs in. Configure them on the Settings > LDAP Authentication panel.

To update provisioning settings:

1. Sign in as an Owner or Administrator.
2. Navigate to the Settings page.
3. In the LDAP Authentication section, update the values.
4. Click Save.

The new values take effect on the next sign-in attempt.

Configure group-to-role mapping

Group-to-role mappings translate directory group membership into Telegraf Controller roles.

1. On the Settings page, scroll to LDAP Authentication > Group role mappings.
2. Click Add mapping and provide:
   • Provider ID: a label that identifies the LDAP instance. Use the default default unless you run multiple directories.
   • Group name: the value Telegraf Controller receives in the AUTH_LDAP_ATTR_GROUPS attribute (for example cn=telegraf-admins,ou=groups,dc=example,dc=com or the bare telegraf-admins, depending on your directory).
   • Role: administrator, manager, or viewer.
3. Click Save.

When a user signs in, Telegraf Controller matches each of their groups against the mappings and assigns the highest matching role. Users without a matching group fall back to Default role or are rejected, depending on On no group match.

Bootstrap the owner against LDAP

You only need to bootstrap an LDAP-backed owner if you plan to disable local authentication. Otherwise, the default local owner can administer LDAP from the Settings page without limitation.

On first startup, set both of the following alongside the standard owner variables:

export OWNER_AUTH_PROVIDER=ldap
export OWNER_EXTERNAL_ID='uid=alice,ou=people,dc=example,dc=com'

The owner can sign in through LDAP and also retains a local password hash as a recovery credential. See Configure local authentication for the disable-local procedure.

Provider examples

export AUTH_LDAP_ENABLED=true
export AUTH_LDAP_URL=ldaps://ad.example.com:636
export AUTH_LDAP_BIND_DN='CN=svc-controller,OU=Service Accounts,DC=example,DC=com'
export AUTH_LDAP_BIND_PASSWORD='<bind-password>'
export AUTH_LDAP_USER_SEARCH_BASE='OU=Users,DC=example,DC=com'
export AUTH_LDAP_USER_SEARCH_FILTER='(sAMAccountName={{username}})'
export AUTH_LDAP_ATTR_USERNAME=sAMAccountName
export AUTH_LDAP_ATTR_EMAIL=mail
export AUTH_LDAP_ATTR_DISPLAY_NAME=displayName
export AUTH_LDAP_ATTR_GROUPS=memberOf

export AUTH_LDAP_ENABLED=true
export AUTH_LDAP_URL=ldaps://ldap.example.com:636
export AUTH_LDAP_BIND_DN='cn=svc-controller,ou=services,dc=example,dc=com'
export AUTH_LDAP_BIND_PASSWORD='<bind-password>'
export AUTH_LDAP_USER_SEARCH_BASE='ou=people,dc=example,dc=com'
export AUTH_LDAP_USER_SEARCH_FILTER='(uid={{username}})'
export AUTH_LDAP_ATTR_USERNAME=uid
export AUTH_LDAP_ATTR_EMAIL=mail
export AUTH_LDAP_ATTR_DISPLAY_NAME=cn
export AUTH_LDAP_ATTR_GROUPS=memberOf

export AUTH_LDAP_ENABLED=true
export AUTH_LDAP_URL=ldaps://ipa.example.com:636
export AUTH_LDAP_BIND_DN='uid=svc-controller,cn=users,cn=accounts,dc=example,dc=com'
export AUTH_LDAP_BIND_PASSWORD='<bind-password>'
export AUTH_LDAP_USER_SEARCH_BASE='cn=users,cn=accounts,dc=example,dc=com'
export AUTH_LDAP_USER_SEARCH_FILTER='(uid={{username}})'
export AUTH_LDAP_ATTR_USERNAME=uid
export AUTH_LDAP_ATTR_EMAIL=mail
export AUTH_LDAP_ATTR_DISPLAY_NAME=displayName
export AUTH_LDAP_ATTR_GROUPS=memberOf
export AUTH_LDAP_CA_CERT_PATH=/etc/ipa/ca.crt

Disable LDAP

To disable LDAP authentication, remove AUTH_LDAP_ENABLED (or set it to a value other than true) and restart Telegraf Controller.

• POST /api/auth/login/ldap returns 403 Forbidden after restart.
• Existing LDAP-provisioned user accounts remain in the database. They cannot sign in through LDAP until LDAP is re-enabled, but they continue to appear in the Users list.
• API tokens issued to LDAP users continue to work until the owning user is disabled or deleted.

Audit events

LDAP sign-in and sign-out emit the following audit events. They appear in the audit log when audit logging is enabled.

For details on enabling and reviewing audit events, see Audit logs.