These docs are for Cribl Iam 4.16 and are no longer actively maintained.

See the latest version (4.17).

User authentication in the Cribl Suite

On-prem deployments of the Cribl Suite support local, Splunk, LDAP, SSO/OpenID Connect, and SSO/SAML authentication methods, depending on license type.

Local Authentication

​

To set up local authentication:

1. In the sidebar, select Settings, then Global.
2. Under Access Management, select Authentication.
3. Choose Local as authentication Type.

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

For Windows Edge Nodes, the changes are persisted in a file located at C:\ProgramData\Cribl\local\cribl\auth\users.json.

This is the line format, and note that both usernames and passwords are case-sensitive:

{"username":"user","first":"Goat","last":"McGoat","roles":["admin"],"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

​

Manual password replacement is available only in on-prem deployments. In Cribl.Cloud, when logging in, you can reset your password by selecting the Forgot password? link.

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>". The product 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":"Goat","last":"McGoat","roles":["admin"],"disabled":"false","passwd":"Yrt0MOD1w8OzyMYB8WMcEleOtYESMwZw2qIZyTvueOE"}

…you’d modify the final key-value pair to something like:

{"username":"user","first":"Goat","last":"McGoat","roles":["admin"],"disabled":"false","password":"V3ry53CuR&pW9"}

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

Set Worker/Edge Node Passwords

​

In a Distributed deployment (Edge, Stream), once a Worker/Edge Node has been set to point to the Leader Node, Cribl Suite will set each Worker/Edge Node’s admin password with a randomized password that is different from the admin user’s password on the Leader Node. This is by design, as a security precaution. But it might lead to situations where administrators cannot log into a Worker/Edge Node directly, and must rely on accessing them via the Leader.

To explicitly apply a known/new password to your Stream Worker or Edge Node, you set and push a new password to the Worker Group/Fleet. Here’s how, in the Leader Node’s UI:

1. On the top bar, select Products, and then select Stream or Edge.
2. Select the desired Worker Group or Fleet.
3. On the Worker Group/Fleet submenu, select Worker Group Settings or Fleet Settings.
4. Select Local Users, then expand the desired user.
5. Update the Password and Confirm Password fields and select Save.

Every 10 seconds, the Worker/Edge Node will request an update of configuration from the Leader, and any new password settings will be included.

On Cribl.Cloud, Group Settings for customer-managed hybrid Workers include the above Local Users options, but Groups for Cribl-managed Workers in Cribl.Cloud do not. For alternatives, see the Cribl.Cloud Launch Guide and Cribl.Cloud SSO Setup docs.

Authentication Controls

​

Use the following authentication-specific controls at Settings > Global > General Settings > API Server Settings > Advanced to customize authentication behavior:

• Logout on roles change: If role-based access control is enabled, toggle on to automatically log out users when their assigned Roles change. Default is toggled on.

• Auth token TTL: Authentication tokens’ valid lifetime, in seconds. Default is 3600 (60 minutes = 1 hour); minimum is 1.

• Session idle time limit: How long to observe no user interaction before invalidating users’ session tokens, in seconds. Default is 3600 (60 minutes = 1 hour); minimum is 60.

• Login rate limit: The number of login attempts allowed over the specified unit of time. For example, to limit login attempts to 50 per minute, specify the login rate limit 50/minute. Valid units of time are second, minute, hour, and day. Default is 2/second.

• SSO/SLO callback rate limit: The number of requests to SSO and SLO callback endpoints allowed over the specified unit of time. For example, to limit requests to 10 per minute, specify 10/minute. Valid units of time are second, minute, hour, and day.

• HTTP headers: One or more custom HTTP headers to send with every response.

Token Renewal and Session Timeout

​

Here is how Cribl Suite sets tokens’ valid lifetime by applying the Auth-token TTL field’s value:

• When a user logs in, the product returns a token whose expiration time is set to {login time + Auth-token TTL value}.

• If the user is idle (no UI activity) for the configured token lifetime, they are logged out.

• As long as the user is interacting with the Cribl UI in their browser, the product continually renews the token, resetting the idle-session time limit back by the Auth-token TTL value.

The cribl.secret File

​

When Cribl Suite 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 - for example, 600.

External Authentication

​

While configuring any external auth method, make sure you don’t get locked out! Enable the Fallback on fatal error or Allow login as Local User toggle until you’re certain that external auth is working as intended. If you do get locked out, refer back to Manual Password Replacement for the remedy.

All external auth methods require certain license tiers. For details, see Pricing.

Granular Permissions and Roles are supported only with an Enterprise license. With a Standard license, all your external users are imported into Cribl as Admins.

This topic covers the following external authentication providers:

• Splunk Authentication
• LDAP Authentication
• Personal Identity Verification (PIV) Authentication

To configure single sign-on (SSO) using an identity provider (IdP) like Okta, read the SSO documentation.

Splunk Authentication

​

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

Navigate to Settings > Global > Access Management > Authentication > Type and select Splunk. This exposes the following controls.

• 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 toggled on.

• Validate certificates: When enabled, Cribl Suite will reject any certificate that the Certificate Authority (CA) for your system does not authorize. Although this control is off by default, Cribl strongly recommends that you enable it, except when you must allow untrusted (for example, self-signed) certificates.

• Fallback on fatal error: Toggle on to attempt local authentication if Splunk authentication is unsuccessful. Default is toggled off. If toggled on, the product will attempt local authentication only after a failed Splunk auth.

• Fallback on bad login (available only if Fallback on fatal error is toggled on): Attempt local authentication if the supplied user/password fails to log in on Splunk. Default is toggled off.

The Splunk search head does not need to be locally installed on the Cribl instance.

Map Splunk Roles to Cribl Teams or Roles

​

Splunk role membership alone does not define access rights in Cribl. You must use mapping to explicitly associate Splunk roles with Cribl access rights. Whether to use Team or Role mapping depends on which Cribl access control model you use:

• If you are using the Cribl Permissions model for access control, follow the instructions below to map Splunk roles to Cribl Teams.
• If you are using the legacy Roles and Policies model for access control, follow the instructions below to map Splunk roles to Cribl Roles.

LDAP Authentication

​

To set up LDAP authentication, navigate to Settings > Global > Access Management > Authentication > Type, and select LDAP. This exposes the following controls:

• Secure: Toggle on to use a secure LDAP connection (ldaps://). Toggle off for an insecure (ldap://) connection.

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

• Bind DN: Distinguished Name of entity to authenticate with LDAP server (for example, '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 (for example, 'dc=example,dc=org').

• Username field: LDAP user search field, such as cn or (cn (or uid). For Microsoft Active Directory, use sAMAccountName here.

• User search filter: LDAP search filter to apply when authenticating users. Optional, but recommended. If empty, all users in your domain will be able to log in with the default Cribl Role. For example:

  • (&(objectClass=user)(memberof=CN=StreamAdmins,OU=Groups,DC=cribl,DC=io)): Enables only users in the StreamAdmins group to log in and maps them to the specified Teams or Roles.

  • (&(group=admin)(!(department=123*))): Enables anyone in the admin group who does not have a department attribute that starts with 123 to log in.

• The following Group-related settings are required only if you are using Team or Role mapping with LDAP authentication. If you are not using Team or Role mapping, ignore these fields.

  • Group search base: Starting point to search LDAP for groups (for example, dc=example,dc=org).

  • Group member field: LDAP group search field (for example, member).

  • Group membership attribute: Attribute name of LDAP user object. Determines group member attribute’s value, which defines group’s allowed users. This field accepts dn, cn, uid, or uidNumber. If none of these are specified, falls back to dn.

  • Group search filter: LDAP search filter to apply when retrieving groups for authorization and mapping to Teams or Roles (for example, (&(cn=cribl*)(objectclass=group))).

  • Group name field: Attribute used in objects’ DNs that represents the group name (for example, cn). Cribl Suite does not directly read this attribute from group objects; rather, it must be present in your groups’ DN values. Match the attribute name’s original case (upper, lower, or mixed) when you specify it in this field. In particular, Microsoft Active Directory requires all-uppercase group names - for example, CN.

• Connection timeout (ms): Defaults to 5000.

• Reject unauthorized: Valid for secure LDAP connections. Toggle on to reject unauthorized server certificates.

• Fallback on fatal error: Attempt local authentication if LDAP authentication is down or misconfigured. Default is toggled off. If toggled on, local authentication will be attempted only after a failed LDAP auth.

• Fallback on bad login (available only if Fallback on fatal error is toggled on): Attempt local authentication if the supplied user/password fails to log in on the LDAP provider. Default is toggled off.

If you encounter SSL certificate errors when connecting to your LDAP server (such as “unable to get local issuer certificate”), you may need to configure custom CA certificates. This is common when using self-signed certificates or internal certificate authorities. You can use environmental variables to specify custom CA certificates for LDAP authentication. For details, see CA Certificates and Environment Variables.

Map LDAP Groups to Cribl Teams or Roles

​

LDAP group membership alone does not define access rights in Cribl. You must use mapping to explicitly associate LDAP groups with Cribl access rights. Whether to use Team or Role mapping depends on which Cribl access control model you use:

• If you are using the Cribl Permissions model for access control, follow the instructions below to map LDAP groups to Cribl Teams.
• If you are using the legacy Roles and Policies model for access control, follow the instructions below to map LDAP groups to Cribl Roles.

Cribl Suite evaluates only direct group membership during LDAP authentication. Team and Role mappings must reference groups that users are direct members of.

For example, if a user belongs to Group A, and Group A is a member of Group B:

• Mapping using Group A is supported because the user is a direct member of Group A.
• Mapping using Group B is not supported because the user is an indirect member of Group B through Group A.

Cribl Suite does not traverse nested group membership chains. If your environment uses nested groups, make sure that your mappings refer to groups that users belong to directly.

Personal Identity Verification (PIV) Authentication

​

Cribl supports Personal Identity Verification (PIV) authentication with an Enterprise license for an on-prem deployment.

To use PIV authentication, you must configure and enable TLS. Define your chain of trust for all Certificate Authorities (CAs) in the CA certificate path field in the TLS settings. The PEM-encoded certificate file can include multiple certificates.

PIV authentication is compatible only with LDAP. Users must exist in LDAP to successfully log in using client certificates. If you enable the Fallback on fatal error and Fallback on bad login options in the LDAP authentication settings, local username and password authentication is also available.

Cribl does not perform Online Certificate Status Protocol (OCSP) revocation checks for PIV authentication. To revoke access for PIV-authenticated users, you must remove their entries from LDAP.

Follow these steps to configure authentication with PIV credentials:

1. Configure LDAP authentication. To fall back to local login with username and password if PIV authentication fails, in the LDAP authentication settings, enable the Fallback on fatal error and Fallback on bad login options.

2. Open port 9002 to allow the browser to access the identity server. If you are using a load balancer, open port 9002 on it too.

3. Make sure that the API server’s Fully Qualified Domain Name (FQDN) is defined in the san.ip or san.dns field in the API server certificate.

4. Use the Cribl Stream command line interface (CLI) to configure and enable PIV with the auth mf sub-command. For example:

   $CRIBL_HOME/bin/cribl auth mf -e true -u '/(?:UPN:)([^,]+)(?:,|$)/' -f san -o 'https://127.0.0.1:9000'

   Copy

   In this example command:

   • e true enables PIV authentication.
   • u '/(?:UPN:)([^,]+)(?:,|$)/' is the regular expression (regex) pattern to use to extract the username from the PIV client certificate. Update the pattern according to your implementation. Cribl applies the pattern to the certificate field that you define with the -f option.
   • -f san is the certificate field from which to extract the username for authentication. Specify either san or subject, depending on your implementation.
   • -o 'https://127.0.0.1:9000' is the URL for the Cribl deployment. Update with the correct URL for your deployment.
     
     

   You can also include an -a option to specify an API server URL (for example, -a 'https://internal-fqdn'). If you do not include an -a option in your command, the API server URL defaults to the value you provide for the -o option.

5. Restart the Leader Node so that the change takes effect:

   $CRIBL_HOME/bin/cribl restart

   Copy

6. Confirm that PIV authentication is configured and enabled:

   $CRIBL_HOME/bin/cribl auth mf

   Copy

   The response indicates the PIV authentication status, along with the current configured values. Using the configured values set in the example command above, the response would be:

   PIV multi-factor authentication is enabled.
   Username field: san
   Username regex pattern: /(?:UPN:)([^,]+)(?:,|$)/
   Access control allow origin header: https://127.0.0.1:9000
   Api server url: https://127.0.0.1:9000

   Copy

   The response includes notifications for unconfigured values or issues like failure to restart or enable TLS. For example:

   PIV multi-factor authentication is enabled.
   Username field not defined. Please make sure to configure it.
   Username regex pattern: /(?:UPN:)([^,]+)(?:,|$)/
   Access control allow origin header: https://127.0.0.1:9000
   Api server url: https://127.0.0.1:9000
   You will need to restart instance before your changes take full effect.
   Warning: TLS is not enabled. PIV will not function until TLS is successfully configured and enabled.

   Copy

After you configure and enable PIV and restart the Leader Node, users can select PIV/CAC on the Cribl login screen to log in without entering a username or password. Users are prompted to enter their PIV credentials, and Cribl validates the certificates, fetches the user from LDAP, and completes login.

To disable PIV authentication:

1. Set the -e option to false using the auth mf sub-command:

   $CRIBL_HOME/bin/cribl auth mf -e false

   Copy

2. Restart the Leader Node so that the change takes effect:

   $CRIBL_HOME/bin/cribl restart

   Copy