80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
---
|
|
title: Authorization
|
|
description: >
|
|
Understand how authentication and authorization work in Telegraf Controller,
|
|
including user roles, API tokens, and endpoint security.
|
|
menu:
|
|
telegraf_controller:
|
|
name: Authorization
|
|
parent: Reference
|
|
weight: 106
|
|
related:
|
|
- /telegraf/controller/users/
|
|
- /telegraf/controller/tokens/
|
|
- /telegraf/controller/settings/
|
|
---
|
|
|
|
{{% product-name %}} uses session-based authentication for the web UI and
|
|
token-based authentication for API and Telegraf agent requests.
|
|
Both mechanisms work together to control who can access the system and what
|
|
actions they can perform.
|
|
|
|
## User roles
|
|
|
|
{{% product-name %}} enforces a four-tier role hierarchy.
|
|
Each role inherits the permissions of the roles below it, and higher roles
|
|
unlock additional administrative capabilities.
|
|
|
|
| Role | Description |
|
|
| :-------------- | :------------------------------------------------------------------------------------------------------------------- |
|
|
| **Owner** | Full system access. Manages users, tokens, and settings. Only one owner exists at a time. Created during initial setup. |
|
|
| **Administrator** | Full system access. Same capabilities as the owner except cannot transfer ownership. |
|
|
| **Manager** | Manages configurations, agents, labels, and reporting rules. Manages own API tokens. Cannot manage users or settings. |
|
|
| **Viewer** | Read-only access to configurations, agents, labels, and reporting rules. Cannot manage tokens, users, or settings. |
|
|
|
|
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.
|
|
|
|
> [!Tip]
|
|
> To change the owner of your {{% product-name %}} instance, see [Transfer ownership](/telegraf/controller/users/transfer-ownership/).
|
|
|
|
## API tokens
|
|
|
|
API tokens authenticate programmatic API requests and Telegraf agent connections
|
|
to {{% product-name %}}.
|
|
|
|
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.
|
|
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.
|
|
|
|
Tokens use the `tc-apiv1_` prefix, making them easy to identify in configuration
|
|
files and scripts.
|
|
|
|
> [!Important]
|
|
> A token value is shown only once at the time of creation.
|
|
> Store it in a secure location immediately---you cannot retrieve it later.
|
|
|
|
## Endpoint authentication
|
|
|
|
By default, {{% product-name %}} requires authentication for API endpoints.
|
|
Administrators can selectively require authentication for individual endpoint
|
|
groups:
|
|
|
|
- **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.
|
|
|
|
> [!Note]
|
|
> To configure which endpoint groups require authentication, see
|
|
> [Manage settings](/telegraf/controller/settings/).
|