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 investigate why a user doesn't have access to a project, service, or feature that they expect. 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:

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 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 have been explicitly denied permission to a feature. To determine whether it's 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 reevaluate 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 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 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 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.

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.

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

    Screenshot of filter box, enter user name.

    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.

Screenshot of 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.

  1. Select Project settings > Security, and then enter the user name into the filter box.

    Screenshot of enter user name into the filter box, Azure DevOps Server 2019.

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

  2. Trace why a user does or doesn't have any of the listed permissions. Hover over the permission, and then choose Why.

    Screenshot of Choose Why in permissions list view for project level information, Azure DevOps Server 2019.

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 they're in.

Screenshot of Trace showing inherited permissions, Azure DevOps Server 2019.

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 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.

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 Re-evaluate permissions. This function reevaluates your group memberships and permissions, and then any recent changes take effect immediately.

Screenshot of Reevaluate permissions control.

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:

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. 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 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.

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.

View, add, and manage permissions with CLI

You can view, add, and manage permissions at a more 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 get ranked in the following order: Subscriber > Basic + Test Plans > Basic > Stakeholder. Users always get the best access level between all the group rules, including Visual Studio (VS) subscription.

Note

  • Changes made to project readers through group rules don't persist. If you need to adjust project readers, consider alternative methods, such as direct assignment or custom security groups.
  • We recommend that you regularly review the rules listed on the "Group rules" tab of the "Users" page. If any changes get made to the Microsoft Entra ID group membership, these changes show up in the next re-evaluation of the group rules, which can be done on-demand, when a group rule gets 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 when you're trying to deploy 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 organization and project members. They receive emails but when signing in they receive an error 401.

Solution

You're likely signed into Azure DevOps with an incorrect identity. Complete 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 that says, "Sign out in progress." After you sign out, you're redirected to dev.azure.microsoft.com.

  4. Sign in to Azure DevOps again. Select your other identity.