Documentation

InfluxDB Clustered

Set up administrative authentication

  • Install InfluxDB Clustered
  • Phase 4: Secure your cluster

To manage administrative access to your InfluxDB cluster, integrate your cluster with an OAuth 2.0 identity provider. Use your identity provider to create OAuth2 accounts for all users who need administrative access to your InfluxDB cluster. Administrative access lets users perform actions like creating databases and database tokens (which provide read and write access to databases).

InfluxData has tested with the following identity providers, but any provider that meets the requirements should work:

Identity providers can be deployed with your InfluxDB cluster or run externally. If you choose to deploy your provider with your InfluxDB cluster, the process outlined below should be done after your initial InfluxDB cluster deployment.

Identity provider requirements

To integrate an identity provider with your InfluxDB Cluster, it must meet the following requirements:

Identity provider credentials

To access the OAuth2 server, InfluxDB requires the following OAuth2 connection credentials:

  • Client ID
  • JWKS endpoint
  • Device authorization endpoint
  • Token endpoint

Set up your identity provider

Setup instructions are provided for the following:

Keycloak Microsoft Entra ID

Keycloak

To use Keycloak as your identity provider:

  1. Create a Keycloak realm
  2. Create a Keycloak client with device flow enabled
  3. Create users that need administrative access to your InfluxDB cluster
  4. Configure InfluxDB Clustered to use Keycloak

Create a Keycloak realm

See Creating a realm in the Keycloak documentation.

Create a Keycloak client with device flow enabled

  1. In the Keycloak Admin Console, navigate to Clients and then click Create Client.

  2. In the General Settings configuration step:

    1. Set the Client type to OpenID Connect.
    2. Enter a Client ID, Save your client ID to be used later.
    3. Optional: Enter a Name and Description for the client.
    4. Click Next.

  3. In the Capability configuration step, enable the OAuth 2.0 Device Authorization Grant authentication flow, and then click Next.

  4. In the Login settings step, you don’t need to change anything. Click Save.

Create users

See Creating users in the Keycloak documentation.

Find user IDs with Keycloak

To find the user IDs with Keycloak, use the Keycloak Admin Console or the Keycloak REST API.

Keycloak Admin Console
  1. In the Keycloak Admin Console, navigate to your realm
  2. Select Users in the left navigation.
  3. Select the user you want to find the ID for.
  4. Select the Details tab. The user ID is listed here.
Keycloak REST API

Send a GET request to the Keycloak REST API /users endpoint to fetch the ID of a specific user. Provide the following:

  • Query parameters
    • username: Username to retrieve information about
curl https://
KEYCLOAK_HOST
/auth/admin/realms/
KEYCLOAK_REALM
/users?username=
KEYCLOAK_USERNAME

Replace the following:

  • KEYCLOAK_HOST: the Keycloak host and port (host:port)
  • KEYCLOAK_REALM: the Keycloak realm
  • KEYCLOAK_USERNAME: the Keycloak username to retrieve

Configure InfluxDB Clustered to use Keycloak

Run the following command to retrieve a JSON object that contains the OpenID configuration of your Keycloak realm:

curl https://
KEYCLOAK_HOST
/realms/
KEYCLOAK_REALM
/.well-known/openid-configuration

View example response body

The following are important fields in the JSON object that are necessary to connect your InfluxDB cluster and administrative tools to Keycloak:

Microsoft Entra ID

To use Microsoft Entra ID as your identity provider:

  1. Create a new tenant in Microsoft Entra ID
  2. Add users that need administrative access to your InfluxDB cluster
  3. Register a new application with device code flow enabled
  4. Configure InfluxDB Clustered to use Microsoft Entra ID

Create a new tenant in Microsoft Entra ID

See Create a new tenant in Microsoft Entra ID in the Microsoft Azure documentation. Copy and store your Microsoft Entra Tenant ID.

Add users that need administrative access to your InfluxDB cluster

See Add or delete users in the Microsoft Azure documentation.

Find user IDs with Microsoft Entra ID

For Microsoft Entra ID, the unique user ID is the Microsoft ObjectId (OID). To download a list of user OIDs:

  1. In the Microsoft Azure Portal, select Users in the left navigation.
  2. Select users you want OIDs for and click Download Users.

In the downloaded CSV file, user OIDs are provided in the id column.

Register a new application with device code flow enabled

  1. In the Microsoft Azure Portal, select App Registrations in the left navigation.
  2. Click New Registration and enter a name for a new application to handle authentication requests.
  3. Click Register Application. Copy and store your Application (Client) ID.
  4. In your registered application, click Authentication in the left navigation.
  5. Under Advanced Settings, set Allow public client flows to Yes. This enables the use of the device code flow for logging in to your InfluxDB cluster.

Configure InfluxDB Clustered to use Microsoft Entra ID

Use the following command to retrieve a JSON object that contains the OpenID configuration of your Microsoft Entra tenant:

curl https://login.microsoftonline.com/
AZURE_TENANT_ID
/v2.0/.well-known/openid-configuration

Replace AZURE_TENANT_ID with your Microsoft Entra tenant ID.

View example response body

The following are important fields in the JSON object that are necessary to connect your InfluxDB cluster and administrative tools to Keycloak:

Configure your cluster to connect to your identity provider

To connect your InfluxDB cluster to your OAuth2 provider, update your AppInstance resource with the required credentials. Modify your AppInstance resource directly or, if using the InfluxDB Clustered Helm chart, update your values.yaml.

AppInstance Helm

Provide values for the following fields in your AppInstance resource:

  • spec.package.spec.admin
    • identityProvider: Identity provider name. If using Microsoft Entra ID (formerly Azure Active Directory), set the name to azure.
    • jwksEndpoint: JWKS endpoint provide by your identity provider.
    • users: List of OAuth2 users to grant administrative access to your InfluxDB cluster. IDs are provided by your identity provider.

Below are examples for Keycloak, Auth0, and Microsoft Entra ID, but other OAuth2 providers should work as well:

Keycloak Auth0 Microsoft Entra ID

apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      admin:
        identityProvider: keycloak
        jwksEndpoint: |-
          https://
KEYCLOAK_HOST
/auth/realms/
KEYCLOAK_REALM
/protocol/openid-connect/certs          
        users:
          # All fields are required but `firstName`, `lastName`, and `email` can be
          # arbitrary values. However, `id` must match the user ID provided by Keycloak.
          - id: 
KEYCLOAK_USER_ID

            firstName: Marty
            lastName: McFly
            email: mcfly@influxdata.com

Replace the following:

  • KEYCLOAK_HOST: Host and port of your Keycloak server
  • KEYCLOAK_REALM: Keycloak realm
  • KEYCLOAK_USER_ID: Keycloak user ID to grant InfluxDB administrative access to
apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      admin:
        identityProvider: auth0
        jwksEndpoint: |-
          https://
AUTH0_HOST
/.well-known/openid-configuration          
        users:
          - 
AUTH0_USER_ID

Replace the following:

  • AUTH0_HOST: Host and port of your Auth0 server
  • AUTH0_USER_ID: Auth0 user ID to grant InfluxDB administrative access to
apiVersion: kubecfg.dev/v1alpha1
kind: AppInstance
# ...
spec:
  package:
    spec:
      admin:
        identityProvider: azure
        jwksEndpoint: |-
          https://login.microsoftonline.com/
AZURE_TENANT_ID
/discovery/v2.0/keys          
        users:
          - 
AZURE_USER_ID

Replace the following:

Provide values for the following fields in your values.yaml:

  • admin
    • identityProvider: Identity provider name. If using Microsoft Entra ID (formerly Azure Active Directory), set the name to azure.
    • jwksEndpoint: JWKS endpoint provide by your identity provider.
    • users: List of OAuth2 users to grant administrative access to your InfluxDB cluster. IDs are provided by your identity provider.

Below are examples for Keycloak, Auth0, and Microsoft Entra ID, but other OAuth2 providers should work as well:

Keycloak Auth0 Microsoft Entra ID

admin:
  # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc
  # Note for Azure Active Directory it must be exactly "azure"
  identityProvider: keycloak
  # The JWKS endpoint provided by the Identity Provider
  jwksEndpoint: |-
    https://
KEYCLOAK_HOST
/auth/realms/
KEYCLOAK_REALM
/protocol/openid-connect/certs    
  # The list of users to grant access to Clustered via influxctl
  users:
    # All fields are required but `firstName`, `lastName`, and `email` can be
    # arbitrary values. However, `id` must match the user ID provided by Keycloak.
    - id: 
KEYCLOAK_USER_ID

      firstName: Marty
      lastName: McFly
      email: mcfly@influxdata.com

Replace the following:

  • KEYCLOAK_HOST: Host and port of your Keycloak server
  • KEYCLOAK_REALM: Keycloak realm
  • KEYCLOAK_USER_ID: Keycloak user ID to grant InfluxDB administrative access to
admin:
  # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc
  # Note for Azure Active Directory it must be exactly "azure"
  identityProvider: auth0
  # The JWKS endpoint provided by the Identity Provider
  jwksEndpoint: |-
    https://
AUTH0_HOST
/.well-known/openid-configuration    
  # The list of users to grant access to Clustered via influxctl
  users:
    - 
AUTH0_USER_ID

Replace the following:

  • AUTH0_HOST: Host and port of your Auth0 server
  • AUTH0_USER_ID: Auth0 user ID to grant InfluxDB administrative access to
admin:
  # The identity provider to be used e.g. "keycloak", "auth0", "azure", etc
  # Note for Azure Active Directory it must be exactly "azure"
  identityProvider: azure
  # The JWKS endpoint provided by the Identity Provider
  jwksEndpoint: |-
    https://login.microsoftonline.com/
AZURE_TENANT_ID
/discovery/v2.0/keys    
  # The list of users to grant access to Clustered via influxctl
  users:
    - 
AZURE_USER_ID

Replace the following:

For more information about managing users in your InfluxDB Cluster, see Manage users.

Apply your configuration changes

Use kubectl or helm to apply your configuration changes and connect your InfluxDB cluster to your identity provider.

kubectl Helm

kubectl apply \
  --filename myinfluxdb.yml \
  --namespace influxdb

helm upgrade \
  influxdata/influxdb3-clustered \
  -f ./values.yml \
  --namespace influxdb

Configure influxctl

The influxctl CLI lets you perform administrative actions such as creating databases or database tokens. All influxctl commands are first authorized using your identity provider. Update your influxctl configuration file to connect to your identity provider.

The following examples show how to configure influxctl for various identity providers:

Keycloak Auth0 Microsoft Entra ID

[[profile]]
    name = "default"
    product = "clustered"
    host = "cluster-host.com" # InfluxDB cluster host
    port = "8086" # InfluxDB cluster port

    [profile.auth.oauth2]
        client_id = "
KEYCLOAK_CLIENT_ID
"
        device_url = "https://KEYCLOAK_HOST/realms/
KEYCLOAK_REALM
/protocol/openid-connect/auth/device"
        token_url = "https://KEYCLOAK_HOST/realms/
KEYCLOAK_REALM
/protocol/openid-connect/token"

[[profile]]
    name = "default"
    product = "clustered"
    host = "cluster-host.com" # InfluxDB cluster host
    port = "8086" # InfluxDB cluster port

    [profile.auth.oauth2]
        client_id = "
AUTH0_CLIENT_ID
"
        client_secret = "
AUTH0_CLIENT_SECRET
"
        device_url = "https://
AUTH0_HOST
/oauth/device/code"
        token_url = "https://
AUTH0_HOST
/oauth/token"

[[profile]]
    name = "default"
    product = "clustered"
    host = "cluster-host.com" # InfluxDB cluster host
    port = "8086" # InfluxDB cluster port

    [profile.auth.oauth2]
        client_id = "
AZURE_CLIENT_ID
"
        scopes = ["
AZURE_CLIENT_ID
/.default"]
        device_url = "https://login.microsoftonline.com/
AZURE_TENANT_ID
/oauth2/v2.0/devicecode"
        token_url = "https://login.microsoftonline.com/
AZURE_TENANT_ID
/oauth2/v2.0/token"

Refresh your admin token

In preparation for moving into production, we strongly recommend revoking your cluster’s admin token used to authorize with your cluster in the earlier phases of the InfluxDB Clustered installation process and generate a new admin token.

For detailed instructions, see Revoke an admin token.

Test your authorization flow

To test your identity provider integration and ensure administrative access is correctly authorized, run any influxctl command that requires administrative authentication–for example:

influxctl token list

You are directed to authorize with your identity provider before the command executes and returns results. If authorized correctly, the command should run successfully.

Was this page helpful?

Thank you for your feedback!

© 2024 InfluxData, Inc.

What is your InfluxDB cluster URL?

Enter your InfluxDB cluster URL and we’ll update code examples for you.

Enter cluster URL

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.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements

InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered