diff --git a/docs/content/admin/user_management/PRO__audit_log_index.md b/docs/content/admin/user_management/PRO__audit_log_index.md index ffa828ad8b0..31d9e677143 100644 --- a/docs/content/admin/user_management/PRO__audit_log_index.md +++ b/docs/content/admin/user_management/PRO__audit_log_index.md @@ -116,6 +116,9 @@ attributed to the user who triggered it. | Organization Group Assignment | ✅ | ✅ | ✅ | | Asset Member | ✅ | ✅ | ✅ | | Organization Member | ✅ | ✅ | ✅ | +| View As Session | ✅ | ✅ | ✅ | + +A View As Session's create is the start of a [View As User](../pro__view_as_user/) session and its update is the end. The browser session it ran in is never stored, only a digest of it, and the digest is excluded from the audit log. ### Pro — relationship (add / remove) events diff --git a/docs/content/admin/user_management/PRO__audit_logging.md b/docs/content/admin/user_management/PRO__audit_logging.md index 77ea1ddc980..af35565316e 100644 --- a/docs/content/admin/user_management/PRO__audit_logging.md +++ b/docs/content/admin/user_management/PRO__audit_logging.md @@ -36,6 +36,8 @@ Audit Logs track a variety of actions, including, but not limited to: - Creation and editing of User profiles. - EPSS percentile updates. +- Each [View As User](../pro__view_as_user/) session: an entry when it starts, naming the user who started it and the user viewed, and an entry when it ends, with how it ended. + The full list of changes and actions that are captured in Audit Logs can be found [here](../pro__audit_log_index/). ## Audit Logs Table diff --git a/docs/content/admin/user_management/PRO__permission_audit.md b/docs/content/admin/user_management/PRO__permission_audit.md new file mode 100644 index 00000000000..c2c14843ccb --- /dev/null +++ b/docs/content/admin/user_management/PRO__permission_audit.md @@ -0,0 +1,68 @@ +--- +title: "Permission Audit and Effective Access" +description: "See what every user and group can reach, why, and export it for an access review" +audience: pro +weight: 3 +--- + +Access in DefectDojo adds up from several places: a Global Role, Roles on Organizations and Assets, Roles held through Groups, Organization Types, and Configuration Permissions. The **Permission Audit** mode on the Users list and the **Access** tab on each user's page bring those together, so an administrator can answer "who can see this, and why" without opening every Asset. + +These pages are part of **Access Administration**, a beta feature that is on by default. A Superuser can turn it off under **Settings > Feature Flags**. + +## Who can use it + +Permission Audit and the Access tab of another user are shown to Superusers, Global Owners, and users who hold the permission to view users. Every user can open the Access tab on their own page. + +Counts and lists only include what the person reading them can see. An Asset or Organization the reader cannot see is never named. On the Access tab it is counted under its table ("And 4 more you cannot see."). + +## Permission Audit on the Users list + +1. Navigate to **Settings > Users & Permissions > Users**. +2. Click **Permission Audit** in the table toolbar. Click it again to return to the usual list. + +In Permission Audit mode the list adds these columns: + +* **Flags**: Elevated, No Access and Inactive (see below). +* **Global Roles**: the user's own Global Role and those of their Groups. +* **Configuration Permissions**: how many Configuration Permissions the user holds. +* **Organizations** and **Assets**: how many the user holds a Role on, directly, through a Group, through an Organization Type, or (for Assets) through their Organization. A user with a Global Role, and a Superuser, shows **All**. +* **Groups**: the Groups the user belongs to. + +Each column can be filtered, and the counts can be sorted. Clicking a username opens that user's **Access** tab. + +### The three flags + +| Flag | Shown when | +| --- | --- | +| **Elevated** | The user is a Superuser, holds a Global Role with Owner-level permissions, holds any Configuration Permission, or belongs to a Group that holds a Global Role. | +| **No Access** | The user has no Asset or Organization Role, no Global Role and no Group. | +| **Inactive** | The user has not signed in for 90 days, or never has. | + +A useful review starts with **Elevated** and **Inactive** together: accounts that hold broad access they no longer use. + +### Exporting + +With Permission Audit on, **Export** offers the audit columns alongside the usual user fields. The export contains the same users as the list, with the same filters applied. + +## The Access tab on a user's page + +Open a user and select the **Access** tab. It shows: + +* An **Access Summary**: the user's flags, Global Roles and Configuration Permissions, each with where it comes from. +* **Organizations**, **Assets** and **Groups** tables, each listing the Role and a **Via** column: **Direct**, **Group** with the Group's name, **Facet** with the Organization Type, or (for Assets) the **Organization** the Asset is reached through. + +Each table can be searched by name and filtered by Via. An Asset can appear more than once when the user reaches it in more than one way, for example directly and through its Organization. + +A Global Role reaches every Asset and Organization its permissions allow, so it is listed once in the summary rather than as one row per object. + +## A Group's Overview + +A Group's page opens on its **Overview** tab, which shows the Group's members count and what the Group reaches in its own right: its Global Role, its Configuration Permissions, and its Organizations and Assets, with the same Via column. Every member of the Group receives this access through it. When the Group holds a Global Role, the Overview says that the Group has instance-wide access. + +## Preview a Role + +When **View As User** is turned on, the Access tab also shows **Preview Role**. Choose a Role and an Organization or an Asset, and click **Preview** to see what that Role would reach there and the permissions the Role carries. Nothing is granted and no user is created. + +## API + +These pages read endpoints of the DefectDojo Pro UI and are not part of the public API. diff --git a/docs/content/admin/user_management/PRO__view_as_user.md b/docs/content/admin/user_management/PRO__view_as_user.md new file mode 100644 index 00000000000..d05d01d11de --- /dev/null +++ b/docs/content/admin/user_management/PRO__view_as_user.md @@ -0,0 +1,45 @@ +--- +title: "View As User" +description: "See DefectDojo the way another user sees it, read-only and audited" +audience: pro +weight: 4 +--- + +**View As User** shows the application as another user sees it: the same pages, lists, counts and menus that user would get. It is meant for checking access before and after a change, for example before a new team is onboarded. The view is read-only, lasts at most an hour, and every start and stop is written to the Audit Log. + +View As User is a beta feature and is off by default. A Superuser turns it on under **Settings > Feature Flags**. + +## Who can view as whom + +The **View As** button appears on a user's page when you may view as that user: + +* A Superuser, or a user who holds the permission to edit users, may view as any user. +* A user who can manage the members of a Group (the Manage Members permission of their own Role in that Group) may view as any member of that Group. + +In every case: + +* The user being viewed may not be a Superuser, and may not be inactive. +* You must already be able to see everything that user can see. If they can see Organizations or Assets that you cannot, the button is disabled and its tooltip says how many, for example "You cannot view as this user: they can see 3 assets you cannot." +* You cannot view as yourself, and a View As session cannot be started from inside another one. +* Service users cannot start View As. A service user can be viewed as, which shows what its token can reach. + +## While viewing as a user + +1. Open the user's page and click **View As**. A group lead who cannot open users' pages starts it from the group instead: on the group's **Members** tab, choose the member under **View As a Member** and click **View As**. +2. The application reloads as that user. A bar across the top of the page reads "Viewing as . Read-only." with an **Exit** button. + +While the bar is shown: + +* Everything is read-only. Controls that would change data are hidden or disabled, and a change sent anyway is refused with "Read-only while viewing as ." +* Sign-in credentials are not available: the user's API token, MFA settings and recovery codes cannot be read while viewing as them. +* Walkthroughs are turned off, since they record progress. +* Only the Pro UI is affected. API requests made with an API token, and the Classic UI, still act as you. +* In the last ten minutes the bar shows the time left. + +## Ending View As + +The session ends when you click **Exit**, when you sign out, or after one hour. **Exit** returns you to the user's page as yourself. + +## Audit Log + +Each session is recorded as a **View As Session** in the Audit Log: one entry when it starts, naming the actor and the user viewed, and one when it ends, with how it ended (**Exit**, **Logout**, **Expired** or **Revoked**). A session is revoked when the viewed user becomes a Superuser or is deactivated, when View As User is turned off, or when you no longer pass the rules above (they are checked again every minute while the session runs). diff --git a/docs/content/admin/user_management/create_user_group.md b/docs/content/admin/user_management/create_user_group.md index f0eb83c06dc..09d5a38e070 100644 --- a/docs/content/admin/user_management/create_user_group.md +++ b/docs/content/admin/user_management/create_user_group.md @@ -32,6 +32,13 @@ Users with the **View Group** configuration permission see every Group. A Member ## Viewing A Group +With Access Administration on (Pro), a Group's page has three tabs: + +* **Overview**: the number of members and what the Group reaches in its own right: its Global Role, its Configuration Permissions, and the Organizations and Assets it holds a Role on, with how each Asset is reached. Every member of the Group receives this access through it. A Group that holds a Global Role is marked as having instance-wide access. +* **Members**: the Group's details, Configuration Permissions and members, as described below. +* **Access**: the Group's Roles on Organizations and Assets, with **Add to Organization**, **Add to Asset**, **Change Role** and **Remove**. Each change is checked against your permissions on that Organization or Asset, exactly as on its own Members dialog. + + Viewing a group displays all Group information, such as ID, name, description, global roles, etc. The Group Members, Organizations, and Assets associated with the group are also displayed. ![image](images/group_view_pro_ui.png) diff --git a/docs/content/admin/user_management/set_user_permissions.md b/docs/content/admin/user_management/set_user_permissions.md index bcbd80c2a49..7caea608420 100644 --- a/docs/content/admin/user_management/set_user_permissions.md +++ b/docs/content/admin/user_management/set_user_permissions.md @@ -112,6 +112,23 @@ An Asset Role will supersede a user’s standard Organization Role or Global Rol However, this does not work in reverse. If a User has an Organization Role or Global Role of **Owner**, assigning them a **Reader** role on a particular Asset will not take away their **Owner** permissions. **Roles cannot take away permissions granted to a User by other Roles, they can only add additional permissions.** +### Give a Role from the User's page (Pro) + +With Access Administration on, a user's page has **Organizations** and **Assets** tabs that list the Roles the user holds directly, and change them without leaving the user. + +1. Navigate to **Settings > Users & Permissions > Users** and open the User. +2. Select the **Organizations** or **Assets** tab and click **Add to Organization** or **Add to Asset**. +3. Choose one or more Organizations or Assets. Only those where you can manage Members are listed, and those the User already holds a Role on are left out. +4. Choose the Role and click **Submit**. + +Each item is checked exactly as it is on its own Members dialog: the **Owner** Role is offered only when you can grant it on every selected item, and an item that refuses is listed in the window with the reason while the others are saved. The ⋮ menu on each row offers **Change Role** and **Remove**. + +The **Access** tab on the same page lists everything the User reaches and why. See [Permission Audit and Effective Access](../pro__permission_audit/). + +### Add or remove several Users at once (Pro) + +On the Users list, select the Users and use **Add To** or **Remove From** above the table, then choose **Group**, **Organization** or **Asset**. The window lists the selected Users; pick the targets (and, when adding, the Role) and click **Submit**. Each User and target pair is its own request with its own permission check. When some pairs are refused, the window stays open and names each one with the reason, for example a User who is already a Member or not a Member at all. + ## Configuration Permissions Many configuration dialogues and API endpoints can be enabled for users or groups of users, regardless of their superuser status. These Configuration Permissions allow regular users to access and contribute to parts of DefectDojo outside of their standard Asset or Asset Role assignment.