---
alias: user-guide-security-roles
description: "Manage roles within the application, including creation, editing, and assignment of users, services, and features to control access and permissions"
---

# Roles

:lock: Administration.**Security**

## Roles Overview

The list of Roles is available by selecting the Roles label on the landing page of the **Security** page.

![Roles list showing available security roles in the system](../images/security_role_list.png)

The **Roles** page displays general information on the specific **Role**. In addition it enables the user to perform all the operations that can be performed on a specific **Role**.

{% include-markdown 'includes/views/details_view.md' %}

* **Details** - displays general information on the **Role**.
* **Members** - displays information on the **Users** or other **Roles** that belong to the **Role**.
* **Features** - displays information on the **Features** to which the **Role** has access.
* **Services** - displays information on the **Services** to which the **Role** has access.
* **Data Groups** - displays information on the **Data Groups** to which the **Role** belongs.
* **Report Folders** - displays information on the **Data Groups** to which the **Role** has access.

!!! warning
	To access the Report Folders section within the Role page, the user must have access to the `ReportFolder.Edit` feature.

![Role details view showing general information, members, features, services, and data access sections](../images/security_role_page_details_view.png)

## System Default Roles

Critical Manufacturing MES provides a set of default roles that control the operations users can perform in the system. The following roles are available by default:

* **Administrators** - the system's built-in administrative role. This role cannot be deleted.
* **AppFrameworkApiAccess** - grants applications the permissions required to interact with Critical Manufacturing MES APIs during installation. This role is assigned to the user representing the application being installed.
* **CubeExplorerAdministrators** - a role used to control access to the Cube Explorer (Cube Playground) functionality.
* **DataOrchestratorAdministrators** - grants access to the [[user-guide-data-orchestrator]] (Dagster) user interface.
* **MES** - an OAuth Scope Role automatically generated as part of the environment. This role is required for non-Administrator users to log in to Critical Manufacturing MES. Without it, users will receive an error at login.
* **SysAdministrators** - grants access to environment management endpoints related to ClickHouse backup and restore operations.

!!! info
    In addition to these roles, installed applications create their own roles. These roles are automatically generated and follow the name of the corresponding application.

## Creating a Role

:lock: Role.**Create**

To create a **Role** in the application - note that the role must exist in the Active Directory - it's necessary to choose the Roles page and select the Create button in the ribbon:

1. Provide the name for the Role.
2. Optionally, provide a description.
3. Optionally, enter a auto-lock timeout value (in seconds) which applies by default for every user which has this role defined as the primary role. Note that this value is overridden by the user level auto-lock timeout value.
4. Optionally, specify a Distribution List where emails will be sent when notifying role.

	!!! note
		If a Distribution List is defined, it must be well formed - it must contain valid email addresses, and if multiple email addresses are provided, they must be separated by a semicolon.

5. If the Role is an Active Directory Role, the *Is Active Directory Group* checkbox must be checked. Note that in this case the Name must match exactly the Active Directory group name. For groups from more than one Active Directory domain, see [[operation-guide-multipledomains]].
6. If the Role is defined as an OAuth Scope Role, the *Is OAuth Scope* checkbox must be checked for proper authorization when using the appropriate Security Portal strategy.

    !!! note
	     The `MES` OAuth Scope Role is required for non-Administrator users to log in to MES. Without it, the user will receive a message error at login.

7. Select **Create** to complete the operation.

![Create Role form with name, description, auto-lock, and directory settings](../images/security_role_create.png)

## Editing a Role

:lock: Role.**Edit**

To edit a **Role**, it's necessary to:

1. Open the **Role** page.
2. Open the wizard by selecting **Edit** on the top ribbon.
3. Make the necessary changes.
4. Commit the data to the database by choosing **Update**.

![Edit Role form showing editable role details and update action](../images/security_role_edit.png)

## Removing a Role

:lock: Role.**Remove**

To remove a Role, it's necessary to:

1. Open the **Role** page.
2. Open the wizard by selecting Remove on the top ribbon.
3. Select **Remove** to complete the operation.

![Remove Role confirmation dialog showing the role deletion action](../images/security_role_remove.png)

!!! warning
    Any Personal Access Tokens with the scope associated through the role (directly or indirectly) will be revoked.

## Assigning Users to a Role

:lock: Role.**Edit**

To assign one or more Users to a **Role** is necessary to:

1. Open the **Role** details and navigate to the Members sub-section in the Details View panel, or select the Roles in the **Role** list page.
2. Select the **Assign** dropdown button and select **Users**.
3. Choose the desired Users to be assigned the current **Role**.
4. Select **Assign** to complete the operation.

![Assign Users dialog showing available users for the selected role](../images/security_role_assign_user.png)

## Unassigning Users from a Role

:lock: Role.**Edit**

To unassign one or more Users from a **Role** is necessary to:

1. Open the **Role** details and navigate to the Members sub-section in the Details View panel.
2. Choose the Users you wish to unassign from the **Role** and select the **Unassign** dropdown button, followed by **Users**.
3. Select **Unassign** to complete the operation.

![Unassign Users dialog showing users selected for removal from the role](../images/security_role_unassign_user.png)

## Assigning Roles to a Role

:lock: Role.**Edit**

To assign one or more **Roles** to a **Role** is necessary to:

1. Open the **Role** details and navigate to the Members sub-section in the Details View panel, or select the **Roles** in the **Role** list page.
2. Select the **Assign** dropdown button and select **Roles**.
3. Choose the desired **Roles** to be assigned the current **Role**.
4. Select **Assign** to complete the operation.

![Assign Roles dialog showing available roles to inherit into the current role](../images/security_role_assign_role.png)

## Unassigning Roles from a Role

:lock: Role.**Edit**

To unassign one or more **Roles** from a **Role** is necessary to:

1. Open the **Role** details and select the Members sub-section in the Details View panel.
2. Choose the **Roles** you wish to unassign from the **Role** and select the **Unassign** dropdown button, followed by **Roles**.
3. Select **Unassign** to complete the operation.

![Unassign Roles dialog showing roles selected for removal from the current role](../images/security_role_unassign_role.png)

## Assigning Services to a Role

:lock: Role.**Edit**

To assign one or more **Services** to a **Role** is necessary to:

1. Open the **Role** details and select the **Services** sub-section in the Details View panel, or select the **Roles** in the **Role** list page.
2. Select the **Assign** button.
3. Select the desired **Services** to be assigned the current **Role**.
4. Select **Assign** to complete the operation.

![Assign Services dialog showing services available to the selected role](../images/security_role_assign_service.png)

## Unassigning Services from a Role

:lock: Role.**Edit**

To unassign one or more **Services** from a **Role** is necessary to:

1. Open the **Role** details and select the **Services** sub-section in the Details View panel.
2. Choose the **Services** you wish to unassign from the **Role** and select the **Unassign** button.
3. Select **Unassign** to complete the operation.

![Unassign Services dialog showing services selected for removal from the role](../images/security_role_unassign_service.png)

## Assigning Features to a Role

:lock: Role.**Edit**

To assign one or more Features to a **Role** is necessary to:

1. Open the **Role** details and select the Features sub-section in the Details View panel, or select the **Roles** in the **Role** list page.
2. Select the **Assign** button.
3. Choose the desired Features to be assigned the current **Role**.
4. Select **Assign** to complete the operation.

!!! info
	For easier feature assignment, there is the possibility of selecting all features at once, bypassing the grid paging and allowing for a one-click selection of the entire set of features. Simply use Select All Items and all the available features will be selected. Similarly, to deselect all features, use Clear Selection and all features will be deselected.

![Assign Features dialog showing feature permissions available to the role](../images/security_role_assign_feature.png)

## Unassigning Features from a Role

:lock: Role.**Edit**

To unassign one or more Features from a **Role** is necessary to:

1. Open the **Role** details and select the Features sub-section in the Details View panel.
2. Choose the Features you wish to unassign from the **Role** and select the **Unassign** button.
3. Select **Unassign** to complete the operation.

![Unassign Features dialog showing features selected for removal from the role](../images/security_role_unassign_feature.png)

## Assigning Data Groups to a Role

:lock: Role.**Edit**

To assign one or more Data Groups to a **Role** is necessary to:

1. Open the **Role** details and select the Data Groups sub-section in the Details View panel, or select the **Roles** in the **Role** list page.
2. Select the **Assign** button.
3. Choose the desired Data Groups to be assigned the current **Role**.
4. Choose the Access Mode for each of the Data Groups to assign to the current **Role**.
5. Select **Next**.
6. Choose the Access Mode for each Data Group and select **Assign** to complete the operation.

=== "Data Groups"

    ![Assign Data Groups dialog](../images/security_role_assign_datagroup.png)

=== "Access Mode"

    ![Assign Data Groups dialog showing access mode configuration for role membership](../images/security_role_assign_datagroup_access_mode.png)

## Unassigning Data Groups from a Role

:lock: Role.**Edit**

To unassign one or more Data Groups from a **Role** is necessary to:

1. Open the **Role** details and select the Data Groups sub-section in the Details View panel.
2. Choose the Data Groups you wish to unassign from the **Role** and select the **Unassign** button.
3. Select **Unassign** to complete the operation.

![Unassign Data Groups dialog showing data groups selected for removal from the role](../images/security_role_unassign_datagroup.png)

## Assigning Report Folders to a Role

:lock: Role.**Edit**

To assign one or more Report Folders to a **Role** is necessary to:

1. Open the **Role** details and select the Report Folders sub-section in the Details View panel, or select the **Roles** in the **Role** list page.
2. Select the **Assign** button.
3. Choose the desired Report Folders to be assigned the current **Role**.
4. Choose the Access Mode for each of the Report Folders to assign to the current **Role**.
5. Select **Next**.
6. Choose the Access Mode for each Report Folder and select **Assign** to complete the operation.

!!! warning
	To access the Report Folders sub-section within the Role page, the user must have access to the `ReportFolder.Edit` feature.

=== "Report Folders"

    ![Assign Report Folders dialog showing report folder permissions](../images/security_role_assign_report_folders.png)

=== "Access Mode"

    ![Assign Report Folders dialog showing access modes](../images/security_role_assign_report_folders_access_mode.png)

## Unassigning Report Folders from a Role

:lock: Role.**Edit**

To unassign one or more Report Folders from a **Role** is necessary to:

1. Open the **Role** details and select the Report Folders sub-section in the Details View panel.
2. Choose the Report Folders you wish to unassign from the **Role** and select the **Unassign** button.
3. Select **Unassign** to complete the operation.

!!! warning

    * If the user role is Administrator, you cannot unassign Report Folders. Administrators always have access to all available Report Folders.
	* To access the Report Folders sub-section within the Role page, the user must have access to the `ReportFolder.Edit` feature.

![Unassign Report Folders dialog showing report folders selected for removal from the role](../images/security_role_unassign_report_folders.png)

## Managing Role Workspaces

:lock: Role.**ManageWorkspaces**

To manage **Role Workspaces**, follow these steps:

1. Select the desired **Role** and choose **Manage Workspaces**.
2. Add, edit, or remove **Role Workspaces** as needed. For each record, specify:
    * The **Workspace** associated with the **Role**.
    * Whether the **Workspace** is set as the default.

    !!! note
        - To create a Workspace, you must [[user-guide-uipages-create-uipage|create a UI Page]] configured with the [[user-guide-uipages-workspaces|Workspace scope]].
		- Each Role/Workspace combination must be unique.
        - Only one Workspace can be marked as the default for each Role.

3. Select **Update** to save and apply the changes.

![Manage Role Workspaces dialog showing workspace assignment and default workspace selection](../images/manage_workspaces.png)