Authentication and authorization

Telegraf Controller distinguishes two security questions:

• Authentication: who is making this request? Verified by a sign-in flow (local, LDAP, or OIDC) or by a presented API token.
• Authorization: what is the authenticated identity allowed to do? Determined by the user’s role and by endpoint-level access policies.

This page is the reference for both. For task-based instructions, see Authentication and Manage users.

• Authentication providers
• Identity model
• User roles
• API tokens
• Session-only endpoints
• Endpoint authentication
• License management

Authentication providers

Telegraf Controller supports three authentication providers that can run individually or together:

Each provider is enabled at startup with a dedicated environment variable (AUTH_LOCAL_ENABLED, AUTH_LDAP_ENABLED, AUTH_OIDC_ENABLED). Provider transport settings are read once at startup and immutable until restart. Provisioning rules and group-to-role mappings are stored in the database and editable at runtime from the Settings page.

For setup instructions, see:

• Configure local authentication
• Configure LDAP authentication
• Configure OIDC authentication

Identity model

Every user account carries an authProvider (local, ldap, or oidc) and, for external providers, an externalId that links the account to the identity in the source directory or identity provider:

• Local users have a stored password hash and are subject to the configured password complexity, lockout, and reset policies.
• LDAP users have no password hash; authentication is delegated to the LDAP server. The externalId is the user’s distinguished name (DN).
• OIDC users have no password hash; authentication is delegated to the OIDC provider. The externalId is the sub claim from the ID token.

First-time sign-in and provisioning

When an LDAP or OIDC user signs in for the first time, Telegraf Controller applies the provider’s provisioning strategy to decide whether to create a Telegraf Controller account:

• invite_only: requires a matching pending invite (default).
• domain_restricted: admits invited users; otherwise requires an email domain in the allow list.
• auto_create: creates an account for any user the provider authenticates.

The provider’s default role and group-to-role mappings determine the new account’s role.

For setup details, see Authentication.

Owner account behavior

The owner is the only account that:

• Always retains a local password hash, even if its primary authProvider is ldap or oidc. The hash provides a recovery credential if the external provider becomes unreachable.
• Cannot be downgraded by group-to-role mappings. Owner is reserved.
• Cannot be auto-linked from an external provider. Account-takeover protection prevents an external sign-in from claiming the owner record.

Only the owner can change the LDAP and OIDC sections of the Settings page (PATCH /api/auth/settings). Administrators can change local login security but not external provider configuration.

User roles

Telegraf Controller enforces a four-tier role hierarchy. Each role inherits the permissions of the roles below it, and higher roles unlock additional administrative capabilities.

Only one owner can exist at a time. The owner account is created during initial setup and cannot be deleted. If you need to change the owner, the current owner must transfer ownership to another user.

API tokens

API tokens authenticate programmatic API requests and Telegraf agent connections to Telegraf Controller.

Each token is scoped to the user who created it. The token’s effective permissions are restricted to the creating user’s role. A token cannot exceed the permissions of its owner. When a token is created, the requested permissions are clamped to the user’s role: a wildcard such as *:* or license:* expands to the permissions the role holds, and a request authenticated with a token cannot create a token broader than itself. If a user’s role changes to a role with less permissions, all of that user’s existing tokens are automatically updated with restricted permissions or revoked to match the new role. After an ownership transfer, the former owner’s tokens are re-clamped to the Administrator role.

Token management also depends on how the request is authenticated. Owners and Administrators signed in with a session can list, revoke, delete, and reassign any user’s tokens. A request authenticated with an API token manages only the tokens of the user it belongs to, whatever its permissions, and cannot reassign tokens. See Token visibility.

Tokens use the tc-apiv1_ prefix, making them easy to identify in configuration files and scripts.

API tokens are independent of the authentication provider that created the underlying user account. An LDAP user, an OIDC user, and a local user all issue tokens the same way.

Session-only endpoints

Endpoints that act on the signed-in user’s own account or on instance ownership accept only an interactive session, never an API token. A request to one of these endpoints with an API token returns 403 Forbidden with the message This endpoint requires an interactive session, even when the token holds the matching permissions.

Endpoint authentication

By default, Telegraf Controller requires authentication for API endpoints. Operators can selectively disable authentication for individual endpoint groups at startup:

• Agents: agent management endpoints
• Configs: configuration management endpoints
• Labels: label management endpoints
• Reporting rules: reporting rule management endpoints
• Heartbeat: agent heartbeat endpoints

When authentication is enabled for an endpoint group, every request to that group must include a valid API token or an active session.

Endpoint authentication policy is independent of the user authentication provider configuration. Disabling endpoint authentication for a group removes the requirement to present a token or session regardless of which provider would otherwise be used.

Endpoint authentication is controlled exclusively by the --disable-auth-endpoints CLI flag or DISABLED_AUTH_ENDPOINTS environment variable, read once at startup and immutable at runtime. To change which endpoint groups skip authentication, update the value and restart Telegraf Controller.

License management

Telegraf Controller exposes two permission resources for the Telegraf Enterprise license:

Only the Owner can apply, replace, or remove a license.

Any authenticated user, including Viewers, can call GET /api/license/entitlements to read the current entitlements and usage. This endpoint is intended for monitoring and capacity-planning scripts.

Security advisories

Telegraf Controller exposes one permission resource for security advisories, a Telegraf Enterprise feature:

Without a valid license, every security advisory endpoint returns 403 Forbidden regardless of role.