Documentation

Kapacitor

Set up InfluxDB Enterprise authorizations

Use user-based authorizations stored and managed in InfluxDB Enterprise to authenticate requests to the Kapacitor HTTP API.

How authentication works

The process of using InfluxDB Enterprise authorizations to authenticate with Kapacitor involves three components of the enterprise TICK stack:

  1. Kapacitor parses user credentials provided in an API request.

  2. Kapacitor checks to see if the username and password currently match any user details stored in the local Kapacitor cache.

  3. If the user details are in the cache, skip to step 7.
    If user details are not in the cache, Kapacitor sends the credentials to the InfluxDB Enterprise meta API endpoint.

  4. The InfluxDB Enterprise meta server checks if the credentials are valid and, if valid, returns a user details JSON document to Kapacitor.

  5. Kapacitor checks the user details document for the correct privileges.

  6. Kapacitor caches the user details.

  7. If the user has the correct privileges, Kapacitor completes the request.
    If the user does not have the correct privileges, Kapacitor aborts the transaction and returns a 403 error with response body:

    {"error":"user <USER> does not have \"read\" privilege for API endpoint \"/kapacitor/v1/tasks\""}

Create an InfluxDB Enterprise user or role with Kapacitor permissions

Use the InfluxDB Enterprise meta API to create a user with Kapacitor permissions or to create a role with Kapacitor permissions and assign a user to that role.

The examples below use the InfluxDB Enterprise meta API to manage users and roles, but you can also use Chronograf to manage users and roles.

To interact with Kapacitor, the user or role must have one or both of the following permissions:

Create a user Create a role and assign a user

  1. Create a new InfluxDB Enterprise user
  2. Grant Kapacitor permissions to the new user

Create a new InfluxDB Enterprise user

Use the following request method and endpoint of the InfluxDB Enterprise meta API to create a new InfluxDB Enterprise user:

POST /user

Provide the following:

  • InfluxDB Enterprise meta URL: URL of the lead InfluxDB Enterprise meta node
  • Basic authentication: InfluxDB Enterprise username and password
  • Request body: JSON object with the following fields:
    • action: create
    • user: JSON object with the following fields:
      • name: Username
      • password: Password
curl --request POST https://172.17.0.2:8091/user \
  --user "admin:changeit" \
  --data '{
    "action":"create",
    "user": {
      "name":"johndoe",
      "password":"pa5sw0Rd"
    }
  }'

Grant Kapacitor permissions to the new user

Use the following request method and endpoint of the InfluxDB Enterprise meta API to grant Kapacitor-related permissions to the new user:

POST /user

Provide the following:

  • InfluxDB Enterprise meta URL: URL of the lead InfluxDB Enterprise meta node
  • Basic authentication: InfluxDB Enterprise username and password
  • Request body: JSON object with the following fields:
    • action: add-permissions
    • user: JSON object with the following fields:
      • name: Username
      • permissions: JSON object with the following fields: -"": List of permissions to add
$ curl --request POST https://172.17.0.2:8091/user \
  --user "username:password" \
  --data '{
    "action": "add-permissions",
    "user":{
      "name": "johndoe",
      "permissions": {
        "":[
          "KapacitorAPI",
          "KapacitorConfigAPI"
        ]
      }
    }
  }'
  1. Create a new InfluxDB Enterprise role
  2. Grant Kapacitor permissions to the new role
  3. Create a new InfluxDB Enterprise user
  4. Assign a user to the new role

Create a new InfluxDB Enterprise role

Use the following request method and endpoint of the InfluxDB Enterprise meta API to create a new InfluxDB Enterprise role:

POST /role

Provide the following:

  • InfluxDB Enterprise meta URL: URL of the lead InfluxDB Enterprise meta node
  • Basic authentication: InfluxDB Enterprise username and password
  • Request body: JSON object with the following fields:
    • action: create
    • role: JSON object with the following fields:
      • name: Role name
curl --request POST https://172.17.0.2:8091/role \
  --user "admin:changeit" \
  --data '{
    "action":"create",
    "user": {
      "name":"kapacitor",
    }
  }'

Grant Kapacitor permissions to the new role

Use the following request method and endpoint of the InfluxDB Enterprise meta API to grant Kapacitor-related permissions to the new role:

POST /role

Provide the following:

  • InfluxDB Enterprise meta URL: URL of the lead InfluxDB Enterprise meta node
  • Basic authentication: InfluxDB Enterprise username and password
  • Request body: JSON object with the following fields:
    • action: add-permissions
    • role: JSON object with the following fields:
      • name: Role name
      • permissions: JSON object with the following fields: -"": List of permissions to add
$ curl --request POST https://172.17.0.2:8091/user \
  --user "username:password" \
  --data '{
    "action": "add-permissions",
    "role":{
      "name": "kapacitor",
      "permissions": {
        "":[
          "KapacitorAPI",
          "KapacitorConfigAPI"
        ]
      }
    }
  }'

Create a new InfluxDB Enterprise user

Use the following request method and endpoint of the InfluxDB Enterprise meta API to create a new InfluxDB Enterprise user:

POST /user

Provide the following:

  • InfluxDB Enterprise meta URL: URL of the lead InfluxDB Enterprise meta node
  • Basic authentication: InfluxDB Enterprise username and password
  • Request body: JSON object with the following fields:
    • action: create
    • user: JSON object with the following fields:
      • name: Username
      • password: Password
curl --request POST https://172.17.0.2:8091/user \
  --user "admin:changeit" \
  --data '{
    "action":"create",
    "user": {
      "name":"johndoe",
      "password":"pa5sw0Rd"
    }
  }'

Assign a user to the new role

Use the following request method and endpoint of the InfluxDB Enterprise meta API to assign an InfluxDB Enterprise user to the new role:

POST /role

Provide the following:

  • Basic authentication: InfluxDB Enterprise username and password
  • Request body: JSON object with the following fields:
    • action: add-users
    • role: JSON object with the following fields:
      • name: Role name
      • users: List of users to add
curl --request POST  https://172.17.0.2:8091/role \
  --user "username:password" \
  --data '{
    "action": "add-users",
    "role": {
      "name": "example-role",
      "users": [
        "johndoe"
      ]
    }
  }'

Enable and configure Kapacitor authentication

Enable and configure authentication-related Kapacitor configuration options in your kapacitor.conf or with environment variables:

kapacitor.conf Environment variables

[http]
  # ...
  auth-enabled = true

[auth]
  enabled = true
  cache-expiration = "1h"
  bcrypt-cost = 4
  meta-addr = " 172.17.0.2:8091"
  meta-username = "example-influxdb-username"
  meta-password = "example-influxdb-password"
  meta-use-tls = true
  meta-ca = "/path/to/cert.ca"
  meta-cert = "/path/to/cert.cert"
  meta-key = "/path/to/cert.key"
  meta-insecure-skip-verify = false

# ...

export KAPACITOR_HTTP_AUTH_ENABLED=true
export KAPACITOR_AUTH_ENABLED=true
export KAPACITOR_AUTH_CACHE_EXPIRATION=1h
export KAPACITOR_AUTH_BCRYPT_COST=4
export KAPACITOR_AUTH_META_ADDR=172.17.0.2:8091
export KAPACITOR_AUTH_META_USERNAME=example-username
export KAPACITOR_AUTH_META_PASSWORD=example-password
export KAPACITOR_AUTH_META_USE-tls=true
export KAPACITOR_AUTH_META_CA=/path/to/cert.ca
export KAPACITOR_AUTH_META_CERT=/path/to/cert.cert
export KAPACITOR_AUTH_META_KEY=/path/to/cert.key
export KAPACITOR_AUTH_META_INSECURE_SKIP_VERIFY=false

Authenticate with Kapacitor

With authentication enabled, Kapacitor requires valid user credentials for all API requests.

Authenticate with the Kapacitor CLI

To authenticate with Kapacitor when using the kapacitor CLI, provide your username and password as part of the Kapacitor -url:

# Syntax
kapacitor -url http://<username>:<password>@localhost:9092

# Example
kapacitor -url http://admin:Pa5sw0Rd@localhost:9092

Authenticate with the Kapacitor API

To authenticate directly with the Kapacitor API, use basic authentication to provide your username and password.

# Syntax
curl --request GET http://localhost:9092/kapacitor/v1/tasks \
  -u "<username>:<password>" 

# Example
curl --request GET http://localhost:9092/kapacitor/v1/tasks \
  -u "johndoe:Pa5sw0Rd"

Was this page helpful?

Thank you for your feedback!

© 2024 InfluxData, Inc.

Where are you running InfluxDB?

Select your InfluxDB Cloud region and cluster or your InfluxDB OSS URL and we’ll customize code examples for you. Identify your InfluxDB Cloud cluster.

  • InfluxDB Cloud
  • InfluxDB OSS or Enterprise
AWS

  • US West (Oregon)

GCP
Azure
Default
Custom

For more information, see InfluxDB Cloud regions or InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following: