These docs are for Cribl Api 4.14 and are no longer actively maintained.

See the latest version (4.15).

Authenticate with the Cribl Terraform Provider (Preview)

Preview Feature

​

The Cribl Terraform provider is a Preview feature that is still being developed. We do not recommend using it in a production environment, because the feature might not be fully tested or optimized for performance, and related documentation could be incomplete.

Please continue to submit feedback through normal Cribl support channels, but assistance might be limited while the feature remains in Preview.

For customer-managed deployments, if you’re using SSO/OpenID Connect Authentication, you must toggle on Allow login as Local User in Cribl (see Set Up Fallback Access). You’ll need to be a Local user when you authenticate.

To use https for customer-managed requests, you must configure Transport Layer Security (TLS). If you do not configure TLS, use http instead. Use http only for testing in development environments. In production, configure TLS and use https to secure your communications.

Token Management Options

​

All Cribl Terraform operations require you to authenticate with a Bearer token. In Cribl, Bearer tokens are JSON Web Tokens (JWTs). The Bearer token verifies your identity and ensures secure access to the requested resources.

• On Cribl.Cloud, Bearer tokens are valid for 24 hours.

• In customer-managed deployments, Bearer tokens expire according to the value you provide for the Auth token TTL setting at Settings > Global > General Settings > API Server Settings > Advanced. The default setting is 3600 seconds (1 hour).

To configure authentication, you can use either automatic or manual token management:

• For automatic token management, you provide your OAuth credentials to the Terraform provider. The provider uses your credentials to automatically make OAuth requests to obtain a Bearer token. When the token expires, the provider automatically refreshes the token. Automatic token management is more convenient and reliable for Terraform operations.

• For manual token management, you obtain a Bearer token in advance and provide the token directly to the Terraform provider. You are responsible for ensuring that applications refresh the Bearer token within the expiration window for each token.

Automatic token management is supported for all authentication configuration methods on Cribl.Cloud and in customer-managed deployments. The Cribl Terraform provider does not support manual token management if you use the credentials file to configure authentication.

Authenticate on Cribl.Cloud

​

To configure authentication on Cribl.Cloud, first create an API Credential. The API Credential provides a Client ID and Client Secret, which you must either provide in your configuration or use to obtain a Bearer token.

To create an API Credential:

1. Log in to Cribl.Cloud as an Owner or an Admin.

2. On the top bar, select Products, and then select Cribl.

3. In the sidebar, select Organization, and then select API Credentials.

4. Select Add Credential.

5. Enter a Name and an optional Description.

6. In the Organization Permissions drop-down menu, select a Role to use for defining Permissions for the Credential’s tokens.

   The Organization Permissions selector is available on certain plan/license tiers. Without a proper license, all tokens are granted the Admin Role.

   • If you choose the User Role, under Workspace Access, define the desired Permissions for specific Workspaces.

   • Choosing the Admin or Owner Role automatically grants admin access to all Workspaces.

7. Select Save.

The API Credentials page displays the new API Credential within a few seconds.

The API Credential includes a Client ID and a Client Secret that Organization Owners and Admins can use to generate Bearer tokens. Organization Owners and Admins can view, edit, and disable existing API Credentials. Only Owners can delete API Credentials.

The Client ID and Client Secret are sensitive information and should be kept private.

Next, decide whether you want to use automatic or manual token management. For automatic token management, you will provide your OAuth credentials (the Client ID and Client Secret from the API Credential) when you configure authentication.

For manual token management, you must obtain a Bearer token to use directly when you configure authentication. Send an API request to https://login.cribl.cloud/oauth/token, with the Client ID and Client Secret from the API Credential in the body:

curl -X POST 'https://login.cribl.cloud/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "grant_type": "client_credentials",
  "client_id": "${clientId}",
  "client_secret": "${clientSecret}",
  "audience": "https://api.cribl.cloud"
}'

As shown in the following example response, the JSON object in the response includes several attributes:

• access_token: The Bearer token to provide when you configure authentication.
• scope: The Permissions that the Bearer token grants.
• expires_in: The number of seconds until the Bearer token expires. On Cribl.Cloud, Bearer tokens expire 24 hours (86400 seconds) after they are created.
• token_type: The type of the token. On Cribl.Cloud, the value is always Bearer.

{
  "access_token": "abcdefg1234567890...exampleBearerToken",
  "scope": "user:read:workergroups user:update:workergroups user:read:connections user:update:connections user:update:workspaces user:read:workspaces",
  "expires_in": 86400,
  "token_type": "Bearer"
}

After you have the Client ID and Client Secret (for automatic token management) or a Bearer token (for manual token management), you can configure authentication using the following methods, listed in order of precedence:

1. Provider block.

2. Environment variables.

3. Credentials file (automatic token management only).

If you include a provider block in your Terraform configuration file, it has the highest precedence and will override any environment variables or credentials file that you have also configured. If you configure authentication using both environment variables and a credentials file, the Terraform provider will use the environment variables instead of the credentials file.

Provider Block (Cribl.Cloud)

​

To configure authentication directly in your Terraform configuration file, include a provider block:

provider "criblio" {

  # OAuth credentials for automatic token management
  # with optional cloud_domain
  client_id        = "your-client-id" # Replace with the Client ID for your API Credential
  client_secret    = "your-client-secret" # Replace with the Client Secret for your API Credential
  organization_id  = "your-organization-id" # Replace with your Organization ID
  workspace_id     = "your-workspace-id" # Replace with your Workspace name
  cloud_domain     = "cribl.cloud" # (Optional) Replace with the Cloud domain

  # Bearer token for manual token management
  bearer_token = "your-bearer-token" # Replace with a Bearer token
}

Environment Variables (Cribl.Cloud)

​

To configure authentication using environment variables, replace the placeholder values with your OAuth credentials (automatic token management) or a Bearer token (manual token management):

# OAuth credentials for automatic token management
export CRIBL_CLIENT_ID="your-client-id" # Replace with the Client ID for your API Credential
export CRIBL_CLIENT_SECRET="your-client-secret" # Replace with the Client Secret for your API Credential
export CRIBL_ORGANIZATION_ID="your-organization-id" # Replace with your Organization ID
export CRIBL_WORKSPACE_ID="your-workspace-name" # Replace with your Workspace name

# Bearer token for manual token management
export CRIBL_BEARER_TOKEN="your-bearer-token" # Replace with a Bearer token

Credentials File (Cribl.Cloud)

​

The credentials file method for configuring authentication supports only automatic token management. Store your OAuth credentials in ~/.cribl/credentials or ~/.cribl (legacy) with the following format:

# OAuth credentials for automatic token management
# with multiple profiles and optional cloud_domain
[default]
client_id = your-client-id # Replace with the Client ID for your API Credential
client_secret = your-client-secret # Replace with the Client Secret for your API Credential
organization_id = your-organization-id # Replace with your Organization ID
workspace = your-workspace-id # Replace with your Workspace name
cloud_domain = cribl-playground.cloud # (Optional) Replace with the Cloud domain

[profile2]
client_id = another-client-id # Replace with the Client ID for your API Credential
client_secret = another-client-secret # Replace with the Client Secret for your API Credential
organization_id = another-organization-id # Replace with your Organization ID
workspace = another-workspace-id # Replace with your Workspace name
cloud_domain = cribl.cloud # (Optional) Replace with the Cloud domain

To use a specific profile, set the CRIBL_PROFILE environment variable:

export CRIBL_PROFILE="profile2"

Authenticate in Customer-Managed Deployments

​

In customer-managed (on-prem and hybrid) deployments, you can configure authentication using the following methods (listed in order of precedence):

1. Environment variables.

2. Credentials file (automatic token management only).

If you configure authentication using both environment variables and a credentials file, the environment variables will override the credentials file configuration.

Environment Variables (Customer-Managed Deployment)

​

If you use environment variables to configure authentication, you may use eitherlogin credentials for automatic token management or a Bearer token for manual token management.

Use Automatic Token Management with Environment Variables

​

To configure authentication using automatic token management, replace the placeholder values for the following environment variables with your server URL and login credentials (username and password):

# Server URL
export CRIBL_ONPREM_SERVER_URL="http://localhost:9000"  # Replace with your server URL

# Login credentials for automatic token management
export CRIBL_ONPREM_USERNAME="your-username" # Replace with your username
export CRIBL_ONPREM_PASSWORD="your-password" # Replace with your password

In the Terraform configuration file, include the provider block with no authentication settings to ensure that the Terraform provider uses the settings from the environment variables:

provider "criblio" {
  # Do not configure authentication settings. Uses environment variables.
}

Use Manual Token Management with Environment Variables

​

To configure authentication by directly providing a Bearer token in an environment variable for manual token management, you must first send a request to the /auth/login endpoint to obtain a Bearer token.

The following example request demonstrates an /auth/login request. Replace the variables in the example request with your hostname, port, and login credentials (username and password). Your username and password are sensitive information and should be kept private.

curl -X POST 'https://${hostname}:${port}/api/v1/auth/login' \
--header 'Content-Type: application/json' \
--data '{
  "username": "${username}",
  "password": "${password}"
}'

The response is a JSON object like the following example. The value of the token attribute in the response is the Bearer token:

{
  "token": "Bearer abcdefg1234567890...exampleBearerToken",
  "forcePasswordChange": false
}

When you have a Bearer token, replace the placeholder values for the following environment variables with your server URL and the Bearer token:

# Server URL
export CRIBL_ONPREM_SERVER_URL="http://localhost:9000"  # Replace with your server URL

# Bearer token for manual token management
export CRIBL_BEARER_TOKEN="your-bearer-token" # Replace with a Bearer token

In the Terraform configuration file, include the provider block with no authentication settings to ensure that the Terraform provider uses the settings from the environment variables:

provider "criblio" {
  # Do not configure authentication settings. Uses environment variables.
}

Credentials File (Customer-Managed Deployment)

​

The credentials file method for configuring authentication supports only automatic token management. Store your login credentials (username and password) in ~/.cribl/credentials or ~/.cribl (legacy) with the following format:

# Server URL and login credentials for automatic token management
[onprem]
onprem_server_url = http://localhost:9000 # Replace with your server URL
onprem_username = your-username # Replace with your username
onprem_password = your-password # Replace with your password

To use the configured profile, set the CRIBL_PROFILE environment variable:

export CRIBL_PROFILE="onprem"

In the Terraform configuration file, include the provider block with no authentication settings to ensure that the Terraform provider uses the settings from the credentials file:

provider "criblio" {
  # Do not configure authentication settings. Uses credentials file.
}