Troubleshoot access and permission issues

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Due to the extensive security and permission structure of Azure DevOps, you might need to investigate why a user lacks access to a project, service, or feature they expect. Find step-by-step guidance to understand and address issues a user might encounter when connecting to a project or accessing an Azure DevOps service or feature.

Prerequisites

Permissions: To manage permissions or groups at the organization or collection level, be a member of the Project Collection Administrators security group. If you created the organization or collection, you're automatically a member of this group.

Recommended: Before using this guide, we recommend getting familiar with the following content:

• Get started with permissions, access, and security groups
• Default permissions and access quick reference.

Tip

When you're creating an Azure DevOps security group, label it clearly to indicate if it's intended to limit access.

You can set permissions at the following levels:

• Object level
• Project level
• Organization or project collection level
• Security role
• Team administrator role

Common access and permission issues

See the 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 determine whether it's the cause, determine the user's access level and subscription status.
Their membership within a security group doesn’t support access to a feature or they were explicitly denied permission to a feature.	To determine whether it's the cause, trace a permission.
The user was recently granted permission but their client needs a refresh to recognize the changes.	Have the user refresh or reevaluate their permissions.
The user's trying to exercise a feature granted only to a team administrator for a specific team, however they aren't granted that role.	To add them to the role, see Add, remove team administrator.
The user didn't enable 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 was added to a limited scope security group, such as the Project-Scoped Users group.	To determine whether it's the 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 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 were 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 restricting access levels in Azure DevOps, see Supported access levels.

To use Azure DevOps features, users must be added to a security group with the appropriate permissions and have access to the web portal. Feature limitations are based on the user's access level and security group.

Users can lose access for the following reasons:

Reason for loss of access	Troubleshooting action
The user's Visual Studio subscription 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 didn't sign 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 is having permissions issues, and you use default security groups or custom groups for permissions, use tracing to investigate where those permissions are coming from. Permissions issues could be because of delayed changes. It can take up to 1 hour for Microsoft Entra group memberships or permissions changes to propagate throughout Azure DevOps. If a user's having issues that don't resolve immediately, wait a day to see if they resolve. For more information about user and access management, see Manage users and access in Azure DevOps.

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.

1. Select Project settings > Permissions > Users, and then select the user.

   

   You should now have a user-specific view that shows what permissions they have.

2. To trace why a user does or doesn't have any of the listed permissions, select the information icon next to the permission in question.

The resulting trace lets you know how they're inheriting the listed permission. You can then adjust the user's permissions by adjusting the permissions that are provided to the groups that they're in.

For more information, see Manage access to specific features and functions or Request an increase in permission levels.

Refresh or reevaluate permissions

See the following scenario where refreshing or reevaluating permissions might be necessary.

Problem

Users get added to an Azure DevOps or Microsoft Entra 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

Go to User settings > Permissions > Re-evaluate 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 is limited to seeing only their projects or can't access organization settings, the following information might explain why. To restrict users from accessing organization settings, enable the Limit user visibility and collaboration to specific projects preview feature. For more information, including important security-related call-outs, see Manage your organization, Limit user visibility for projects and more.

Examples of restricted users include Stakeholders, Microsoft Entra guest users, or members of a security group. Once enabled, any user or group added to the Project-Scoped Users group is restricted from accessing the Organization settings pages, except for Overview and Projects. They can only access the projects to which they get added.

For more information, see Manage your organization, Limit user visibility for projects and more.

View, add, and manage permissions with CLI

You can view, add, and manage permissions at a granular level with the az devops security permission commands. For more information, see Manage permissions with command line tool.

Group rules with lesser permissions

Group rule types are ranked in the following order: Subscriber > Basic + Test Plans > Basic > Stakeholder. Users always receive the highest access level available to them across all group rules, including any Visual Studio (VS) subscriptions.

Note

• Changes made to project readers through group rules don't persist. To adjust project readers, consider alternative methods such as direct assignment or custom security groups.
• Regularly review the rules listed on the "Group rules" tab of the "Users" page. Changes to Microsoft Entra ID group membership will appear in the next re-evaluation of the group rules, which can be done on-demand, when a group rule is modified, or automatically every 24 hours. Azure DevOps updates Microsoft Entra group membership every hour, but it may take up to 24 hours for Microsoft Entra ID to update dynamic group membership.

See the following examples, showing how subscriber detection factors into group rules.

Example 1: Group rule gives me more access

If I have a VS Pro subscription and I'm in a group rule that gives me Basic + Test Plans – what happens?

Expected: I get Basic + Test Plans because what the group rule gives me is greater than my subscription. Group rule assignment always provides the greater access, rather than limiting access.

Example 2: Group rule gives me the same access

I have a Visual Studio Test Pro subscription and I'm in a group rule that gives me Basic + Test Plans – what happens?

Expected: I get detected as a Visual Studio Test Pro subscriber, because the access is the same as the group rule. I'm already paying for the Visual Studio Test Pro, so I don't want to pay again.

Work with GitHub

See the following troubleshooting information for deploying code in Azure DevOps with GitHub.

Problem

You can't bring the rest of your team into the organization and project, despite adding them as members. They receive emails, but when signing in, they get a 401 error.

Solution

You might be signed into Azure DevOps with an incorrect identity. Do the following steps:

1. Close all browsers, including browsers that aren't running Azure DevOps.

2. Open a private or incognito browsing session.

3. Go to the following URL: https://aka.ms/vssignout.

   A message displays, "Sign out in progress." After you sign out, you get redirected to dev.azure.microsoft.com.

4. Sign in to Azure DevOps again and choose a different identity.

Other areas where permissions might be applied

• Area path permissions
• Work item tags
• Moved work items out of a project
• Deleted work items
• Quick guide to default permissions and access for Azure Boards
• Custom rules
• Sample custom rule scenarios
• Custom backlogs and boards
• Custom controls

Related articles

• Manage permissions with the command line tool
• Change individual or group permissions
• Security best practices
• Add users to an administrator role