> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-agentix/configure-cortex-agentix/users-and-roles-management/user-group-management.md). # User group management Users are assigned roles and permissions either by being assigned a role directly or by being assigned membership in one or more user groups. A user group can only be assigned to a single role, but users can be added to multiple groups if they require multiple roles. You can also nest groups to achieve the same effect. Users who have multiple roles through either method will receive the highest level of access based on the combination of their roles. The same principle for users with multiple roles is followed for both the Role-Based Access Control (RBAC) access permissions and the Scope-Based Access Control (SBAC) granular scoping, so that users receive the highest level of access by combining their roles. Example 10. * Joe has an Analyst role and is a member of the Tier-1 Analyst user group, which is assigned the Triage role. Joe has the permissions of the Analyst role and the Triage role. Joe is assigned 2 roles, and has the highest permission based on the combination of both roles. * John is a member of two user groups - Tier-1 Analyst and Tier-2 Analyst. One group is configured to use the Triage role and the other group is configured to use the Incident Response role. John is assigned both roles and has the highest permissions based on the combination of all roles. * Jack is a member of the Tier-2 user group, which has an Incident response role. This user group is included in a Tier-3 user group (Threat Hunter role), added as a nested group. Jack is assigned both roles and has the highest permissions based on the combination of all roles. On the **User Groups** page, you can create a new user group for several different system users or groups. You can see information including the details of all user groups, the roles, nested groups, IdP groups (SAML), and when the group was created/updated. You can also right-click in the table to edit, save as a new group, remove (delete) a group, and copy text to the clipboard. {% hint style="info" %} **Note** Non-administrator users with **Access Management** permissions cannot create or modify user groups to include the **Instance Administrator** role. Additionally, the **Edit** and **Delete** options are hidden for any user group that holds the **Instance Administrator** role, whether assigned directly or indirectly (through parent group assignments). {% endhint %} You can create user groups in the tenant or Cortex Gateway. User groups created in Cortex Gateway do not support SAML group mapping and are shared across all your tenants. We recommend managing user groups directly in the Cortex tenant, because only tenant-based groups support scoping and SAML group mapping. Managing groups directly in the tenant allows you to maintain different user groups for different environments, such as dev/prod. It also allows you to apply granular scoping to a user group by granting access only to the relevant data that the group members require. To use scope-based access control (SBAC), you must enable it in the **Server Settings** page. For more information, see [Manage user scope](/cortex-agentix/configure-cortex-agentix/users-and-roles-management/user-management/manage-user-scope.md). Before configuring SBAC, ensure that you review **Understand scoping** in the [Manage user scope](/cortex-agentix/configure-cortex-agentix/users-and-roles-management/user-management/manage-user-scope.md) section.
Core identity and group provisioning strategies To govern user-to-group lifecycle relationships within individual tenant workloads, administrators must utilize one of three core provisioning strategies to ingest or evaluate directory identities: **Strategy A: Native local custom groups (default method)** This default method allows you to associate users with groups created and managed within Cortex AgentiX. * **Methodology**: System administrators manually build structural custom groups directly in the tenant console or the Cortex Gateway, explicitly assigning individual accounts into the member list. * **Prerequisites for allocation**: The user identity must first exist in the Customer Support Portal (CSP) or have finished a first Single Sign-On (SSO) authentication sequence. For CSP users, the account must also be assigned the specific **Cortex User** role within the support portal configuration. If this role is not assigned, the user will be unable to log in through the CSP and will only be able to log in through SSO (if configured). For more information, see [Users, groups, and roles in Cortex AgentiX](/cortex-agentix/configure-cortex-agentix/users-and-roles-management/users-and-roles-in-cortex-agentix.md). **Strategy B: SAML dynamic group mapping (IdP is the source of truth)** This approach establishes your corporate Identity Provider (IdP) as the absolute source of truth, allowing group assignments defined in your enterprise directory to be seamlessly reused inside Cortex AgentiX. * **Methodology**: Administrators create user group shells inside Cortex AgentiX and associate them with the user groups defined in the IdP. This allows you to reuse your existing organizational hierarchy, access permissions, and team structures directly into the security operations console without introducing operational fragmentation or duplicative group-association overhead. * **Note on role requirements**: Users who authenticate only through Single Sign-On (SSO) do not require the **Cortex User** role in the CSP. Their access and permissions are managed via the SAML group mappings and the default role configured in your SSO settings. * **Configuration steps**: * **For Okta environments**: For step-by-step instructions, see [Set up Okta as the Identity Provider Using SAML 2.0](/cortex-agentix/configure-cortex-agentix/users-and-roles-management/set-up-authentication/set-up-okta-as-the-identity-provider-using-saml-2.0.md). Pay close attention to configuring the group attribute statement to pass the user's groups in the SAML assertion token. * **For Microsoft Entra ID (Active Directory) environments**: For step-by-step instructions, see [Set up Microsoft Entra ID as the Identity Provider Using SAML 2.0](/cortex-agentix/configure-cortex-agentix/users-and-roles-management/set-up-authentication/set-up-microsoft-entra-id-as-the-identity-provider-using-saml-2.0.md). You must configure Entra ID to emit user group claims in the token. * **Critical capitalization requirement**: String evaluation across authentication mappings, attribute configurations, and group designations enforces absolute case mapping rules. Strict attention to exact character capitalization must be maintained across all configurations. If the group name string in the IdP does not match the string in Cortex AgentiX with identical uppercase and lowercase letters, the mapping will fail completely, and users will not inherit their permissions. * **Active session mechanics**: This flow operates dynamically during user login and does not alter or update the permanent group mappings listed within the Cortex AgentiX console. The session flow works as follows: 1. The user logs in via SSO. 2. Based on the SAML assertions coming from the Identity Provider (IdP), the list of IdP groups associated with that user is extracted. 3. These extracted groups are used to associate the user with the local Cortex Groups based on the **SAML Group Mapping** field configured within the Cortex group settings. 4. These mapped groups are associated with the user for the length of the current authenticated session. 5. Consequently, these groups do not appear in the persistent list of Cortex groups associated with this user inside the Cortex AgentiX console. **Strategy C: Cloud Identity Engine (CIE) directory sync** This process utilizes the CIE directory to manage and arrange organizational group mappings in advance. * **Methodology**: The Cloud Identity Engine (CIE) uses the System for Cross-domain Identity Management (SCIM) protocol to automatically synchronize groups from your Identity Provider (IdP) directly into CIE. Then, Cortex AgentiX synchronizes the CIE groups that were selected using **Import AD Group** into its local list of groups. * **Configuration steps**: Configure and connect the underlying identity engine pipeline to your enterprise directory before mapping groups locally. See your Cloud Identity Engine onboarding instructions. * **Synchronization processing delay**: Because the directory sync between CIE and the Cortex tenant runs on a periodic background schedule, a delay of a few hours may occur after the list of groups changes in your IdP, or when a mapping between groups and users changes in CIE. {% hint style="info" %} ### Important The Cloud Identity Engine (CIE) is used exclusively for directory group management; it is not utilized for individual user account management, provisioning, or authentication workflows. Consequently, disabling, suspending, or removing user objects directly within CIE does not automatically disable, restrict, or delete those corresponding users inside Cortex AgentiX. If you use Single Sign-On (SSO) for Cortex AgentiX authentication, see [Set up authentication](/cortex-agentix/configure-cortex-agentix/users-and-roles-management/set-up-authentication.md) for instructions on handling directory lifecycle cleanups and managing stale accounts. {% endhint %}
How to create a user group 1. Go to Settings → Configurations → Access Management → **User Groups**. If creating in Cortex Gateway, go to **Permission Management** → **User Groups**. 2. To create a new user group for several different system users or groups, click **New Group**, and add the following parameters: | Parameter | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Name of the user group. | | Description | Description of the user group. | | Group for product | (Cortex Gateway only) If you have multiple products, select the relevant Cortex product. | | Role |

Select the group role associated with this user group. You can only have a single role designated per group.

In Cortex Gateway, you can only select either Instance Administrator or a custom role created in the Gateway.

Note

For non-administrator users, the Instance Administrator role is unavailable from the dropdown menu.

| | Users |

Select the users you want to belong to this user group.

Note

If users have been created in the CSP, but you want them to access the tenant through SSO only, skip this field and add only SAML group mapping after SSO is set up, otherwise, users can access the tenant through both the CSP and SSO.

If you have not yet created any users, skip this field and add them later. See Set up authentication.

| | Nested Groups |

Lists any nested groups associated with this user group. If you have an existing group, you can add a nested group.

User groups can include multiple users and nested groups, which inherit the permissions of parent user groups. The user group will have the highest level of permission.

For example:

If you add Group A as a nested group in Group B, Group A inherits Group B's permissions (Tier-1 and Tier-2 permissions).

In Cortex Gateway, you can only add user groups that are created in Cortex Gateway.

| | SAML Group Mapping |

(Relevant when creating a user group in the Cortex tenant only.)

Maps the SAML group membership to this user group. For example, you have defined a Cortex Admins group. You need to name this group exactly how it appears in Okta.

You can add multiple groups by separating them with a comma.

Note

When using Microsoft Entra ID for SSO, the SAML group mapping needs to be provided using the group object ID (GUID) and not the group name.

If you have not set up SSO in your tenant, skip this field and add it later. After you have added it, follow the procedure relevant to your IdP. For example, see Set up Okta as the Identity Provider Using SAML 2.0.

| 3. (Optional) When creating the user group in the tenant, configure granular scoping for the user group. If creating the user group in the Cortex Gateway, you can skip this step, as scoping is only supported in the tenant. 1. Click the **Scope** tab. 2. Expand the scoping areas that you want to grant the user role access to in the tenant by clicking the chevron icon (**>**) beside the scoping area title, and make any changes required. The following table explains the options available to configure: | Scoping Area | Granular Scoping Configurations | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cases and Issues |

Set the Scope by selecting one of the following:

|

Important

By default, Enable Scope Based Access Control is disabled in Settings → Configurations → General → Server Settings, and granular scoping is not enforced. Before enabling SBAC, we recommend that an administrator or a user with Access Management permissions first ensures that the users, user groups, and API Keys defined in Cortex AgentiX are granted the required access by assigning the relevant scopes. For more information, see Manage user scope.

4. Click **Create** to create the user group.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-agentix/configure-cortex-agentix/users-and-roles-management/user-group-management.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.