Skip to content

Commit

Permalink
Rework docs for roles and permissions (#13716)
Browse files Browse the repository at this point in the history 
* first changes

* more changes

* More changes

* More changes

* Small changes and updates

* small typo

* small typo

---------

Co-authored-by: birthe <b.lindenthal@openproject.com>
  • Loading branch information
@lindenthal @birthe
lindenthal and birthe committed Sep 21, 2023
1 parent f5da307 commit f57b86c
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 53 deletions.
115 changes: 63 additions & 52 deletions docs/system-admin-guide/users-permissions/roles-permissions/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,91 +7,102 @@ keywords: manage roles, manage permissions
---
# Roles and permissions

A **role** is a set of **permissions** that can be assigned to any project member. Multiple roles can be assigned to the same project member.
## Users

When creating a role, the **Global role** checkbox can be checked, making it a **Global role** that can be assigned to a [user details](../users/#manage-user-settings) or a [group details](../groups/#add-global-roles-to-a-group) and applied across all projects.
A user is any individual who can log into your OpenProject instance.

## Permissions

| Topic | Content |
| ----------------------------------------------- |-------------------------------------------------------------------|
| [Permissions](#permissions) | What are permissions and how can I access the permissions report? |
| [Create a new role](#create-a-new-role) | How to create a new (global) role. |
| [Edit and remove roles](#edit-and-remove-roles) | How to change and delete existing roles. |
| [Global roles](#global-roles) | Which global roles are there and what are their significances? |
Permissions control what users can see and do within OpenProject. Permission are granted to users by assigning one or more roles to the users.

## Permissions
## Roles

A role bundles a collection of permissions. It is an convenient way of granting permissions to multiple users in your organization that need the same permissions or restrictions.

The permissions are predefined in the system, and cannot be changed. They define what actions a role can carry out. If a user has more than one role (including global and project roles), a permission is granted if it is assigned to any of those roles.
A user can have one or more roles which grant permissions on different levels:

All permissions are shown sorted by OpenProject module in the [create a new role](#create-a-new-role) page or when clicking on an existing role.
| Role type and description | Scope of the role | Permission examples | Customization options |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **Administrator**<br />Administrators have full access to all settings and all projects in an OpenProject environment. The permissions of the Administrator role can not be changed.<br /> | Application-level: Full control of all aspects of the application | - Assign administration privileges to other users<br />- Create and restore backups in the web interface<br />- Create and configure an OAuth app<br />- Configure custom fields<br />- Archive projects/restore projects<br />- Configure global roles<br />- Configure project roles | Cannot be changed |
| **Global role**<br />Global roles allow Administrators to delegate administrative tasks to individual users. | Application-level: Permissions scoped to specific administrative tasks (not restricted to specific projects) | - Manage users<br />- Create projects | Administrators can create new global roles and assign global permissions to those role |
| **Project role**<br />A project role is a set of **permissions** that can be assigned to any project member. Multiple roles can be assigned to the same project member.<br /><br />**Note:** If a module is not enabled in a project it is not shown to a user despite having a permission for it. | Project-level: Permissions scoped to individual projects (a user can have different roles for individual projects) | - Create work packages (in a project)<br />- Delete wiki pages (in a specific project) | Create different project roles with individual permission sets |
| **Non-member**<br />Non member is the default role of users of your OpenProject instance who have not been added to a project. This only applies if the project has been set as **[public](../user-guide/projects/#set-a-project-to-public)** in the project settings.<br /><br /><br />**Note: **The *Non-member* role cannot be deleted. | Project-level: Permissions scoped to individual projects for users which are logged in | - View work packages for users that are logged in | Assign different permissions to the role *Non-member* |
| **Anonymous**<br />OpenProject allows to share project information with anonymous users which are not logged in. This is helpful to communicate projects goals and activities with a public community.<br /><br /> **Note**: This only applies if you disabled the need for authentication for your instance and if the project is set as **public**.<br />The *Anonymous* role cannot be deleted. | Project-level: Permissions scoped to individual projects for users which are <u>not</u> logged in | - View work packages for users that are not logged in | Assign different permissions to the role *Anonymous* |

## Customize roles with individual permissions

Administrators can add new roles with custom permissions or configure existing ones in *Administration* > *Users and permissions* > *Roles and permissions*.

### Permissions report

On the bottom of the roles list page there is a link to the **Permissions report**. This shows a grid of existing roles (columns) against permissions (rows); the intersections are ticked if the role has the permission.
The permissions report is a good starting point to get an overview of the current configuration of roles and permissions. To open the permissions report, navigate to the overview table of exiting *Roles* and click on the link *Permissions report* below the table.

### Create a new project roles

Administrators can create new project roles in *Administration* > *Users and permissions* > *Roles and permissions*. Click on the green *+Role* button to create a new role.

Complete the following steps:

1. **Name**: must be a new role name.
2. **Global role**: create a new [global role](#create-a-new-global-role).
3. **Copy workflow from**: select an existing role and copy the respective [workflow](../../manage-work-packages/work-package-workflows) to the newly created role.
4. **Permissions**: you can grant permissions which define what the user with the respective role can see and do in the project scope. The permissions are grouped based on the modules.

To create the new role, click on the grey *Create* button at the bottom of the page.

### Create a new global role

A **Check/uncheck all** checkbox is shown on each role or permission to allow bulk change. **Be careful, this cannot be undone**. If you make a mistake, do not save the report.
Administrators can create new global roles in *Administration* > *Users and permissions* > *Roles and permissions*. In the creation form check the box **Global role**. The form now shows the available global permissions which can be assigned to the new global role:

### Project Modules
- **[Create projects](../../getting-started/projects/#create-a-new-project)**

Note: If a [project module](../../../user-guide/projects/project-settings/modules/) is not enabled for a specific project it is not shown in that project's menu whether the user has permission for that module or not.
> **Note:** To create a subproject for an existing project it requires also the project permission "Create subprojects".
## Create a new role
- **[Create backups](../backup/)**

To create a new role, navigate to the administration and select **Users and permissions -> Roles and permissions** from the menu on the left.
- **[Create users](../users-permissions/users/#create-users)**

You will see the list of all the roles that have been created so far.
- **[Edit users](../users/)**

**Non member** is the default role of users of your OpenProject instance who have not been added to a project. This only applies if the project has been set as **public** in the project settings.
**Anonymous** is the default role of users who are not logged in. This only applies if you disabled the need for authentication for your instance and if the project is set as **public**.
Those two roles can't be deleted.
> **Note:** This allows the *Administrator* to delegate the administration of users to other people that should not have full control of the entire OpenProject installation (Administrator).

![create roles](system-guide-roles.png)
- **[Create, edit, and delete placeholder users](../placeholder-users/)**

After clicking the green **+ Role** button, a form will be shown to define the role and its permissions.
> **Note**: Users with this global permission cannot automatically see and edit all placeholder user in all projects. It is restricted to the placeholder users in projects in which the user has the respective permission to see or edit project member.
Complete the following as required:
### Edit and delete roles

1. **Role name** - must be entered and be a new name.
2. **Global Role** - this role applies to all projects, and can be assigned in the [user details](../users/#manage-user-settings) or in the [group details](../groups/#add-global-roles-to-a-group). Once saved, the decision to make a role global can't be reverted.
Ticking this box will show the available [global roles](#global-roles) and hide the regular permission options.
3. **Copy workflow from** - select an existing role. The respective [workflows](../../manage-work-packages/work-package-workflows) will be copied to the role to be created.
4. **Permissions** for this role - you can specify the permissions per OpenProject module. Click the arrow next to the module name to expand or compress the permissions list.
To edit an existing role, click on the role name in the roles overview table. Make your changes and save the update by clicking on the *Save* button at the bottom of the overview page.

Select the permissions which should apply for this role. You can use **check all** or **uncheck all** at the right of a module permissions list. If a module is not enabled in a project it is not shown to a user despite having a permission for it.
To delete an existing role click on the **delete icon** next to a role in the list.

Don't forget to click the **Save** button at the bottom of the page.
> **Note:** Roles that are assigned to a user cannot be deleted.
![create new role with role template](system-guide-new-role.png)
## FAQ for roles and permissions

**Note:** In the work package tracking section, you can also give the role permission to be able to be assigned to work packages or to be set as a responsible person.
### Can Administrators delegate the task to delete users?

No, only Administrators can delete other users.

## Edit and remove roles
### Can I set a default role for a user that creates a new project?

To edit a role navigate to the roles overview list and click on the role name. If is not a global role it cannot be converted into one.
You can set a [default role](../../system-settings/project-system-settings/#settings-for-new-projects) that users with this permission will have in a project they created.

To remove an existing role click on the **delete icon** next to a role in the list. It cannot be deleted if it is assigned to a user.
### Users do not see the action *Create project* in the main navigation even though they have the create project permission?

![Sys-admin-edit-roles](system-guide-edit-role1.png)
This is UX bug tracked in [#50123](https://community.openproject.org/wp/50123).

### What is the difference between a project permission and a global permission?

Project permissions controls what a user can see and do within a project scope. Project permissions are attached to **project roles**. You can grant a user a permission in a specific project by giving the user one or more project roles in a specific project.

## Global roles
Examples for project permissions:

To create a global role check the **Global Role** box when [creating a new role](#create-a-new-role).
* Create work packages
* Add comments to a work package

![global-roles-in-openproject](image-20210308171607279.png)
Global permissions are system wide. They are attached to **global roles** and controls what a user can do and see independent of a specific project memberships.

You can choose between these global permissions:
### Can I convert a project role to a global role?

- **Create project**: With this permission users can create new projects even when they are not system administrators.
[Here](../../system-settings/project-system-settings/#settings-for-new-projects) you can set a default role that users with this permission will have in a project they created.
- **Create and edit users**: Assign this permission to users who should be able to create or invite new users. They also can edit user profiles in a limited way.
Users with this permission can add users and edit a user's name, username, email address and language. Additionally, they can can see all users of your OpenProject instance. They can't delete or lock users.
They can only see the project membership of users for projects in which they have permission to see the members (e.g. as Project admin or Member). They can only manage project membership of users for projects in which they have permission to manage members (e.g. as Project admin).
The user profile will look like this for them (user name and email address were redacted): ![create-and-edit-users-role](image-20210308180635158.png)
- **Create, edit, and delete placeholder users**: Assign this permission to users (e.g. project admins) who should be able to manage [placeholder users](../placeholder-users).
Users with this permission can create, edit and delete placeholder users, as well as see all placeholder users in your OpenProject instance.
**Please note**: They can only see the project membership of placeholder users for projects in which they have permission to see the members (e.g. as Project admin or Member). They can only manage project membership of placeholder users for projects in which they have permission to manage members (e.g. as Project admin).
A placeholder user's profile will look like this for them: ![create-edit-and-delete-placeholder-users-role](image-20210308192119584.png)
- **Administrator**: Technically, the system administrator is also a global role. However, it can't be configured and is assigned to a user in another way. Find out more [here](../users/#general-settings).
No this is not possible. You need to create a new role instead.
2 changes: 1 addition & 1 deletion docs/user-guide/activity/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
sidebar_navigation:
title: Project Activity
title: Activity
priority: 890
description: Find out about the Activity within a project
keywords: activity
Expand Down

0 comments on commit f57b86c

Please sign in to comment.