Skip to content

DOCS-680 - Update role filtering guidance on "role stacking" #5049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Feb 10, 2025
Merged

DOCS-680 - Update role filtering guidance on "role stacking" #5049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7b57cdb
DOCS-680 - Update role filter article
jpipkin1 Feb 7, 2025
7f439b1
Update docs/manage/users-roles/roles/construct-search-filter-for-role.md
jpipkin1 Feb 10, 2025
0b3e68d
Update docs/manage/users-roles/roles/create-manage-roles.md
jpipkin1 Feb 10, 2025
d1e4043
Update docs/reuse/role-stacking-tip.md
jpipkin1 Feb 10, 2025
817c992
Updates from reviews
jpipkin1 Feb 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 37 additions & 57 deletions docs/manage/users-roles/roles/construct-search-filter-for-role.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,52 +5,20 @@ description: Construct a role search filter to control what log data users with
---

import useBaseUrl from '@docusaurus/useBaseUrl';

import RoleStacking from '../../../reuse/role-stacking-tip.md';

This page describes how to define search filters for a role. These instructions apply to the **Search Filter** option in Step 6 of the [Create a role](/docs/manage/users-roles/roles/create-manage-roles/#create-a-role) procedure.

## Understanding search filters

A search filter for a role defines what log data a user with that role can access. You can define a search filter using keywords, wildcards, metadata fields, and logical operators. Here is a simple role filter:

```sql
_sourceCategory=labs*
```

This filter grants access to logs whose `_sourceCategory` begins with the string “labs”. (Logs whose `_sourceCategory` don’t start with “labs” won’t be accessible.)

When a user with this filter enters a query like:

```sql
_sourceCategory=labs/apache | parse "* --" as src_ip | count by src_ip | sort _count
```

Sumo silently (it’s transparent to the user) adds the role filter to the beginning of the query with an AND:

```sql
_sourceCategory=labs* AND (_sourceCategory=labs/apache | parse "* --" as src_ip | count by src_ip | sort _count)
```

The example above positively grants access to log data. You can do the opposite: explicitly deny access to data, with an exclamation point (!). For example:

```
!_sourceCategory=JobX*
```

The role filter above denies access to log data whose  `_sourceCategory` begins with “JobX”. (Access to log data with other source category values is not restricted.)

The examples above are simple: they involve a single role, and hence a single role filter. 

Typically however, a Sumo user will have multiple roles. If a user has multiple roles, Sumo `OR`s the several role filters and prepends that expression to the user’s queries with an `AND`, as discussed in [Multiple role filters and filter precedence](#multiple-role-filters-and-filter-precedence).

## Search filter basics

The sections below list search filter limitations, and describe how you can use keywords, wildcards, metadata, and logical operators in filters. 
A search filter for a role defines what log data a user with that role can access. You can define a search filter using keywords, wildcards, metadata fields, and logical operators.

The explanations of the behavior of each example filter assume that no other role filters apply. In practice, you will likely assign multiple roles to users. After you understand the basics of how role filters work, see [Multiple role filters and filter precedence](#multiple-role-filters-and-filter-precedence).
The explanations of the behavior of each example filter assume that no other role filters apply. In practice, you may assign multiple roles to users. After you understand the basics of how role filters work, see [Multiple role filters and filter precedence](#multiple-role-filters-and-filter-precedence).

### Search filter limitations

The sections below list search filter limitations, and describe how you can use keywords, wildcards, metadata, and logical operators in filters. 

* Role filters should include only keyword expressions or built-in metadata field expressions using these fields: `_sourcecategory`, `_collector`, `_source`, `_sourcename`, `_sourcehost`.
* Using `_index` or `_view` in a role filter scope is not supported.
* Role filters cannot include vertical pipes (`|`).
Expand All @@ -69,33 +37,33 @@ You can use metadata fields in a role search filter. The following search filter
_collector=HR_Tools
```

When a user with that role filter runs a query, Sumo prepends the filter to the query with an AND:
When a user with that role filter runs a query, Sumo Logic prepends the filter to the query with an `AND`:

```sql
_collector=HR_Tools AND <user-query>
```

### Using AND and OR in a search filter

You can use AND and OR in a search filter. For example, this role filter uses OR to grant access to log data from two source categories:
You can use `AND` and `OR` in a search filter. For example, this role filter uses `OR` to grant access to log data from two source categories:

```sql
_sourceCategory=stock OR _sourceCategory=insurance
```

When a user with that role filter runs a query, Sumo prepends the filter to the query with an AND:
When a user with that role filter runs a query, Sumo Logic prepends the filter to the query with an `AND`:

```sql
(_sourceCategory=stock OR _sourceCategory=insurance) AND <user-query>
```

This role filter below uses AND to grant access to log data with the source category “insurance” from the collector named “HR_Tools”:
This role filter below uses `AND` to grant access to log data with the source category “insurance” from the collector named “HR_Tools”:

```sql
_collector=HR_Tools AND _sourceCategory=insurance
```

When a user with that role filter runs a query, Sumo prepends the filter to the query with an AND:
When a user with that role filter runs a query, Sumo Logic prepends the filter to the query with an `AND`:

```sql
(_collector=HR_Tools AND _sourceCategory=insurance) AND <user-query>
Expand All @@ -109,7 +77,7 @@ You can include a string you want to search for in a role search filter. This ro
_collector=HR_Tools AND enrollment
```

When a user with that role filter runs a query, Sumo runs it like this:
When a user with that role filter runs a query, Sumo Logic runs it like this:

```sql
(_collector=HR_Tools AND enrollment) AND <user-query>
Expand All @@ -123,7 +91,7 @@ You can use an asterisk (\*) as a wildcard in a role search filter. This role fi
_collector=HR* 
```

When a user with that role filter runs a query, Sumo runs it like this:
When a user with that role filter runs a query, Sumo Logic runs it like this:

```sql
_collector=HR* AND <user-query>
Expand All @@ -135,7 +103,7 @@ This role filter grants access to logs that contain the string “violation” f
_collector=HR* AND violation
```

When a user with that role filter runs a query, Sumo runs it like this:
When a user with that role filter runs a query, Sumo Logic runs it like this:

```sql
(_collector=HR* AND violation) AND <user-query>
Expand All @@ -155,15 +123,21 @@ denies access to log data whose:  
* `_sourceName` contains “finance”
* `_sourceCategory` contains “secret”

When a user with that role filter runs a query, Sumo runs it like this:
When a user with that role filter runs a query, Sumo Logic runs it like this:

```sql
(!_sourceHost=humanresources* AND !_sourceName=*finance* AND !_sourceCategory=*secret*) AND <your-query>
```

:::warning
Although this example demonstrates that filtering to deny access is possible, we do not recommend it. If a user has multiple roles, one role may deny access to an area while another grants access, leading to conflicts. To avoid this, use filtering to allow access rather than deny it. This ensures roles work additively, making access management more predictable.
:::

## Multiple role filters and filter precedence

When a user is assigned to multiple Sumo roles, Sumo combines the role filters from each of the roles using a logical OR to come up with the combined role filter.
When a user is assigned to multiple Sumo Logic roles ("role stacking"), Sumo Logic combines the role filters from each of the roles using a logical `OR` to come up with the combined role filter.

<RoleStacking/>

When multiple roles filters are applied to a query, the least restrictive filter takes precedence. That this rule doesn’t apply if any of the role filters applied to a query is simply blank, which effectively grants access to all data, and would be the least restrictive filter. If the combined search filters applied to a query includes filters that are blank, the blank search filter is ignored and the next least restrictive filter takes precedence. So, if you actually want to grant a role access to all data, set the search filter to an asterisk (`*`). A search filter that is configured in that fashion will take precedence when combined with more restrictive search filters.

Expand All @@ -180,7 +154,7 @@ Role A allows access to log data whose `_source` tag is “GCP Audit” and `_co

Role B Allows access to log data whose `_sourceCategory` tag begins with “Vx”.  

When a user with Roles A and B runs a query, Sumo applies the filters with an OR, and prepends them with an AND to your query, like this:
When a user with Roles A and B runs a query, Sumo Logic applies the filters with an `OR`, and prepends them with an `AND` to your query, like this:

```sql
((_source="GCP Audit" AND _collector="GCP") OR _sourceCategory="Vx*")
Expand All @@ -196,19 +170,19 @@ Assume the following role filters.
| Role | Filter |
|:----------|:-------------------|
| Role A | `_collector=fee*` |
| Role B | `!_collector=fi*` |
| Role B | `_collector=f*` |

Role A allows access only to log data whose `_collector` tag matches “fee\*”, and not to data whose `_collector` tag is any other value.

Role B Allows access to any log data whose `_collector` tag does not match “fi”.  
Role B Allows access to any log data whose `_collector` tag matches “f\*”, and not to data whose `_collector` tag is any other value.  

When a user with Roles A and B runs a query, Sumo combines the two filters with an OR, and prepends them with an AND to your query, like this:
When a user with Roles A and B runs a query, Sumo Logic combines the two filters with an `OR`, and prepends them with an `AND` to your query, like this:

```sql
(_collector=fee OR !_collector=fi) AND <your-query>
(_collector=fee OR _collector=f) AND <your-query>
```

**The least restrictive of the role filters takes precedence**. So, although Role A effectively restricts results to log data that matches `_collector=fee*`, Role B allows grants access to all collectors, except for those that match `_collector=fi*`. So, Role B takes precedence and Role A has no effect.
**The least restrictive of the role filters takes precedence**. So, although Role A effectively restricts results to log data that matches `_collector=fee*`, Role B allows grants access to all collectors that match `_collector=f*`. So, Role B takes precedence and Role A has no effect.

### Example 3 

Expand All @@ -224,14 +198,15 @@ Role A allows access only to log data whose `_sourceCategory` is “analytics-la

Role B Allows access to log data whose `_sourceCategory` begins with “analytics”.

When a user with Roles A and B runs a query, Sumo combines the two filters with an OR, like this:
When a user with Roles A and B runs a query, Sumo Logic combines the two filters with an `OR`, like this:

```sql
(_sourceCategory=analytics-lab OR _sourceCategory=analytics*) AND <your-query>
```

**The least restrictive of the role filters takes precedence.** Role A alone grants access to a log data from a single  source category, “analytics-lab”.  Role B grants access to log data to any source category that starts with “analytics”. Since the least restrictive filter takes precedence, data tagged `_sourceCategory=analyticsLong` could be returned in addition to data tagged `_sourceCategory=analytics-lab`.

<!-- Hiding the following for work on DOCS-680
### Example 4

Assume the following role filters.
Expand All @@ -245,15 +220,16 @@ Role A allows access to log data whose `_collector` tag matches “prod\*”, an

Role B prevents access to log data whose `_sourceCategory` tag does contain “shoguns”. Data with any ` _sourceCategory` tag that does not contain “shoguns” is available. 

When a user with Roles A and B runs a query, Sumo combines the two filters with an OR, and prepends them with an AND to your query, like this:
When a user with Roles A and B runs a query, Sumo Logic combines the two filters with an `OR`, and prepends them with an `AND` to your query, like this:

```sql
(_collector=prod* OR !_sourceCategory=*shoguns*) AND <your-query>
```

Role B is the least restrictive. Users with the combined role filter will be able to view any log data whose  `_sourceCategory` does not contain the string “shoguns”, regardless of the value of the `_collector` tag.
-->

### Example 5
### Example 4

Assume the following role filters.

Expand All @@ -266,4 +242,8 @@ Role A allows access to all indexes whose name starts with "sumologic".

Role B, with a blank search filter (user did not enter anything as the search filter for the role), allows access to all data.

When a user with Roles A and B runs a query, Sumo combines the two filters and since Role B has a blank search filter, the more restrictive search filter, Role A, takes precedence. Users with the combined role filter will be able to  view any log data in any of the indexes prefixed with "sumologic".
When a user with Roles A and B runs a query, Sumo Logic combines the two filters and since Role B has a blank search filter, the more restrictive search filter, Role A, takes precedence. Users with the combined role filter will be able to  view any log data in any of the indexes prefixed with "sumologic".

## Test role filtering

To test whether filtering works as expected, select a role and click the **Emulate log search** button. For more information, see [Test a role](/docs/manage/users-roles/roles/create-manage-roles/#test-a-roles-log-access-rights).
Loading
Loading