From 21ad484c197a023406730bb0babe41fdf2a3070f Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Mon, 14 Apr 2025 18:54:38 -0500 Subject: [PATCH] feat(enterprise): Get-started using admin, database, and system tokens --- .../v3-enterprise-get-started/_index.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/content/shared/v3-enterprise-get-started/_index.md b/content/shared/v3-enterprise-get-started/_index.md index 26a1f3296..1488e6bca 100644 --- a/content/shared/v3-enterprise-get-started/_index.md +++ b/content/shared/v3-enterprise-get-started/_index.md @@ -232,6 +232,124 @@ Upon verification, the license creation, retrieval, and application are automate _During the beta period, licenses are valid until May 7, 2025._ +### Authentication and authorization + +{{% product-name %}} uses token-based authentication and authorization which is enabled by default when you start the server. +With authentication enabled, you must provide an _admin token_ or _database token_ to access the server. + +- **admin token**: Grants access to all CLI actions and API endpoints. +_ **database token**: Scoped to a specific database and grant access to write and query data in that database. + Creating a database token requires an admin token. + +After you have [started the server](#start-influxdb), you can create and manage tokens using the `influxdb3` CLI or the HTTP API. + +When you create a token InfluxDB 3 returns a token string in clear text +that you can use to authenticate CLI commands (using ) and API requests. + + +Securely store your token, as you won't be able to retrieve it later. + +To have the `influxdb3` CLI use your admin token automatically, assign it to the +`INFLUXDB3_AUTH_TOKEN` environment variable. + +> [!Important] +> +> #### Securely store your tokens +> +> For security, InfluxDB only lets you view tokens when you create them. +> InfluxDB 3 stores a hash of the token in the catalog, so you can't retrieve the token after it is created. + +#### Create an admin token + +To create an admin token, use the `influxdb3 create token` subcommand and pass the `--admin` flag--for example: + +```bash + influxdb3 create token --admin \ + --host http://{{< influxdb/host >}} +``` + +The command returns a token string that you can use to authenticate CLI commands and API requests. +Securely store your token, as you won't be able to retrieve it later. + +To have the `influxdb3` CLI use your admin token automatically, assign it to the +`INFLUXDB3_AUTH_TOKEN` environment variable. + +After you have created an admin token, you can use it to create database tokens and system tokens. + +> [!Important] +> +> #### Securely store your tokens +> +> For security, InfluxDB only lets you view tokens when you create them. +> InfluxDB 3 stores a hash of the token in the catalog, so you can't retrieve the token after it is created. + +#### Create a database token + +To create a database token, use the `influxdb3 create token` subcommand and pass the following: + +- `--permission`: Create a token with permissions +- `--name`: A unique description of the token +- _Options_, for example: + - `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration). + If an expiration isn't set, the token does not expire until revoked. + - `--token` option with the admin token to use for authentication +- Token permissions (read and write) in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: + - db:mydb:read,write + - `db:`: The `db` resource type, which specifies the token is for a database. + - `mydb`: The name of the database to grant permissions to. This part supports the `*` wildcard, which grants permissions to all databases. + - `read,write`: The permissions to grant to the token. + +The following example shows how to create a database token that expires in 90 days and has read and write permissions for all databases on the server: + +{{% code-placeholders "ADMIN_TOKEN" %}} +```bash +influxdb3 create token \ + --permission \ + --expiry 90d \ + --token ADMIN_TOKEN \ + --host http://{{< influxdb/host >}} \ + --name "rw all databases" \ + "db:*:read,write" +``` +{{% /code-placeholders %}} + +In your command, replace {{% code-placeholder-key %}} `ADMIN_TOKEN`{{% /code-placeholder-key %}} +with the admin token you created earlier. + +#### Create a system token + +A _system token_ grants read access to system information and metrics for the server, including the following HTTP API endpoints: + +- `/health` +- `/metrics` +- `/ping` + +To create a system token, use the `influxdb3 create token` subcommand and pass the following: +- `--permission`: Create a token with permissions +- `--name`: A unique description of the token +- _Options_, for example: + - `--expiry` option with the token expiration time as a [duration](/influxdb3/enterprise/reference/glossary/#duration). + If an expiration isn't set, the token does not expire until revoked. + - `--token` option with the admin token to use for authentication + - `--host` option with the server host +- Token permissions (read) in the `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example: + - system:*:read + - `db:`: The `db` resource type, which specifies the token is for a database. + - `mydb`: The name of the database to grant permissions to. This part supports the `*` wildcard, which grants permissions to all databases. + - `read,write`: The permissions to grant to the token. + + + +#### Use tokens to authorize CLI commands and API requests + +- To authenticate `influxdb3` CLI commands, use the `--token` option or assign your + token to the `INFLUXDB3_AUTH_TOKEN` environment variable for `influxdb3` to use it automatically. +- To authenticate HTTP API requests, include `Bearer ` in the `Authorization` header--for example: + + ```bash + curl \ + "http://{{< influxdb/host >}}/api/v3/query_sql?db=mydb" \ + ### Data model The database server contains logical databases, which have tables, which have columns. Compared to previous versions of InfluxDB you can think of a database as a `bucket` in v2 or as a `db/retention_policy` in v1. A `table` is equivalent to a `measurement`, which has columns that can be of type `tag` (a string dictionary), `int64`, `float64`, `uint64`, `bool`, or `string` and finally every table has a `time` column that is a nanosecond precision timestamp.