Troubleshoot access and permission issues
TFS 2017 | TFS 2015 | TFS 2013
Azure DevOps security and permission structure is extensive, so you may find yourself needing to investigate why you or a project member doesn’t have the access to a project, service, or feature that they expect to have. Find step-by-step guidance to understand and address problems a project member may be having in connecting to a project or accessing an Azure DevOps service or feature.
Before using this guide, we recommend that you're familiar with the following content:
- Get started with permissions, access, and security groups
- Default permissions and access quick reference.
- Quick reference index to Azure DevOps security
Tip
When you're creating an Azure DevOps security group, label it in a way that is easy to discern if it's created to limit access.
Permissions get set at one of the following levels:
- object level
- project level
- organization or project collection level
- security role
- team administrator role
Common access and permission issues
See the following most common reasons a project member can’t access a project, service, or feature:
| Issue | Troubleshooting action |
|---|---|
| Their access level doesn’t support access to the service or feature. | To discover if this is the cause, you want to determine the user's access level and subscription status. |
| Their membership within a security group doesn’t support access to a feature or they have been explicitly denied permission to a feature. | To discover if this is the cause, trace a permission. |
| The user has been recently granted permission, however a refresh is required for their client to recognize the changes. | Have the user refresh or re-evaluate their permissions. |
| The user's trying to exercise a feature granted only to a team administrator for a specific team, however they haven’t been granted that role. | To add them to the role, see Add, remove team administrator. |
| The user hasn’t enabled a preview feature. | Have the user open the Preview features and determine the on/off status for the specific feature. For more information, see Manage preview features. |
| Project member has been added to a limited scope security group, such as the Project-Scoped Users group. | To discover if this is a cause, look up the user’s security group memberships. |
Less common access and permission issues
Less common reasons for limited access are when one of the following events has occurred:
| Issue | Troubleshooting action |
|---|---|
| A project administrator disabled a service. In this case, no one has access to the disabled service. | To determine whether a service is disabled, see Turn an Azure DevOps service on or off. |
| A Project Collection Administrator disabled a preview feature, which disables it for all project members in the organization. | See Manage preview features. |
| Group rules governing the user’s access level or project membership are restricting access. | See Determine a user's access level and subscription status. |
| Custom rules have been defined to a work item type’s workflow. | see Rules applied to a work item type that restrict select operation. |
Determine a user's access level and subscription status
You can assign users or groups of users to one of the following access levels:
- Stakeholder
- Basic
- Basic + Test Plans
- Visual Studio subscription
For more information about access level restriction in Azure DevOps, see Supported access levels.
To use Azure DevOps features, users must be added to a security group with the appropriate permissions. Users also need access to the web portal. Limitations to select features get based on the access level and security group to which a user is assigned.
Users can lose access for the following reasons:
| Reason for loss of access | Troubleshooting action |
|---|---|
| The user's Visual Studio subscription has expired. | Meanwhile, this user can work as a Stakeholder, or you can give the user Basic access until the user renews their subscription. After the user signs in, Azure DevOps restores access automatically. |
| The Azure subscription used for billing is no longer active. | All purchases made with this subscription are affected, including Visual Studio subscriptions. To fix this issue, visit the Azure account portal. |
| The Azure subscription used for billing was removed from your organization. | Learn more about linking your organization |
Otherwise, on the first day of the calendar month, users who haven't signed in to your organization for the longest time lose access first. If your organization has users who don't need access anymore, remove them from your organization.
For more information about permissions, see Permissions and groups and the Permissions lookup guide.
Trace a permission
Use permission tracing to determine why a user's permissions aren't allowing them access to a specific feature or function. Learn how a user or an administrator can investigate the inheritance of permissions. To trace a permission from the web portal, open the permission or security page for the corresponding level. For more information, see Request an increase in permission levels.
If a user's having permissions issues and you use default security groups or custom groups for permissions, you can investigate where those permissions are coming from by using our permissions tracing. Permissions issues could be because the user doesn't have the necessary access level.
Users can receive their effective permissions either directly or via groups.
Complete the following steps so administrators can understand where exactly those permissions are coming from and adjust them, as needed.
Go to the Security page for the project that the user is having access problems.
Enter their name into the box in the upper left-hand corner.
You should have a user-specific view that shows what permissions they have.
Trace why a user does or doesn't have any of the listed permissions. Hover over the permission, and then choose Why.
The resulting trace lets you know how they're inheriting the listed permission. You can then adjust the user's permissions by adjusting those permissions provided to the groups they're in.
For more information, see Grant or restrict access to select features and functions or Request an increase in permission levels.
Refresh or reevaluate permissions
See the following scenario where refreshing or reevaluating permissions may be necessary.
Problem
Users get added to an Azure DevOps group. This action grants inherited access to an organization or project. But, they don't get access immediately. Users must either wait or sign out, close their browser, and then sign back in to get their permissions refreshed.
Solution
Within User settings, on the Permissions page, you can select Reevaluate permissions. This function reevaluates your group memberships and permissions, and then any recent changes take effect immediately.
Rules applied to a work item type that restrict select operations
Before you customize a process, we recommend that you review Configure and customize Azure Boards, which provides guidance on how to customize Azure Boards to meet your business needs.
For more information about work item type rules that apply toward restricting operations, see:
- Apply rules to workflow states (Inheritance process)
- Sample rule scenarios
- Define area paths and assign to a team
Hide organization settings from users
If a user's limited to seeing only their projects, or from seeing the organization settings, the following information may explain why. To restrict users from accessing organization settings, you can enable the Limit user visibility and collaboration to specific projects preview feature.
Examples of restricted users include Stakeholders, or members of a security group. Once enabled, any user or group added to the Project-Scoped Users group gets restricted from accessing the Organization Settings pages, except for Overview and Projects. They're restricted to accessing only those projects to which they've been added.
For more information about hiding organization settings from users, see Manage your organization, Limit user visibility for projects and more.
Use tools to fix permission
You can use the following tools to fix a user's permission issue.
TFSSecurity.exe - TFSSecurity is a command-line tool that can be used to view and update and delete permissions or groups.
Example usage:
tfssecurity /a+ Identity "81e4e4b5-bde0-4f2c-a7a5-4d25c2e8a81f\" Read "Project Collection Valid Users" ALLOW /collection:{collectionUrl}tfssecurity /a- Identity "3c7a0a47-27b4-4def-8d42-aab9b405fc8a\" Write n:"[Project1]\Contributors" DENY /collection:{collectionUrl}Use the public sproc
Example usage: Use
prc_pSetAccessControlEntryorprc_pRemoveAccessControlEntriesto add or remove ACEs directly from the security tables if TFSSecurity doesn't work for you.
For more information, see Use TFSSecurity to manage groups and permissions for Azure DevOps.