Configure local authentication

Local authentication signs users in with a username and password stored in the Telegraf Controller database. It is enabled by default on every installation and is the only provider available in the free tier.

• Prerequisites
• Enable local authentication
• Bootstrap the owner account
• Configure login security
• Disable local authentication
• Audit events

Prerequisites

• Permission to modify the Telegraf Controller startup environment (for example, the systemd unit file or startup environment) when changing startup-only settings.
• The Owner or Administrator role to change login security from the UI.
• To disable local authentication, a configured LDAP or OIDC provider and a Telegraf Enterprise license.

Enable local authentication

Local authentication is enabled by default. The AUTH_LOCAL_ENABLED environment variable controls whether it is active and is read once at startup.

To confirm the current state, sign in as an owner or administrator and check that the Local option appears on the sign-in page. You can also call the public status endpoint:

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

The response includes a list of enabled providers. local appears when local authentication is enabled.

To explicitly enable local authentication after it has been disabled, set AUTH_LOCAL_ENABLED=true and restart Telegraf Controller.

Bootstrap the owner account

On first startup, Telegraf Controller creates the owner account using the values you provide through environment variables or interactive prompts. If no owner exists when Telegraf Controller starts and --no-interactive is set, you must supply the bootstrap values:

export OWNER_USERNAME=admin
export OWNER_EMAIL=admin@example.com
export OWNER_PASSWORD='ChangeMeOnFirstLogin!'

telegraf_controller --no-interactive

Bootstrap the owner against an external provider

If you plan to disable local authentication, set the owner’s primary provider at the same time you bootstrap the account:

export OWNER_AUTH_PROVIDER=oidc
export OWNER_EXTERNAL_ID=00u1a2b3c4d5e6f7g8h9

• OWNER_AUTH_PROVIDER accepts local (default), ldap, or oidc.
• OWNER_EXTERNAL_ID is the identifier the external provider uses for the user, such as the LDAP distinguished name (DN) or the OIDC sub claim.

The owner always retains a local password hash, even when bootstrapped against an external provider, so you can sign in directly if the provider becomes unreachable.

For full provider setup, see Configure LDAP authentication or Configure OIDC authentication.

Reset the owner password

To recover from a forgotten or compromised owner password, set RESET_OWNER_PASSWORD=true together with a new OWNER_PASSWORD value and restart Telegraf Controller.

export RESET_OWNER_PASSWORD=true
export OWNER_PASSWORD='NewOwnerPassword!'

telegraf_controller --no-interactive

Configure login security

Three settings govern local sign-in behavior:

Use the Settings page after first startup. Environment variables seed the initial values when Telegraf Controller initializes its settings. For step-by-step instructions and the password complexity matrix, see Manage settings.

These settings only apply to local authentication. LDAP and OIDC providers enforce their own credential policies.

Disable local authentication

Disable local authentication only after you have configured a working external provider and bootstrapped an owner that can sign in through it. The procedure below is irreversible without another restart.

Prerequisites for disabling

• An active Telegraf Enterprise license.
• A configured LDAP or OIDC provider that successfully signs users in.
• An owner whose authProvider is the external provider, bootstrapped with OWNER_AUTH_PROVIDER and OWNER_EXTERNAL_ID on first startup.
• A Telegraf Controller restart is required to apply the change.

Disable local authentication

Set AUTH_LOCAL_ENABLED to false and restart Telegraf Controller.

[Service]
Environment=AUTH_LOCAL_ENABLED=false

sudo systemctl daemon-reload
sudo systemctl restart telegraf-controller

export AUTH_LOCAL_ENABLED=false
telegraf_controller --no-interactive

$env:AUTH_LOCAL_ENABLED="false"
./telegraf_controller.exe --no-interactive

After restart:

• The sign-in page no longer offers the Local option.
• POST /api/auth/login/local returns 403 Forbidden.
• POST /api/auth/setup returns 403 Forbidden. Bootstrap an alternate owner only through the external provider.
• The owner can still authenticate through the external provider as long as it remains healthy.

Re-enable local authentication

Set AUTH_LOCAL_ENABLED=true and restart Telegraf Controller. The owner can then sign in with their stored password hash.

Audit events

Local 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.