diff --git a/docs/manage/users-roles/roles/construct-search-filter-for-role.md b/docs/manage/users-roles/roles/construct-search-filter-for-role.md index ee39416345..e3505bc477 100644 --- a/docs/manage/users-roles/roles/construct-search-filter-for-role.md +++ b/docs/manage/users-roles/roles/construct-search-filter-for-role.md @@ -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 (`|`). @@ -69,7 +37,7 @@ 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 @@ -77,25 +45,25 @@ _collector=HR_Tools AND ### 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 ``` -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 @@ -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 @@ -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 @@ -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 @@ -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 ``` +:::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. + + 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. @@ -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*") @@ -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 +(_collector=fee OR _collector=f) AND ``` -**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  @@ -224,7 +198,7 @@ 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 @@ -232,6 +206,7 @@ When a user with Roles A and B runs a query, Sumo combines the two filters with **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`. + -### Example 5 +### Example 4 Assume the following role filters. @@ -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). \ No newline at end of file diff --git a/docs/manage/users-roles/roles/create-manage-roles.md b/docs/manage/users-roles/roles/create-manage-roles.md index d701a2ec06..4653e3d169 100644 --- a/docs/manage/users-roles/roles/create-manage-roles.md +++ b/docs/manage/users-roles/roles/create-manage-roles.md @@ -5,6 +5,7 @@ description: You can create custom roles for your users. --- import useBaseUrl from '@docusaurus/useBaseUrl'; +import RoleStacking from '../../../reuse/role-stacking-tip.md'; This section has instructions for creating and managing Sumo Logic roles. The roles you assign to a user control what Sumo Logic capabilities are available to the user and what log data the user can access. This functionality is referred to as role-based access control.   @@ -25,14 +26,17 @@ To create a role: 1. The **Create New Role** pane appears on the right side of the page.
Create a new role 1. **Name**. Enter a name for the role.  1. **Description**. Enter a description of the role to help other Administrators understand the purpose or limitations of the role. -1. **Search Filter**. Select one of the following to create a filter that allows access to only the logs that match the defined conditions. Only one is allowed for each. For examples, see [Search Filter and Index Access examples](#search-filter-and-index-access-examples) below. (For general guidance on creating search filters, see [Construct a Search Filter for a Role](/docs/manage/users-roles/roles/construct-search-filter-for-role/).) +1. **Search Filter**. Select one of the following to create a filter that allows access to only the logs that match the defined conditions. Only one is allowed for each. (For general guidance on creating search filters, see [Construct a Search Filter for a Role](/docs/manage/users-roles/roles/construct-search-filter-for-role/).) * **Log Analytics data filter**. This filter applies to all the [partitions](/docs/manage/partitions/run-search-against-partition/) and [LiveTail](/docs/search/live-tail/). * **Audit data filter**. This filter applies to all the logs in [Audit Indexes](/docs/manage/security/audit-indexes/) and [LiveTail](/docs/search/live-tail/). For example, you could include filters for `sumologic_audit_events`, `sumologic_search_events`, `sumologic_search_usage_per_query`, or `sumologic_system_events`, `sumologic_volume`, to name a few. * **Security data filter**. This filter applies on all logs in [Cloud SIEM security indexes](/docs/cse/records-signals-entities-insights/search-cse-records-in-sumo#partition-for-cloud-siem-signals). 1. **Index Access**. Allows or denies access to [search indexes](/docs/manage/partitions/data-tiers/). Select one of the following and choose the indexes in the **Select Indexes** box that appears: * **All indexes**. Allow access to all indexes. * **Allow few indexes**. Allow access to only the selected indexes. - * **Deny few indexes**. Deny access to the selected indexes. + * **Deny few indexes**. Deny access to the selected indexes. + :::warning + Use **Deny few indexes** with caution. We do not recommend filtering to deny access, as conflicting roles can create access inconsistencies—one role may deny access while another grants it. Whenever possible, apply filtering to allow access rather than deny it. This ensures roles work additively for more predictable access management. For more information, see [Index Access behavior when a user has multiple roles](#index-access-behavior-when-a-user-has-multiple-roles) below. + ::: 1. **Capabilities**. In this section, click the checkbox beside each capability you want to grant to users with this role. For information about what each capability enables, see [Role Capabilities](/docs/manage/users-roles/roles/role-capabilities/). 1. Click **Save**.  @@ -42,9 +46,10 @@ Follow this process to restrict access using the **Search Filter** and **Index A 1. Identify the dataset you would like to control access to. Test it out using a [search query](/docs/search/get-started-with-search/). 2. Create the role using the **Search Filter** and/or **Index Access** sections. -3. Verify the dataset access is correct using [emulation](#test-a-role-with-search-filter-and-index-access-defined). +3. Verify the dataset access is correct using [emulation](#test-a-roles-log-access-rights). 4. [Assign the role](#add-a-user-to-a-role) to the relevant users. + ### Index Access behavior when a user has multiple roles +This section describes what happens when a user is assigned multiple roles ("role stacking") and each role has different settings for Index Access. + + + A role can have one of the following Index Access settings: * **All indexes**. Allows access to all indexes. * **Allow few indexes**. Allows access to only the selected indexes. - * **Deny few indexes**. Denies access to the selected indexes. + * **Deny few indexes**. Denies access to the selected indexes. However, if a user is assigned multiple roles that each have different Index Access settings, following is how they are evaluated: * **All indexes** + **Allow few indexes**. Indexes in the "Allow few indexes" list are allowed, and all other indexes are allowed. @@ -67,12 +77,14 @@ However, if a user is assigned multiple roles that each have different Index Acc * **Allow few indexes** + **Deny few indexes**. Indexes in the "Allow few indexes" list are allowed, indexes in the deny list are denied, and all other indexes are denied. * **All indexes** + **Deny few indexes** + **Allow few indexes**. Indexes in the "Allow few indexes" list are allowed, indexes in the deny list are denied, and the rest of the indexes are allowed. -### Test a role with Search Filter and Index Access defined +## Test a role's log access rights + +To test a role to see if it displays the expected log access behavior, select a role and click **Emulate log search**. (You can also test a user. See [Test a user's log access rights](/docs/manage/users-roles/users/create-edit-users/#test-a-users-log-access-rights).) 1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic/). In the main Sumo Logic menu select **Administration > Users and Roles > Roles**.
[**New UI**](/docs/get-started/sumo-logic-ui/). In the top menu select **Administration**, and then under **Users and Roles** select **Roles**. You can also click the **Go To...** menu at the top of the screen and select **Roles**. -1. Select a role with **Search Filter** and/or **Index Access** defined. -1. Click **Emulate log search**. The search will be emulated for the filtering defined in the role. (In the example below, an index access filter is defined.)
Emulate log search for index filter -1. Enter your search parameters in the log search emulation window. The search will return only what is allowed by filtering defined in the role.
Emulate log search window +1. Select a role. +1. Click **Emulate log search**. The search will be emulated for the permissions of the role, including the filtering defined in the role. (In the example below, an index access filter is defined.)
Emulate log search for index filter +1. Enter your search parameters in the log search emulation window. The search will return only what is allowed by the role.
Emulate log search window ## Add a user to a role diff --git a/docs/manage/users-roles/users/create-edit-users.md b/docs/manage/users-roles/users/create-edit-users.md index 0a3db0de07..ddb28eefc4 100644 --- a/docs/manage/users-roles/users/create-edit-users.md +++ b/docs/manage/users-roles/users/create-edit-users.md @@ -46,3 +46,12 @@ When you add or remove a role from a user, it can take about an hour for the RBA 1. Select the row for the user you want to edit and choose **Edit** from the three-dot kebab options menu. 1. An edit pane appears on the right side of the page. For information about edit options, see [Create a user](#create-a-user) above. 1. After editing the user, click **Save**. + +## Test a user's log access rights + +A user's permissions in Sumo Logic are determined by the [roles the user is assigned](/docs/manage/users-roles/roles/add-remove-users-role/). After assigning roles to a user, you can test the user to see if it displays the expected log access behavior based on its assigned roles. (You can also test a role. See [Test a role's log access rights](/docs/manage/users-roles/roles/create-manage-roles/#test-a-roles-log-access-rights).) + +1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic/). In the main Sumo Logic menu select **Administration > Users and Roles > Users**.
[**New UI**](/docs/get-started/sumo-logic-ui/). In the top menu select **Administration**, and then under **Users and Roles** select **Users**. You can also click the **Go To...** menu at the top of the screen and select **Users**. +1. Select a user. +1. Click **More Actions > Emulate log search**. The search will be emulated for the permissions of the user.
Emulate log search for a user +1. Enter your search parameters in the log search emulation window. The search will return only what is allowed for the user.
Emulate log search window diff --git a/docs/reuse/role-stacking-tip.md b/docs/reuse/role-stacking-tip.md new file mode 100644 index 0000000000..3c10ac2f3d --- /dev/null +++ b/docs/reuse/role-stacking-tip.md @@ -0,0 +1,3 @@ +:::tip +As a best practice, avoid "role stacking" and assign all necessary access within a single role to prevent conflicts. When multiple roles are applied, conflicting permissions can arise. However, if role stacking is necessary, use filtering to allow access rather than deny it. This way, each additional role expands access rather than creating conflicts between "allow" and "deny" filters from different roles. +::: \ No newline at end of file diff --git a/static/img/users-roles/emulate-log-search-as-user.png b/static/img/users-roles/emulate-log-search-as-user.png new file mode 100644 index 0000000000..6a7d056058 Binary files /dev/null and b/static/img/users-roles/emulate-log-search-as-user.png differ diff --git a/static/img/users-roles/select-emulate-log-search.png b/static/img/users-roles/select-emulate-log-search.png new file mode 100644 index 0000000000..54e85be666 Binary files /dev/null and b/static/img/users-roles/select-emulate-log-search.png differ