Managing your team and users
Last updated: October 14, 2021
Read time: 6 Minutes
This page describes the standard process for creating and managing users directly in Burp Suite Enterprise Edition. You also have the option to enable single sign-on so that you can manage users centrally. For more information, please refer to Configuring user groups and permissions for SSO.
You manage all settings related to users and authorizations from the "Team" page. This page contains tabs for users, groups, and roles:
- A user is an individual user or machine with access to the application.
- Roles are a set of permissions to perform specific types of action.
- A group is a group of users with a predefined set of roles. For example, rather than managing every role for each user individually, you can set roles centrally on the group level and assign users to the relevant group accordingly. Groups can also optionally be restricted to parts of the site tree.
The users tab shows details about the configured users, such as their name, email address, and their login type. The login type determines whether the user is an actual person who will log in using a password, or an API user. An API user is a virtual entity that is required to integrate Burp Suite Enterprise Edition with other software using either the REST API or GraphQL API.
The filter bar lets you show or hide users based on particular features. For example, you could choose to only show users who are locked out, or who have never logged in. Hovering the mouse over a user shows contextual options, such as disabling or deleting the user.
Creating a new user
Before creating new users, we recommend connecting your SMTP server first as this makes it much easier to invite new users to Burp Suite Enterprise Edition, reset passwords that users have forgotten, and so on.
- Log in as an administrator and go to "Team" > "Add a new user".
- Enter the basic details for the new user, such as their name, username, and email address.
- Select the login type "Password".
- Use the "Enabled" switch to decide whether you want the user to be able to log in right away, or whether you want to create the user first and only activate the account later.
- Select the groups to which this user should belong.
- When you are done, click "Save" in the upper-right corner. The new user should now appear in the list of users. If you have already connected your SMTP server, the user will automatically receive an email inviting them to complete the registration process and obtain their password. Otherwise, you will be prompted to copy a link, which you will have to send to the relevant user manually.
To edit an existing user, go to "Team" > "All users" and select the user from the list. You can then edit their details in the same way as you did when creating a new user.
You can also disable a user temporarily by hovering over the user in the list and clicking the "Disable user" switch on the right of the screen. Or you can delete a user completely by clicking the "Delete user" icon.
Note that you cannot change a user's login type.
Creating API users
If you want to integrate Burp Suite Enterprise Edition with other software, such as Jira or a CI system, you need to create a dedicated API user that the other software will use to authenticate communication with Burp Suite Enterprise Edition via either the REST API or GraphQL API.
API users cannot log in to the web UI.
- Log in as an administrator and go to "Team" > "Add a new user".
- Enter a name and username that will help you easily identify the user later, for example, "Jenkins Build".
- Enter an email address, for example, the email address of the admin user.
- Select the login type "API Key".
- When you are happy with your changes, click the save icon in the upper-right corner.
- When prompted, copy the API key and URL, and save them somewhere secure. You will need these later.
Note that you cannot retrieve the API key for an existing user. If you lose it, you will have to generate a new key and manually update any files where it's used.
A role is a set of permissions to perform specific types of action. Roles group together a number of individual permissions that are related or depend upon each other. It is generally useful to define roles that match the actual job functions of people within your team. This facilitates placing users into the right groups in a quick and reliable way.
On the "Team" page, the roles tab shows all the configured roles. There are various built-in roles that define common job functions, such as administrator, scan initiator, and so on. These cannot be modified. However, you can create your own custom roles as necessary by clicking the "New role" button.
Hovering the mouse over a role shows contextual options for that role, such as deleting it.
You can click into a role to view details. For custom roles, you can edit the role name and the assigned permissions.
There are dependencies between some permissions. Logically, the permission to edit an entity usually depends on having permission to view the same entity. When editing permissions, these dependencies are indicated on the UI - permissions whose prerequisite permission has not been selected will be grayed out and unavailable for selection.
A group is a group of users with a predefined set of roles. For example, rather than managing every role for each user individually, you can set roles centrally on the group level and assign users to the relevant group accordingly.
Groups can also optionally be restricted to parts of the sites tree. Users in the group will inherit the permissions that are defined in the assigned roles, subject to any restrictions on sites. Each user can belong to multiple groups, and will inherit the roles and permissions resulting from all of the groups to which they belong.
The groups tab of the "Team" page shows details of the configured groups, including the group name, user count, and any restrictions on sites.
Hovering the mouse over a group shows contextual options for that group, such as deleting it.
You can use the "New group" button to create a new group. By clicking on an existing group, you can view and edit the group name, its assigned roles, users, and any site restrictions that are defined for the group.
Restricting access to sites
Burp Suite Enterprise Edition supports role-based access control (RBAC) to help you restrict access to sensitive data and functionality to only those who need it. The roles assigned to a group allow for vertical segregation of privileges so that different categories of user can perform different types of action; for example, being able to initiate scans versus being able to view scan results. The ability to place restrictions on sites allows for horizontal segregation of privileges so that different categories of user can perform the same types of action on different data; for example, being able initiate scans for some sites versus others.
The primary use case for restrictions on sites is to support teams where different groups of people require access to different parts of an organization's infrastructure. For example:
- Different people have responsibility for operations, finance, and payroll applications.
- Different people have access to development, staging, and production systems.
- Different people handle applications in different geographical regions.
By default, groups have no restrictions on sites. This means that users in a group will have the defined roles in relation to all sites. In the group details, on the "Site restrictions" tab, you can configure a group to be restricted to certain sites. You can select parts of the site tree to which this group's roles apply. This can be folders or individual sites. Anything not explicitly allowed will be disallowed by default.
Within any folders that you select as allowed, you can deselect specific sites and subfolders that should be disallowed. This enables you to support various situations. For example, you might want to let a group view scan results for everything within the "Production" folder but disallow the "HR" folder beneath that, because its scan results might contain more sensitive information.