Configure OIDC authentication

OIDC authentication signs users in through an OpenID Connect identity provider using authorization code flow with PKCE. Telegraf Controller reads identity claims from the ID token and uses them to assign roles and provision accounts.

• Prerequisites
• Register a client with your OIDC provider
• Configure OIDC at startup
• Configure provisioning
• Configure group-to-role mapping
• Bootstrap the owner against OIDC
• Provider examples
• Disable OIDC
• Audit events

Prerequisites

• A valid Telegraf Enterprise license applied to your Telegraf Controller instance.
• An OIDC-compliant identity provider that supports authorization code flow with PKCE (S256).
• A registered OIDC client in your identity provider with a redirect URI that ends with /api/auth/oidc/callback.
• Permission to modify the Telegraf Controller startup environment.
• The Owner role to change OIDC settings from the Settings page.

Register a client with your OIDC provider

Before configuring Telegraf Controller, create a client (also called an application or integration) in your identity provider with the following properties:

• Flow: Authorization code with PKCE (S256). Telegraf Controller always uses PKCE and does not accept a provider that requires implicit or hybrid flows.
• Redirect URI: The base URL of your Telegraf Controller instance followed by /api/auth/oidc/callback. Example: https://controller.example.com/api/auth/oidc/callback.
• Scopes: At minimum openid, profile, and email. Include any provider-specific scope required to emit a groups claim.
• Claims: Ensure the ID token includes a stable subject (sub), the user’s email (email), and a groups list (default claim name groups).

Copy the client ID and client secret from the provider. You will pass them to Telegraf Controller in the next step.

Configure OIDC at startup

Set the OIDC environment variables before starting Telegraf Controller.

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

Apply the configuration

[Service]
Environment=AUTH_OIDC_ENABLED=true
Environment=AUTH_OIDC_ISSUER=https://idp.example.com
Environment=AUTH_OIDC_CLIENT_ID=telegraf-controller
Environment=AUTH_OIDC_CLIENT_SECRET=<client-secret>
Environment=AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
Environment=AUTH_OIDC_DISPLAY_NAME=Example IdP

sudo systemctl daemon-reload
sudo systemctl restart telegraf-controller

export AUTH_OIDC_ENABLED=true
export AUTH_OIDC_ISSUER=https://idp.example.com
export AUTH_OIDC_CLIENT_ID=telegraf-controller
export AUTH_OIDC_CLIENT_SECRET='<client-secret>'
export AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
export AUTH_OIDC_DISPLAY_NAME='Example IdP'

telegraf_controller --no-interactive

$env:AUTH_OIDC_ENABLED="true"
$env:AUTH_OIDC_ISSUER="https://idp.example.com"
$env:AUTH_OIDC_CLIENT_ID="telegraf-controller"
$env:AUTH_OIDC_CLIENT_SECRET="<client-secret>"
$env:AUTH_OIDC_REDIRECT_URI="https://controller.example.com/api/auth/oidc/callback"
$env:AUTH_OIDC_DISPLAY_NAME="Example IdP"

./telegraf_controller.exe --no-interactive

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

• Settings > OIDC Authentication shows the redacted configuration and reports the issuer as discovered.
• The sign-in page shows a Sign in with <display-name> button.

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 OIDC user signs in. Configure them on the Settings > OIDC Authentication panel.

To update provisioning settings:

1. Sign in as an Owner or Administrator.
2. Navigate to the Settings page.
3. In the OIDC 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 values from the OIDC groups claim into Telegraf Controller roles.

1. On the Settings page, scroll to OIDC Authentication > Group role mappings.
2. Click Add mapping and provide:
   • Provider ID: a label that identifies the OIDC provider instance. Use the default default unless you run multiple providers.
   • Group name: the exact string the provider emits in the groups claim (for example telegraf-admins).
   • Role: administrator, manager, or viewer.
3. Click Save.

When a user signs in, Telegraf Controller matches each group in the token 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 OIDC

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

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

export OWNER_AUTH_PROVIDER=oidc
export OWNER_EXTERNAL_ID='00u1a2b3c4d5e6f7g8h9'

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

Provider examples

The values shown for each provider are starting points. Use the redirect URI for your own Telegraf Controller installation and confirm that the groups claim you choose is actually emitted by your provider.

export AUTH_OIDC_ENABLED=true
export AUTH_OIDC_ISSUER=https://example.okta.com
export AUTH_OIDC_CLIENT_ID=0oaXXXXXXXXXXXXXXXXX
export AUTH_OIDC_CLIENT_SECRET='<client-secret>'
export AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
export AUTH_OIDC_SCOPES='openid profile email groups'
export AUTH_OIDC_GROUPS_CLAIM=groups
export AUTH_OIDC_DISPLAY_NAME=Okta

export AUTH_OIDC_ENABLED=true
export AUTH_OIDC_ISSUER=https://example.us.auth0.com/
export AUTH_OIDC_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXX
export AUTH_OIDC_CLIENT_SECRET='<client-secret>'
export AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
export AUTH_OIDC_SCOPES='openid profile email'
export AUTH_OIDC_GROUPS_CLAIM='https://controller.example.com/groups'
export AUTH_OIDC_DISPLAY_NAME=Auth0

export AUTH_OIDC_ENABLED=true
export AUTH_OIDC_ISSUER=https://keycloak.example.com/realms/telegraf
export AUTH_OIDC_CLIENT_ID=telegraf-controller
export AUTH_OIDC_CLIENT_SECRET='<client-secret>'
export AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
export AUTH_OIDC_SCOPES='openid profile email'
export AUTH_OIDC_GROUPS_CLAIM=groups
export AUTH_OIDC_DISPLAY_NAME=Keycloak

export AUTH_OIDC_ENABLED=true
export AUTH_OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
export AUTH_OIDC_CLIENT_ID=<application-id>
export AUTH_OIDC_CLIENT_SECRET='<client-secret>'
export AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
export AUTH_OIDC_SCOPES='openid profile email'
export AUTH_OIDC_GROUPS_CLAIM=groups
export AUTH_OIDC_DISPLAY_NAME='Microsoft Entra ID'

export AUTH_OIDC_ENABLED=true
export AUTH_OIDC_ISSUER=https://accounts.google.com
export AUTH_OIDC_CLIENT_ID=<client-id>.apps.googleusercontent.com
export AUTH_OIDC_CLIENT_SECRET='<client-secret>'
export AUTH_OIDC_REDIRECT_URI=https://controller.example.com/api/auth/oidc/callback
export AUTH_OIDC_SCOPES='openid profile email'
export AUTH_OIDC_DISPLAY_NAME='Google Workspace'

Disable OIDC

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

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

Audit events

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