Manage users and authentication

Multi-user authentication lets users log in to InfluxDB 3 Enterprise with individual credentials that issue JSON Web Tokens (JWTs). Access is governed by role-based access control (RBAC). Multi-user authentication complements, but doesn’t replace, apiv3_ token authentication.

Enable user authentication

User authentication is off by default (--user-auth-type none). To enable it, start the server with --user-auth-type set to one or both authentication methods:

# Username and password sign-in
influxdb3 serve --user-auth-type basic

# OAuth/OIDC sign-in
influxdb3 serve --user-auth-type oauth

# Both
influxdb3 serve --user-auth-type basic,oauth

none disables user authentication and can’t be combined with other values. --user-auth-type has no effect when the server starts with --without-auth.

For the complete list of authentication serve flags, see the influxdb3 serve CLI reference and configuration options.

Configure JWT signing keys

basic sign-in requires an RSA key pair to sign JWTs. Provide the key ID and private key with --jwt-key-id and --jwt-private-key. The private key must be in PKCS#1 format. Generate a compatible key with the -traditional flag:

openssl genrsa -traditional -out jwt-private-key.pem 2048

influxdb3 serve \
  --user-auth-type basic \
  --jwt-key-id 
JWT_KEY_ID
 \
  --jwt-private-key "$(cat jwt-private-key.pem)"

Replace the following:

• JWT_KEY_ID: an identifier for the key (used in the JWT kid header; any string you choose)

If only one of --jwt-key-id and --jwt-private-key is set, or the key is invalid, the server logs a warning, starts anyway, and disables password sign-in. If neither is set, it starts with password sign-in disabled and logs nothing at the default log level. oauth sign-in and apiv3_ token authentication are unaffected.

JWTs expire one hour after they’re issued.

Bootstrap the initial admin

On a new deployment with no users and no operator token, create the initial admin user and operator token with influxdb3 manage init-admin:

influxdb3 manage init-admin

init-admin only works while the cluster has no users and no operator token. On a deployment that already has an operator token (for example, one that used token authentication before you enabled user authentication), it returns 409 operator token already configured. Create the first admin user with the operator token instead:

influxdb3 create user --username 
USERNAME
 --role Admin --token 
OPERATOR_TOKEN

If you enabled only oauth sign-in (no --jwt-key-id and --jwt-private-key), pass the subject (sub) claim your identity provider issues for that person instead of a username and password:

influxdb3 manage init-admin --oauth-id 
OAUTH_SUBJECT

Replace OAUTH_SUBJECT with the sub claim your identity provider issues for that person.

init-admin prints the operator token once. Store it securely: there’s no way to retrieve it again.

For complete syntax, see the influxdb3 manage CLI reference.

Log in and out

Users authenticate with influxdb3 auth login and end their session with influxdb3 auth logout:

influxdb3 auth login

Credentials are stored at ~/.influxdb3/credentials.json and refreshed automatically.

Upgrading to 3.12: sign in again if a token is rejected

3.12 requires each JWT’s aud (audience) claim to match the cluster’s catalog UUID. Access tokens issued to basic sign-in users before upgrading to 3.12 don’t have a matching claim and are rejected after the upgrade.

Clients that call POST /api/v3/authorize/refresh with a stored refresh token get a valid access token. The influxdb3 CLI refreshes only when its stored token is within 30 minutes of expiry, so if a command is rejected after the upgrade, sign in again with influxdb3 auth login.

apiv3_ API tokens are unaffected by this change.

Optional: Authenticate with OAuth/OIDC

To delegate authentication to an OAuth/OIDC identity provider, start the server with --user-auth-type oauth (or basic,oauth) and set --oauth-issuer, --oauth-audience, and --oauth-client-id:

influxdb3 serve \
  --user-auth-type oauth \
  --oauth-issuer 
OAUTH_ISSUER_URL
 \
  --oauth-audience 
OAUTH_AUDIENCE
 \
  --oauth-client-id 
OAUTH_CLIENT_ID

Replace the following:

• OAUTH_ISSUER_URL: the identity provider’s issuer URL
• OAUTH_AUDIENCE: the audience to validate incoming OAuth tokens against
• OAUTH_CLIENT_ID: the OAuth client ID registered with the identity provider

--oauth-client-id is also required for influxdb3 auth login --oauth and for browser sign-in to the integrated Explorer UI.

For browser-based SSO through the integrated Explorer UI, also set --webui-public-uri. See Use the integrated Explorer UI.

Roles

InfluxDB 3 Enterprise includes three built-in roles–Admin, Auditor, and Member. Assign roles to users to control what they can do. For details on each role and the permissions model, see Role-based access control (RBAC).