Authentication

Preview Feature

​

The Cribl SDKs are Preview features that are still being developed. We do not recommend using them in a production environment, because the features 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 features remain in Preview.

Except for calls to the /auth/login and /health endpoints, all Cribl SDK and API requests require you to authenticate with a Bearer token. In Cribl, Bearer tokens are JSON Web Tokens (JWTs).

You must include a valid Bearer token in the Authorization header of your API requests or in the appropriate configuration when initializing your SDK client to verify your identity and ensure secure access to the requested resources. The SDKs automatically manage the Authorization header for all subsequent requests once the client is properly authenticated.

Authenticate on Cribl.Cloud

​

To obtain a Bearer token to authenticate on Cribl.Cloud, first create an API Credential in Cribl. The API Credential includes the Client ID and Client Secret needed for SDK or API authentication requests. The response to the authentication request includes a 24-hour 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 and authenticate via SDK or API. Your Client ID and Secret are sensitive information and should be kept private.

Organization Owners and Admins can view, edit, and disable existing API Credentials. Only Owners can delete API Credentials.

SDK (Cribl.Cloud)

​

To obtain a 24-hour Bearer token with the Cribl Python SDK (control plane), replace the placeholder values in the example request with your API Credential Client ID and Client Secret. Base URLs are initialized during authentication, so make sure to replace the placeholder values for your Organizaton ID and Workspace name as well. Your Client ID and Secret are sensitive information and should be kept private.

If you prefer, you can create and save an .env file according to the SDK setup instructions instead to keep sensitive information out of your source code.

Authentication examples are also available for the Cribl Go and TypeScript SDKs for the control plane.

"""
Replace the placeholder values for ORG_ID, CLIENT_ID, CLIENT_SECRET,
and WORKSPACE_NAME with your Organization ID, Client ID and Secret, and
Workspace name. To get your CLIENT_ID and CLIENT_SECRET values, follow
the steps at https://docs.cribl.io/cribl-as-code/authentication/#cloud-auth.
Your Client ID and Secret are sensitive information and should be kept private.

NOTE: This example is for Cribl.Cloud deployments only.
"""

import asyncio
from cribl_control_plane import CriblControlPlane
from cribl_control_plane.models import Security, SchemeClientOauth


# Cribl.Cloud configuration: Replace the placeholder values
ORG_ID = "your-org-id"  # Replace with your Organization ID
CLIENT_ID = "your-client-id"  # Replace with your OAuth2 Client ID
CLIENT_SECRET = "your-client-secret"  # Replace with your OAuth2 Client Secret
WORKSPACE_NAME = "main"  # Replace with your Workspace name

base_url = f"https://{WORKSPACE_NAME}-{ORG_ID}.cribl.cloud/api/v1"


async def main():
    # Create authenticated SDK client with OAuth2
    client_oauth = SchemeClientOauth(
        client_id=CLIENT_ID,
        client_secret=CLIENT_SECRET,
        token_url="https://login.cribl.cloud/oauth/token",
        audience="https://api.cribl.cloud",
    )

    security = Security(client_oauth=client_oauth)
    client = CriblControlPlane(server_url=base_url, security=security)
    print(f"✅ Cribl SDK client created for Cribl.Cloud deployment")

    # Validate connection, and list all git branches
    response = await client.versions.branches.list_async()
    branches = "\n\t".join([branch.id for branch in (response.items or [])])
    print(f"✅ Client works! Your list of branches:\n\t{branches}")


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except Exception as error:
        status_code = getattr(error, "status_code", None)
        if status_code == 401:
            print("⚠️ Authentication failed! Check your CLIENT_ID and CLIENT_SECRET.")
        elif status_code == 429:
            print("⚠️ Uh oh, you've reached the rate limit! Try again in a few seconds.")
        else:
            print(f"❌ Something went wrong: {error}")

API (Cribl.Cloud)

​

To obtain a 24-hour Bearer token via the Cribl API, send the following example request to https://login.cribl.cloud/oauth/token. Replace the variables in the example request with your API Credential Client ID and Client Secret.

Your Client ID, Client Secret, and Bearer token are sensitive information and should be kept private.

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"
}'

The response is a JSON object that includes the following attributes:

• access_token: The Bearer token to use in the Authorization header for authentication in subsequent API requests.
• 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. Admins are responsible for ensuring that their applications obtain a new Bearer token within the expiration window for each token.
• 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"
}

To use the Bearer token in subsequent API requests, include it in the Authorization header, like this:

curl -X GET 'https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/system/inputs' \
--header 'Authorization: Bearer abcdefg1234567890...exampleBearerToken' \
--header 'Content-Type: application/json'

Authenticate in Customer-Managed Deployments

​

To obtain a Bearer token in a customer-managed deployment, you can send a local authentication request using your username and password credentials using the SDK or API.

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). Admins are responsible for ensuring that their applications obtain a new Bearer token within the expiration window for each token.

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 via the API.

To use https in the URL for your authentication request as shown in this example, you must configure Transport Layer Security (TLS). If you do not configure TLS, modify the example URLs to use http instead. Use http only for testing in development environments. In production, configure TLS and use https to secure your communications.

SDK (Customer-Managed Deployment)

​

To obtain a Bearer token for use with the Cribl Python SDK (control plane), replace the placeholder username and password in the example authentication request with your local user credentials (username and password). Base URLs are initialized during authentication, so make sure to replace the placeholder value for your server URL as well. Your username and password are sensitive information and should be kept private.

f you prefer, you can create and save an .env file according to the SDK setup instructions instead to keep sensitive information out of your source code.

Authentication examples are also available for the Cribl Go and TypeScript SDKs for the control plane.

"""
Replace the placeholder values for ONPREM_SERVER_URL, ONPREM_USERNAME, and
ONPREM_PASSWORD with your server URL and credentials. Your credentials are
sensitive information and should be kept private.

NOTE: This example is for customer-managed deployments only.
"""

import asyncio
from cribl_control_plane import CriblControlPlane
from cribl_control_plane.models import Security

# On-prem configuration: Replace the placeholder values
ONPREM_SERVER_URL = "http://localhost:9000"  # Replace with your server URL
ONPREM_USERNAME = "admin"  # Replace with your username
ONPREM_PASSWORD = "admin"  # Replace with your password

BASE_URL = f"{ONPREM_SERVER_URL}/api/v1"


async def main():
    # Retrieve Bearer token for authentication
    client = CriblControlPlane(server_url=BASE_URL)
    response = await client.auth.tokens.get_async(
        username=ONPREM_USERNAME, password=ONPREM_PASSWORD
    )
    token = response.token
    print(f"✅ Authenticated with on-prem server, token: {token}")

    # Create authenticated SDK client
    security = Security(bearer_auth=token)
    client = CriblControlPlane(server_url=BASE_URL, security=security)
    print(f"✅ Cribl SDK client created for on-prem server")

    # Validate connection and list all git branches
    response = await client.versions.branches.list_async()
    branches = "\n\t".join([branch.id for branch in (response.items or [])])
    print(f"✅ Client works! Your list of branches:\n\t{branches}")


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except Exception as error:
        status_code = getattr(error, "status_code", None)
        if status_code == 429:
            print("⚠️ Uh oh, you've reached the rate limit! Try again in a few seconds.")
        else:
            print(f"❌ Something went wrong: {error}")

API (Customer-Managed Deployment)

​

Run the following example request to obtain a Bearer token. Replace the variables in the example request with your hostname, port, and login credentials.

Your username, password, and Bearer token 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
}

To use the Bearer token in subsequent API requests, include it in the Authorization header, like this:

curl -X GET 'https://${hostname}:${port}/api/v1/system/inputs' \
--header 'Authorization: Bearer Bearer abcdefg1234567890...exampleBearerToken' \
--header 'Content-Type: application/json'

Authenticate and Create HEC Tokens with Python

​

Cribl Solutions Engineering developed an example script that demonstrates how use Python to authenticate to the Cribl API, make a simple POST request, and add a new HEC token. The script and instructions for usage are available in the py_hec_token_mgr GitHub repo.

To use the script, you’ll need:

• Python 3.
• The Python 3 Requests module (use brew or pip3 to install).
• A working, distributed Cribl Stream or Edge installation, with a configured Splunk HEC Source.
• An admin username and password.