Skip to main content
Version: 3.2

Roles

Define and manage access-control roles and policies


Cribl LogStream offers role-based access control (RBAC) to serve these common enterprise goals:

  • Security: Limit the blast radius of inadvertent or intentional errors, by restricting each user's actions to their needed scope within the application.

  • Accountability: Ensure compliance, by restricting read and write access to sensitive data.

  • Operational efficiency: Match enterprise workflows, by delegating access over subsets of objects/resources to appropriate users and teams.

Role-based access control is enabled only on distributed deployments with an Enterprise license. With other license types and/or single-instance deployments, all users will have full administrative privileges.

RBAC Concepts

LogStream's RBAC mechanism is designed around the following concepts, which you manage in the UI:

  • Roles: Logical entities that are associated with one or multiple Policies (groups of permissions). You use each Role to consistently apply these permissions to multiple LogStream users.

  • Policies: A set of permissions. A Role that is granted a given Policy can access, or perform an action on, a specified LogStream object or objects.

  • Permissions: Access rights to navigate to, view, change, or delete specified objects in LogStream.

  • Users: You map Roles to LogStream users in the same way that you map user groups to users in LDAP and other common access-control frameworks.

Users are independent LogStream objects that you can configure even without RBAC enabled. For details, see Local Users.

How LogStream RBAC Works

LogStream RBAC is designed to grant arbitrary permissions over objects, attributes, and actions at arbitrary levels.

As of v. 2.4.x, Roles are customizable only down to the Worker Group level. E.g., you can grant Edit permission on Worker Group WG1 to User A and User B, but cannot grant them finer-grained permissions on child objects such as Pipelines, Routes, etc.

LogStream's UI will be presented differently to users who are assigned Roles that impose access restrictions. Controls will be visible but disabled, and search and log results will be limited, depending on each user's permissions.

Access to the same objects via LogStream's API and CLI will be similarly filtered, with appropriate error reporting. E.g., if a user tries to commit and deploy changes on a Worker Group where they are not authorized, they might receive a CLI error message like this: git commit-deploy command failed with err: Forbidden

LogStream Roles can be integrated with external authorization/IAM mechanisms, such as LDAP and OIDC and mapped to their respective groups, tags, etc.

Using Roles

LogStream ships with a set of default Roles, which you can supplement.

Default Roles

These Roles ship with LogStream by default:

NameDescription
adminSuperusers – authorized to do anything and everything in the system.
owner_allRead/write access to (and Deploy permission on) all Worker Groups.
editor_allRead/write access to all Worker Groups.
reader_allRead-only access to all Worker Groups.
collect_allAbility to run existing collection jobs on all Worker Groups.
gitopsAbility to sync the LogStream deployment to a remote Git repository.
notification_adminRead/write access to all Notifications.
userDefault role that gets only a home/landing page to authenticate. This is a fallback for users who have not yet been assigned a higher role by an admin.

Cribl strongly recommends that you do not edit or delete these default roles. However, you can readily clone them (see Clone Role below), and modify the duplicates to meet your needs.

Initial Installation or Upgrade

When you first install LogStream with the prerequisites to enable RBAC (Enterprise license and distributed deployment), you will be granted the admin role. Using this role, you can then define and apply additional roles for other users.

You will similarly be granted the admin role upon upgrading an existing LogStream installation from pre-2.4 versions to v. 2.4 or higher. This maintains backwards-compatible access to everything your organization has configured under the previous LogStream version's single role.

Adding and Modifying Roles

In a distributed environment, you manage Roles at the Leader level, for the entire deployment. On the Leader Node, select global ⚙️ Settings (lower left) > Access Management > Roles.

Manage Roles page

To add a new Role, click + Add New at the upper right. To edit an existing Role, click anywhere on its row. Here again, either way, the resulting modal offers basically the same options.

Add/edit Role modal

The options at the modal's top and bottom are nearly self-explanatory:

Role name: Unique name for this Role.

Description: Optional free-text description.

Delete Role: And...it's gone. (But first, there's a confirmation prompt. Also, you cannot delete a Role assigned to an active user.)

Clone Role: Opens a New role version of the modal, duplicating the Description and Policies of the Role you started with.

The modal's central Policies section (described below) is its real working area.

Adding and Modifying Policies

The Policies section is an expandable table. In each row, you select a Policy using the left drop-down, and apply that Policy to objects (i.e., assign permissions on those objects) using the right drop-down.

Let's highlight an example from the above screen capture of LogStream's built-in Roles: The editor_all Role has the GroupEdit Policy, with permission to exercise it on any and all Worker Groups (as indicated by the * wildcard).

Policies on the left, objects on the right

To add a new Policy to a Role:

  1. Click + Add Policy to add a new row to the Policies table.

  2. Select a Policy from the left column drop-down.

  3. Accept the default object on the right; or select one from the drop-down.

To modify an already-assigned Policy, just edit its row's drop-downs in the Policies table.

To remove a Policy from the Role, click its close box at right.

In all cases, click Save to confirm your changes and close the modal.

Default Policies

In the Policies table's left column, the drop-down offers the following default Policies:

NameDescription
GroupReadThe most basic Worker Group-level permission. Enables users to view a Worker Group and/or its configuration.
GroupEditBuilding on GroupRead, grants the ability to also change and commit a Worker Group's configuration.
GroupFullBuilding on GroupEdit, grants the ability to also deploy a Worker Group.
GroupCollectGrants the ability to run Collectors on a Worker Group.
* (wildcard)Grants all permissions on associated objects.

Objects and Permissions

In the Policies table's right column, use the drop-down to select the LogStream objects on which the left column's Policy will apply. (Remember that in v. 2.4, the objects available for selection are specific Worker Groups, or a wildcard representing all Worker Groups.) For example:

  • Worker Group <id>
  • NewGroup2
  • default (Worker Group)
  • * (all Worker Groups)

Extending Default Roles

Here's a basic example that ties together the above concepts and facilities. It demonstrates how to add a Role whose permissions are restricted to a particular Worker Group.

Here, we've cloned the editor_all Role that we unpacked above. We've named the clone editor_default.

We've kept the GroupEdit Policy from editor_all. But in the right column, we're restricting its object permissions to the default Worker Group that ships with LogStream.

Cloning a default Role

You can readily adapt this example to create a Role that has permissions on an arbitrarily named Worker Group of your own.

Roles and Users

Once you've defined a Role, you can associate it with LogStream users. On the Leader Node, select global Settings (lower left) > Access Management > Local Users. For details, see Local Users.

Note that when you assign multiple Roles to a given user, the Roles' permissions are additive: This user is granted a superset of all the permissions contained in all the assigned Roles.

By default, LogStream will log out a user upon a change in their assigned Roles. You can defeat this behavior at global ⚙️ Settings (lower left) > General Settings > API Server Settings > Advanced > Logout on roles change.

External Groups and LogStream Roles

You can map user groups from external identity providers (LDAP, Splunk, or OIDC) to LogStream Roles, as follows:

  1. Select global ⚙️ Settings (lower left) > Access Management > Authentication.

  2. From the Type drop-down, select LDAP, Splunk, or OpenID Connect, according to your needs.

  3. On the resulting Authentication Settings page, configure your identity provider's connection and other basics. (For configuration details, see the appropriate Authentication section.)

  4. Under Role Mapping, first select a LogStream Default role to apply to external user groups that have no explicit LogStream mapping defined below.

  5. Next, map external groups as you've configured them in your external identity provider (left field below) to LogStream Roles (right drop-down list below).

  6. To map more user groups, click + Add Mapping.

  7. When your configuration is complete, click Save.

Here's a composite showing the built-in Roles available on both the Default role and the Mapping drop-downs:

Mapping external user groups to LogStream Roles

And here, we've set a conservative Default Role and one explicit Mapping:

External user groups mapped to LogStream Roles