Cribl LogStream – Docs

Cribl LogStream Documentation

Questions? We'd love to help you! Meet us in #Cribl Community Slack (sign up here)
Download entire manual as PDF - v2.4.4

Authentication

User authentication in LogStream

Cribl LogStream supports local, Splunk, LDAP, and SSO/OpenID Connect authentication methods, depending on license type.

Local Authentication

To set up local authentication, navigate to Settings > General Settings > Authentication Settings and select Local.

You can then manage users through the Settings > Local Users UI. All changes made to users are persisted in a file located at $CRIBL_HOME/local/cribl/auth/users.json.

Line format:

{"username":"user","first":"Elvis","last":"Bath","disabled":"false", "passwd":"Yrt0MOD1w8OzyMYB8WMcEleOtYESMwZw2qIZyTvueOE"}

The file is monitored for modifications every 60s, and will be reloaded if changes are detected.

Adding users through direct modification of the file is also supported, but not recommended.

🚧

If you edit users.json, maintain each JSON element as a single line. Otherwise, the file will not reload properly.

Manual Password Replacement

To manually add, change, or restore a password, replace the affected user's passwd key-value pair with a password key, in this format: "password":"<newPlaintext>". LogStream will hash all plaintext password(s), identified by the password key, during the next file reload, and will rename the plaintext password key.

Starting with the same users.json line above:

{"username":"user","first":"Elvis","last":"Bath","disabled":"false", "passwd":"Yrt0MOD1w8OzyMYB8WMcEleOtYESMwZw2qIZyTvueOE"}

...you'd modify the final key-value pair to something like:

{"username":"user","first":"Elvis","last":"Bath","disabled":"false", "password":"V3ry53CuR&pW9"}

Within at most one minute after you save the file, LogStream will rename the password key back to passwd, and will hash its value, re-creating something resembling the original example.

Set Worker Passwords

In a distributed deployment, once a worker has been set to point to the Master Node, LogStream will set each Worker node's admin password with a randomized password which is different from the admin user's password on the Master Node. This is by design, as a security precaution, but may lead to situations where administrators cannot log into a Worker Node directly and must rely on accessing them via the Master.

To explicitly push a known/new password to your Worker Node, set and push a new password to the Worker Group.

In the Master Node's UI:

  1. From the top menu, select Worker Groups.
  2. Select the desired Worker Group.
  3. From the Worker Groups submenu, select System Settings.
  4. Select Local Users, then expand the desired user.
  5. Update the Password field and select Save.

Every 10 seconds, the Worker Nodes will request an update of configuration from the Master and new password settings will be reflected.

Authentication Controls

You can customize authentication behavior at General Settings > API Server Settings > Advanced. The options here include:

  • Logout on Roles change: If role-based access control is enabled, determines whether users are automatically logged out of LogStream when their assigned Roles change. Defaults to Yes.

  • Auth-token TTL: Sets authentication tokens' valid lifetime, in seconds. Defaults to 3600 (60 minutes).

  • Login rate limit: Sets the number of login attempts allowed over a (selectable) unit of time. Defaults to 2/second.

  • HTTP header: Enables you to specify one or more custom HTTP headers to be sent with every response.

The cribl.secret File

When Cribl LogStream first starts, it creates a $CRIBL_HOME/local/cribl/auth/cribl.secret file. This file contains a key that is used to generate auth tokens for users, encrypt their passwords, and encrypt encryption keys.

Default local credentials are: admin/admin

❗️

Back up and secure access to this file by applying strict permissions – e.g., 600.

Splunk Authentication

Splunk authentication is very helpful when deploying in the same environment as Splunk, and requires the user to have Splunk admin role permissions. To set up Splunk authentication:

Navigate to Settings > General Settings > Authentication Settings > Type and select Splunk.

  • Host: Splunk hostname (typically a search head).

  • Port: Splunk management port (defaults to 8089).

  • SSL: Whether SSL is enabled on Splunk instance that provides authentication. Defaults to Yes.

  • Fallback on fatal error: Attempt local authentication if Splunk authentication is unsuccessful. Defaults to No. If toggled to Yes, local auth will be attempted only after a failed Splunk auth. Selecting Yes also exposes this additional option:

    • Fallback on bad login: Attempt local authentication if the supplied user/password fails to log in on Splunk. Defaults to No.

👍

The Splunk searchhead does not need to be locally installed on the LogStream instance. See also Role Mapping below.

LDAP Authentication

LDAP authentication is supported, and can be set up as follows:

Navigate to Settings > General Settings > Authentication Settings > Type, and select LDAP.

  • Secure: Enable to use a secure LDAP connections (ldaps://). Disable for an insecure (ldap://) connection.

  • LDAP servers: List of LDAP servers. Each entry should contain host:port (e.g., localhost:389).

  • Bind DN: Distinguished name of entity to authenticate with LDAP server. E.g., 'cn=admin,dc=example,dc=org'.

  • Password: Distinguished Name password used to authenticate with LDAP server.

  • User search base: Starting point to search LDAP for users, e.g., 'dc=example,dc=org'.

  • Username field: LDAP user search field, e.g., cn or (cn (or uid).

  • User search filter: LDAP search filter to apply when finding user, e.g., (&(group=admin)(!(department=123*))). Optional.

  • Group search base: Starting point to search LDAP for groups, e.g., dc=example,dc=org. Optional.

  • Group member field: LDAP group search field, e.g., member. Optional.

  • Group search filter: LDAP search filter to apply when finding group, e.g., (&(cn=cribl*)(objectclass=group)). Optional.

  • Group name field: LDAP group field, e.g., cn. If your LDAP directory uses uppercase DN component names (e.g., CN instead of cn), be sure to use the proper case for this string. (Active Directory uses all-caps naming for its object DN components.)

  • Connection timeout (ms): Defaults to 5000.

  • Reject unauthorized: Valid for secure LDAP connections. Set to Yes to reject unauthorized server certificates.

  • Fallback on fatal error: Attempt local authentication if LDAP authentication is down or misconfigured. Defaults to No. If toggled to Yes, local auth will be attempted only after a failed LDAP auth. Selecting Yes also exposes this additional option:

    • Fallback on bad login: Attempt local authentication if the supplied user/password fails to log in on the LDAP provider. Defaults to No.

📘

See also Role Mapping below.

SSO/OpenID Connect Authentication

LogStream supports SSO/OpenID user authentication (login/password) and authorization (user's group membership, which you can map to Cribl Roles). Using OpenID will change the default Log in button on the login page to a button labeled Log in with <provider> which redirects to the specified provider. Set this up as follows:

Navigate to Settings > General Settings > Authentication Settings > Type and select OpenID Connect.

  • Provider name: The name of the identity provider service. You can select Google or Okta, both supported natively. Manual entries are also allowed.

  • Audience: The Audience from provider configuration. This will be the base URL, e.g.: https://yourDomain.com:9000.

  • Client ID: The client_id from provider configuration.

  • Client secret: The client_secret from provider configuration.

  • Scope: Space-separated list of authentication scopes. The default list is: openid profile email.

  • Authentication URL: The full path to the provider's authentication endpoint. Be sure to configure the callback URL at the provider as <yourDomainUrl>/api/v1/auth/authorization-code/callback, e.g.: https://yourDomain.com:9000/api/v1/auth/authorization-code/callback.

  • Token URL: The full path to the provider's access token URL.

  • Logout URL: The full path to the provider's logout URL. Leave blank if the provider does not support logout or token revocation.

  • Validate certs: Whether to validate certificates. Defaults to Yes. Toggle to No to allow insecure self‑signed certificates.

  • Filter type: Select either Email whitelist or User info filter. This selection displays one of the following fields:

    • Email whitelist: Wildcard list of emails that are allowed access.
    • User info filter: JavaScript expression to filter against user profile attributes. E.g.: name.startsWith("someUser") && email.endsWith("domain.com")
  • Group name field: Field on the id_token that contains the user groups. Defaults to cn.

  • Allow local auth: Toggle to Yes to also users to log in using LogStream's local authentication. This enables an extra button called Log in with local user on the LogStream login page. (This option ensures fallback access for local users if SSO/OpenID authentication fails.)

Note the following details when filling in the form – for example, when using Okta:

  • <Issuer URI> is the account at the identity provider.

  • Audience is the URL of the host that will be connecting to the Issuer (e.g., https://localhost:9000). The issuer (Okta, in this example) will redirect back to this site upon authentication success or failure.

📘

See also Role Mapping below.

Cribl Cloud Authentication (Future Option)

This option in the Type drop-down is not yet functional.

❗️

To avoid possible lockout, do not configure or save Cribl Cloud authentication.

Role Mapping

This section is displayed only on distributed deployments with an Enterprise license. For details on mapping your external identity provider's configured groups to corresponding LogStream user access Roles, see External Groups and LogStream Roles. The controls here are:

  • Default role: Default LogStream Role to assign to all groups not explicitly mapped to a Role.

  • Mapping: On each mapping row, enter an external group name on the left, and select the corresponding LogStream Role on the right drop-down list. Click + Add Mapping to add more rows.

Updated 2 days ago

Authentication


User authentication in LogStream

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.