Cribl Stream has supported external Lightweight Directory Access Protocol (LDAP) authentication since version 2.0 was released in late 2019. LDAP directories offer many features, and it’s up to clients to implement them for compatibility. Here is a non-exhaustive list of LDAP features that Cribl Stream does not support:

• anonymous binds
• referrals
• startTLS
• multiple search bases for User search base or Group search base setting

This blog post explores how Cribl Stream implements LDAP for user authentication and assumes you have a working knowledge of the topic. We’ll start with a short section on Proxy Binding, and then dive into a detailed flow of how identification and authentication work in Cribl Stream. Finally, we’ll look behind the scenes at how Cribl Stream processes group information for RBAC purposes.

Proxy Binding in Cribl Stream

Cribl Stream’s LDAP support is designed to remain vendor-agnostic. Stream’s LDAP integration functions with Active Directory, OpenLDAP, and Oracle Internet Directory, as well as with DaaS solutions like JumpCloud.

LDAP authentication in Cribl Stream works through a proxy bind account. The bind operations that Stream performs are known as simple binds in LDAP terms; this is how Stream can integrate with the various directory servers on the market. Cribl Stream’s proxy bind account implementation offers these benefits:

• Limits access to accounts: A proxy bind account will only search for users in the specific directory sub-tree (using the User search base setting) configured by a Cribl Stream admin. A user account has to exist for authentication to initiate. Note: As a best practice, configure your proxy account to only be granted Read-Only access to the directory tree to limit the possibility of unauthorized changes to the directory by anyone who knows the password.
• Flexibility with multiple application accounts: An LDAP directory can contain multiple accounts for different applications for the same user. You can configure Cribl Stream’s LDAP settings to ensure the proxy account finds the correct user account intended for use with Cribl Stream.

Cribl Stream uses the following fields to configure your proxy account:

• Bind DN*: specifies which service account serves as the proxy bind account with the bind account’s password specified in the Password field.
• User search base*: Limits how much of the directory can be searched. It’s useful to reduce search times in large, global directories containing tens of thousands of objects. Specifying the location within the directory tree enables faster and more efficient searches
• User search filter: Limits the search results.
• Username field*: Specifies the directory attribute that is used to match the username on the Cribl Stream login page. This will differ depending on the directory used. Typically it is the cn, uid or sAMAccountName (Microsoft AD) user attribute.

*Required fields

Identification, Authentication, & Authorization in Cribl Stream

We’ll cover a detailed flow of how Cribl Stream identifies, authenticates, and authorizes users. Fair warning: there is a large degree of detail here to provide background information on the design but also to account for error conditions. The overall flow comprises two sections:

1. Identification & Authentication

2. Authorization

The illustration below outlines how a user logs into Cribl Stream which communicates with a Directory server. There are two parts each for steps 2 through 5:

A. A request sent to the directory server

B. A response back to Cribl Stream

The diagram (click to enlarge it) also highlights how a specific fallback procedure is executed in case of failure, where applicable. In Cribl Stream, there are two settings that govern if fallback is enabled and the result of the fallback attempt.

Identification & Authentication

1. A user enters their username and password into the login page and clicks Login.

2a. Cribl Stream connects to the first configured LDAP server then initiates a bind operation using the configured proxy bind account and password. Cribl Stream connects to each LDAP server in order as listed but only after the configured Connection timeout has elapsed when connecting to the current server.

2b. If Cribl Stream can’t connect to any of the LDAP servers or the proxy service account can’t successfully authenticate then:

If Fallback on fatal error is enabled then Cribl Stream authenticates the user to the local repository using the same credentials already provided.

2.b.i. If that local authentication succeeds then the user is granted access.

OR

2.b.i. If that fails then the entire login process fails and the user is not granted access.

OR

If Fallback on fatal error is disabled then the process stops and an error is displayed to the user.

3.a. If Cribl Stream successfully connects to an LDAP server and the proxy service account successfully authenticates, the proxy bind account then issues a search operation to find the person’s user object in the directory using the User search base, Username, and User search filter values from the Authentication Settings.

3.b. If the user object cannot be found then:

If Fallback on bad login is enabled then Cribl Stream attempts to authenticate the person to the local repository using the same credentials. This means the same account with the same password must exist locally for this fallback option to be successful.

3.b.i. If that local authentication succeeds then the person is granted access.

OR

3.b.i. If that fails then the entire login process fails and the person is not granted access.

OR

If Fallback on bad login is disabled the login process is considered unsuccessful and the authentication process is aborted with an error displayed to the user.

If the user object is returned in the LDAP search results it means there was a match between the value of the attribute, specified by the Username field, in the user’s object with the username provided by the person logging in.

4.a. After confirming the person’s user object exists in the directory, Cribl Stream binds with the person’s supplied credentials. If this bind is successful then the user is granted access.

4.b. If Cribl Stream can’t successfully bind as that user then the Fallback on bad login sequence replays as above.

Authorization – Part 1

At this point, the user is successfully identified and authenticated, whether via LDAP or Local authentication.

Cribl Stream always attempts to obtain group membership of the user logging in. If no group mappings exist then all users who are authenticated have defaulted to the Admin role. If the Local auth succeeded then Cribl Stream applies the appropriate RBAC mapping for Local authentication rather than LDAP authentication. But if the LDAP authentication succeeded then Cribl Stream has more steps to perform before the RBAC mapping can occur.

Cribl Stream checks if the user’s LDAP object has a memberOf attribute to obtain all group memberships. memberOf is a standard mechanism in LDAP directories for defining group membership. This attribute specifically contains DN values for each group of which the user is a member.

Note: The existence of the memberOf attribute will supersede searching for any groups even if the Group search base setting is defined, meaning that a search for groups will not be conducted if memberOf exists.

If the user object doesn’t possess a memberOf attribute and the Group search base is defined then Cribl Stream searches for group objects in the LDAP directory. This search is performed with as many of the Group-related settings as defined by a Cribl Stream administrator. This includes Group search base, Group member field, Group search filter, and Group name field.

The group search is performed by only returning groups that match the Group search filter, are within the Group search base, and contain the user (based on the User’s DN) as a member. If the Group search filter isn’t defined then at a minimum the User’s DN is used as a search filter to ensure only relevant groups are found. This is the last interaction Stream has with the directory.

If there isn’t any memberOf attribute in the user’s object and no Group search base defined, then Cribl Stream stops any further attempts at group membership processing and simply assigns the user the default role.

Note: For Cribl Stream to find the correct groups, your Directory’s group membership mechanism must be enabled by groups referencing their members’ DNs.

Here is a summary of the above information to describe what happens in Step 5 to get us back on track with detailing the steps:

5. If memberOf exists with values then do not perform a group search.

OR

5. If memberOf doesn’t exist and Group search base is defined then perform a group search.

OR

5. If memberOf doesn’t exist and Group search base is undefined then proceed with granting default role.

Authorization Part 2 – Internal Cribl Stream Processing

All steps after this point in the process are not reflected in the graphical view because they occur internally to Cribl Stream so Cribl Stream no longer needs to communicate with the directory server at this point.

6. Cribl Stream must perform some pre-processing of the group search results. This involves simply creating a list of DNs for all the groups of which the user is a member. A full list is created, rather than simply choosing, for example, the first group found, to account for situations where a user is a member of multiple groups (and thus has multiple roles) in Cribl Stream. This list will typically be short and often will contain just one entry. If Cribl Stream obtained group memberships via the memberOf attribute then this pre-processing is unnecessary before parsing the group DNs.

7. Cribl Stream now has to parse the group DN list obtained in the last step. These values are either coming from the group DN values in the memberOf attribute or the group DNs of all groups of which the user was found to be a member (but only those groups which matched the Group search filter). Cribl Stream splits the individual components of each DN based on scanning for every occurrence of ‘=’ and ‘,’ characters. It then uses the Group name field setting to determine what the group name should be to use in role mapping because role mappings don’t contain full group DNs.

Here is a concrete example using a user from Active Directory:

Given:

Group name field: CN (specified in the Cribl Stream LDAP settings)
User DN: CN=admin,CN=Users,DC=mydomain,DC=com

Example group DN from user’s memberOf attribute:

CN=admingrp,CN=Users,DC=mydomain,DC=com

After parsing the group DN Cribl Stream finds 2 CN values and splits them into 2 separate group names (this is what the group list looks like if debug logging is enabled in Cribl Stream):

["admingrp","Users"]

The correct answer that Cribl Stream should arrive at for what Active Directory holds for this user’s group membership is actually:

["admingrp"]

The reason Cribl Stream determined the wrong answer is because Cribl Stream’s current code makes an assumption there will only be 1 instance of CN within the group’s DN. But that assumption doesn’t hold true for some situations, such as in the above edge case I specifically chose where the security group happened to be located in the default CN=Users container within Active Directory. There is a defect submitted to address this; it’s a benign issue since extraneous values that are deemed as groups resulting from parsing group DNs shouldn’t have entries in the role mappings.

8. Once the group name list is created it is mapped against the LDAP roles in Cribl Stream. If memberOf didn’t exist, if it had 0 values, the group search yielded no results or the group names couldn’t be matched in the group mappings for any reason then the default role is granted. Assuming the list has at least one match to the role mappings then the user is granted a role. If the user is a member of multiple groups and there are entries in the role mappings for two or more of them, then Cribl Stream will grant multiple roles to the user thus resulting in permissions that represent a union of the granted roles’ permissions.

If you chose the wrong Group name field value, which maps to the component of the DN that contains the group name, or somehow the wrong value was otherwise obtained, then it probably won’t match any of your role mappings. In fact, although LDAP is essentially case insensitive, with some rare exceptions, JavaScript is indeed case sensitive. As such, the default Group name field value is ‘cn’ but that won’t fit all situations. So that’s one scenario where the Group name field value may be incorrect only because of case sensitivity in JavaScript.

For example, when the default Group name field value of cn is evaluated against the components of an Active Directory DN there won’t be a match because Active Directory uses upper case (CN vs cn, as shown in the example above). Therefore the Group name field must be changed to “CN” when using Active Directory.

9. Once the role(s) are granted the user is presented with the Cribl Stream landing page.

Summary – Cribl Stream LDAP Integration

LDAP authentication is a complex subject made more complex because client applications each implement it a little differently. Hopefully, this post has clarified how Cribl Stream implements LDAP authentication to make configuring your environments much easier, secure, and performant.

Here are some key points to remember:

• The only non-password setting where case matters is the Group name field.
• Your directory must either have groups that must possess an attribute that contains member DNs or the user objects need a memberOf attribute.
• Anyone who can authenticate to a directory can access Cribl Stream unless you use appropriate user/group search filters. Those who can access without successful group mapping will be given the default role. Note: The default role is Admin.
• When external auth is enabled Cribl Stream will always attempt using external auth first then only falling back to local if configured to do so.
• Ensure you have the fallback options enabled to prevent being locked out of the Cribl Stream GUI/API if there are connectivity or authentication problems.