Azure DevOps Authorisation

Managing whether an identity has access to a given service, feature, function, object, or method in Azure DevOps comes down to authorisation. Fortunately, by default, the DevOps permissions are set in such a way to enable you to focus on the job at hand, DevOps. Loosely translated this means 'don't get in my way'. My experience is that the Azure DevOps team have done a good job at this, enabling you to crack on developing, building, testing and releasing without much hindrance.

Working with relaxed permissions is great when you are the owner and possibly either a one man band or small team but as soon as we need to consider larger teams, varying roles with approvals and degrees of access, authorisation becomes a real concern.

I was recently involved in a project utilising offshore developers where trust was a concern and a number of specific teams handling specific roles needed to come together to approve a set of pipelines.

This article is a pick of findings and a memory jogger for me of some of the touch points encountered.

If you would like some hands on expertise for your business feel free to reach via my company assemblysoft

This assumes the connection has already been authenticated, more detail on authentication can be found under the references section below.

Authorisation

Authorisation is based on users and groups.

Security Groups

On top of this comes another layer of abstraction that of Azure DevOps security groups. Security groups assign a set of permissions to the members of the group. The members are either individuals or user groups, such as Active Directory, more on that later.

Azure DevOps comes pre-configured with default (built-in) security groups. Some thought has gone into the way different types of users (roles) will interact with Repos, Builds, Releases and much finer granularity but the out of the box groups are ready to be populated with members.

The groups are applied at three levels:

Server (TFS and Azure DevOps Server)
Organisation (also known as collection level)
Project

The levels are detailed below along with examples of the default security groups created for you out of the box.

Server-level

We can ignore Server for this discussion as it is essentially an on prem install and we are focusing on a purely cloud based solution. Links in the references section below provide more info about Azure DevOps Server or Team Foundation Server (TFS).

Organisation-level (Also referred to as Collection Level)

The default organisational security groups are shown below:

Default Permissions and Groups

Group name	Permissions	Membership

Project Collection Build Administrators	Has permissions to administer build resources and permissions for the collection.	Limit this group to the smallest possible number of users who need total administrative control over build servers and services for this collection.
Project Collection Build Service Accounts	Has permissions to run build services for the collection.	Limit this group to service accounts and groups that contain only service accounts.
Project Collection Proxy Service Accounts	Has permissions to run the proxy service for the collection.	Limit this group to service accounts and groups that contain only service accounts.
Project Collection Service Accounts	Has service level permissions for the collection and for Azure DevOps Server.	Contains the service account that was supplied during installation. This group should contain only service accounts and groups that contain only service accounts. By default, this group is a member of Team Foundation Administrators and Team Foundation Service Accounts.
Project Collection Test Service Accounts	Has test service permissions for the collection.	Limit this group to service accounts and groups that contain only service accounts.
Project Collection Valid Users	Has permissions to access team projects and view information in the collection.	Contains all users and groups that have been added anywhere within the collection. You cannot modify the membership of this group.

Project-level

Note* In order to create projects and add users to projects, you need to be added as a project administrator

Essentially, when working in an Azure cloud only model, you are either dealing with an Organisational group or a Project level group.

Note** Avoid changing the permissions of the default groups and instead, create custom security groups

Default Permissions and Groups

Group name	Permissions	Membership
Build Administrators	Has permissions to administer build resources and build permissions for the project. Members can manage test environments, create test runs, and manage builds.
Contributors	Has permissions to contribute fully to the project code base and work item tracking. The main permissions they don't have or those that manage or administer resources.	By default, the team group created when you create a project is added to this group, and any user you add to the team will be a member of this group. In addition, any team you create for a project will be added to this group by default, unless you choose a different group from the list.
Readers	Has permissions to view project information, the code base, work items, and other artifacts but not modify them.	Assign to members of your organization who you want to provide view-only permissions to a project. These users will be able to view backlogs, boards, dashboards, and more, but not add or edit anything. Typically, these are members who aren't granted an access level (Basic, Stakeholder, or other level) within the organization or on-premises deployment. who want to be able to view work in progress.
Project Administrators	Has permissions to administer all aspects of teams and project, although they can't create team projects.	Assign to users who manage user permissions, create or edit teams, modify team settings, define area an iteration paths, or customize work item tracking.
Project Valid Users	Has permissions to access the project. If you set the View collection-level information permission to Deny or Not set for this group, no users will be able to access the project.	Contains all users and groups that have been added anywhere within the project. You cannot modify the membership of this group.
{team name}	Has permissions to contribute fully to the project code base and work item tracking. The default Team group is created when you create a project, and by default is added to the Contributors group for the project. Any new teams you create will also have a group created for them and added to the Contributors group. You can grant permissions to administer team assets by adding members to the team administrator role.	Add members of the team to this group.

Custom Security Groups

When a scenario develops which requires finer granularity or a subset of another group, creating a custom group is the solution. For example, you may want a specific set of Team Admins that do not require all the project or organisational administrator permissions applied to a default administrator group but just a subset.

Note*** Whether creating a security group at the organisation or project level, the result is the same.

Group Membership

Adding Users and Groups to Azure DevOps can can be achieved via Active Directory (AD), Azure Active Directory (AAD), Individual Microsoft Accounts (MSA) or for on-premises deployments, local Windows users and groups.

Our discussion focuses on a the DevOps portal and Azure only so we can narrow that down further to AAD and MSA.

Using MSA works great for projects with limited users but as soon as you start dealing with teams, AAD is the way to go.

You can add individual users or AAD groups to either the default or custom security groups. When you do so, an entry automatically gets added to the Valid Users group (default) as this is required to connect to a project and is primarily limited to read access, such as view build, project and organisational information.

As a starting point, users that are required to 'get stuff done' will usually require access to the Contributors security group. For those only required to approve and review information, this may not be required.

Adding Members

Members can be individual users or more commonly AAD groups. This will lead to creating AAD groups for the types of roles within the organisation but targeted towards DevOps. Some examples might be 'Developers', 'Business Stakeholders', 'Build Admins' 'Release Admins' and at least one group which may act as a more general group with common permissions shared by other groups. Another tip I can recommend is to find a naming convention for the AAD groups which distinguishes them from other Azure DevOps groups, particularly when attempting to gain insight into who is a member of what further down the road.

Linking DevOps Organisation to AAD

Linking your DevOps organisation to AAD is a straight forward process using the link button in the portal, as shown below.

Teams

As well as the default groups created, you can also see above a default team has been created with the same name as the project.

Teams can drastically help the organisation of the development work underway. You can create 'feature' teams and add those as members of the Azure security groups. Work items and sprint planning can then be linked to specific teams. For the sake of brevity, we will not be going any deeper with teams in this article but bear in mind you will need to touch on them to group and get an overview of work at a team level.

Also be mindful that users and groups are assigned to your teams. Teams can then be added as members of the default or custom security groups, which are then impacted by the default or custom level of permissions assigned.

By default, the default team group and all other teams added to the project are included as members of the Contributors group. So adding new users to a team, automatically inherit Contributor permissions.

Note* In order to create teams and manage users, you need to be added as a project administrator or team administrator.

Permissions

The way to visualise permissions is that they are also applied at either the Organisational or Project level. Basically, does it affect the Organisation, which includes all projects within or does it only affect a specific project. Some permissions are only applicable to an Organisation or Project.

Each of the default groups comes pre-defined with a set of default permissions.

Permission controls access to specific functional tasks at different levels within the system.

The levels that permissions are applied to are identified below:

Server-level
Collection-level (Also known as Organisational level)
Project-level
Object-level - set permissions on a file, folder, build pipeline, or a shared query.

Organisational-level

Permission	Description
Administer build resource permissions	Can modify permissions for build pipelines at the organization or project collection-level. This includes: Set retention policies Set resource limits for pipelines Add and manage agent pools Add and manage deployment pools
Administer process permissions	Can modify permissions for customizing work tracking by creating and customizing inherited processes. Customize a project Add and manage processes Applies to Azure DevOps Services and Azure DevOps Server 2019. For Azure DevOps Services, users granted Basic and Stakeholder access are granted this permission by default.
Administer Project Server integration	Can configure the integration of Azure DevOps Server and Project Server to enable data synchronization between the two server products. Applies to TFS 2017 and earlier versions only.
Administer shelved changes	Can delete shelvesets created by other users. Applies when TFVC is used as the source control.
Administer workspaces	Can create and delete workspaces for other users. Applies when TFVC is used as the source control.
Alter trace settings	Can change the trace settings for gathering more detailed diagnostic information about Azure DevOps Web services.
Create a workspace	Can create a version control workspace. Applies when TFVC is used as the source control. The Create a workspace permission is granted to all users as part of their membership within the Project Collection Valid Users group.
Create new projects (formerly Create new team projects)	Can add Azure DevOps projects to an organization or project collection. Additional permissions may be required depending on your on-premises deployment.
Create process	Can create an inherited process used to customize work tracking and Azure Boards. Applies to Azure DevOps Services and Azure DevOps Server 2019 and later versions. Azure DevOps Services users granted Basic and Stakeholder access are granted this permission by default.
Delete field from account	Can delete a custom field that was added to a process. Applies to Azure DevOps Services and Azure DevOps Server 2019 and later versions. Azure DevOps Services users granted Basic and Stakeholder access are granted this permission by default.
Delete process	Can delete an inherited process used to customize work tracking and Azure Boards. Applies to Azure DevOps Services and Azure DevOps Server 2019. Azure DevOps Services users granted Basic and Stakeholder access for Azure DevOps Services are granted this permission by default.
Delete team project	Can delete Azure DevOps projects. Deleting a project will delete all data that is associated with the project. You cannot undo the deletion of a project except by restoring the collection to a point before the project was deleted.
Edit collection-level information	Can add users and groups, and edit collection-level permissions for users and groups. Edit collection-level information includes the ability to perform these tasks for all projects defined in a collection: Add and administer teams and all team-related features Create and modify areas and iterations Edit check-in policies Edit shared work item queries Edit project level and collection level permission ACLs Manage process templates Customize a project or process Create and modify global lists Edit event subscriptions (email or SOAP) on project or collection level events. When you set Edit collection-level information to Allow, users can add or remove collection-level groups and implicitly allows these users to modify version control permissions. To grant all these permissions at a command prompt, you must use the `tf.exe Permission` command to grant the AdminConfiguration and AdminConnections permissions, in addition to GENERIC_WRITE.
Edit process	Can edit a custom inherited process. Applies to Azure DevOps Services and Azure DevOps Server 2019. Azure DevOps Services users granted Basic and Stakeholder access for Azure DevOps Services are granted this permission by default.
Make requests on behalf of others	Can perform operations on behalf of other users or services. You should assign this permission only to on-premises service accounts.
Manage build resources	Can manage build computers, build agents, and build controllers.
Manage process template	Can download, create, edit, and upload process templates. A process template defines the building blocks of the work item tracking system as well as other sub-systems you access through Azure Boards. Applies to Azure DevOps Servers only.
Manage test controllers	Can register and de-register test controllers.
Trigger events	Can trigger project alert events within the collection. Assign only to service accounts. Users with this permission can't remove built-in collection level groups such as Project Collection Administrators.
Use build resources	Can reserve and allocate build agents. Assign only to service accounts for build services.
View build resources	Can view, but not use, build controllers and build agents that are configured for an organization or project collection.
View instance-level information or View collection-level information	Can view project collection-level group membership and permissions. If you set the View instance-level information permission to Deny or Not set for this group, no users will be able to access projects in the organization or project collection.
View system synchronization information	Can call the synchronization application programming interfaces. Assign only to service accounts.

Project-level

Permission	Description
Bypass rules on work item updates	Users with this permission can save a work item that ignores rules, such as assign value rules or conditional rules, defined for the work item type. Scenarios where this is useful are migrations where you don't want to update the by/date fields on import, or when you want to skip the validation of a work item. Rules can be bypassed in one of two ways. The first is through the Work Items - update REST API and setting the `bypassRules` parameter to `true`. The second is through the client object model, by initializing in bypassrules mode (initialize `WorkItemStore` with `WorkItemStoreFlags.BypassRules`). Users granted Basic and Stakeholder access are granted this permission by default.
Change process of project	Can change the Inheritance process for a project. To learn more, see Create and manage inherited processes. Applies to Azure DevOps Services and Azure DevOps Server 2019. Azure DevOps Services users granted Basic and Stakeholder access are granted this permission by default.
Create tag definition	Can add tags to a work item. By default, all members of the Contributors group have this permission. All users granted Stakeholder access for a private project can only add existing tags, not add new tags, even if the Create tag definition permission is set to Allow. This is part of the Stakeholder access settings. Azure DevOps Services users granted Stakeholder access for a public project are granted this permission by default.
Create test runs	Can add and remove test results and add or modify test runs. To learn more, see Control how long to keep test results and Run manual tests.
Delete and restore work items or Delete work items in this project	Can mark work items in the project as deleted. Azure DevOps Services users granted Stakeholder access for a public project are granted this permission by default. For Azure DevOps and TFS 2015.1 and later versions, the Contributors group has Delete and restore work items at the project-level set to "Allow" by default. For TFS 2015 and earlier versions, the Contributors group has Delete work items in this project at the project-level set to "Not set" by default. This setting causes the Contributors group to inherit the value from the closest parent that has it explicitly set.
Delete shared Analytics view	Can delete Analytics views that have been saved under the Shared area. Applies to Azure DevOps Services and Azure DevOps Server 2019.
Delete project	Can delete a project from an organization or project collection.
Delete test runs	Can delete a test run.
Edit project-level information	Can edit project level permissions for users and groups. Edit project-level information includes the ability to perform these tasks for the project: Create and modify areas and iterations Edit check-in policies Edit shared work item queries Edit project level permission ACLs Manage process templates Customize a project Create and modify global lists Edit event subscriptions (email or SOAP) on project level events.
Edit shared Analytics view	Can create and modify shared Analytics views. Applies to Azure DevOps Services and Azure DevOps Server 2019.
Manage project properties	Can provide or edit metadata for a project. For example, a user can provide high-level information about the contents of a project. Changing metadata is supported through the Set project properties REST API.
Manage test configurations	Can create and delete test configurations.
Manage test environments	Can create and delete test environments.
Move work items out of this project	Can move a work item from one project to another project within the collection. Applies to Azure DevOps Services and Azure DevOps Server 2019. Users granted Stakeholder access for a public project are granted this permission by default.
Permanently delete work items in this project	Can permanently delete work items from this project. Azure DevOps Services users granted Stakeholder access for a public project are granted this permission by default.
Rename project	Can change the name of the project.
Suppress notifications for work item updates	Users with this permission can update work items without generating notifications. This is useful when performing migrations of bulk updates by tools and want to skip generating notifications. Consider granting this permission to service accounts or users who have been granted the Bypass rules on work item updates permission. You can set the `suppressNotifications` parameter to `true` when updating working via Work Items - update REST API. Users granted Stakeholder access for a public project are granted this permission by default.
Update project visibility	Can change the project visibility from private to public or public to private. Applies to Azure DevOps Services only.
View analytics	Can access data available from the Analytics service. For details, see Permissions required to access the Analytics service. Applies to Azure DevOps Services and Azure DevOps Server 2019.
View project-level information	Can view project level group membership and permissions.
View test runs	Can view test plans under the project area path.

Object-level

Object level permissions are what they say on the tin. But it took me a while for the penny to drop. Each and every 'thing' we create in the portal is mostly defined as an object. For example, a build pipeline, a code branch, a release pipeline, file, folder etc. Each of these objects contain a more granular permission level by accessing the ellipses menu while the object is selected, which loads the familiar permissions dialog.

Object-level permissions can be seen below, highlighting specific permissions applied to a selected build pipeline.

Once again, the same set of security groups determine what permissions are allowed, which as stated previously will cover most scenarios 99% of the time.

Also bear in mind many of the object-level permissions follow a hierarchical model. In the above release pipeline scenario, the same set of permissions can be set for all release pipelines as shown below:

The above highlights that for the area of interest, it is first worth checking whether object-level permissions apply to ensure you are setting the permission at the right level for your requirements. (see scopes below)

At the other end of the spectrum, below highlights the same permissions being applied to a stage within the same release pipeline:

Another example is Git Repos, which also have a set of Object-level permissions, accessed via the project settings action bar.

There are also

Role - managed through a security role
Team - managed by an administrator team

Scopes

The above release-pipeline scenario highlights another level, that of scopes. When reading the documentation for a permission, take note of the scope column, which identifies at what scope a permission can be applied i.e project | release | pipeline or project | release | pipeline | stage. This will aid in confirming the level applied is the correct one for your given requirement/s.

Note* Project Collection Administrators are granted all collection-level permissions. Other collection-level groups have select permission assignments.

Permission Settings

Permission settings correspond to Allow, Deny, Inherited allow, Inherited deny, and Not set.

Allow or Deny explicitly grants or restricts users from performing specific tasks, and are usually inherited from group membership.

Not set implicitly denies users the ability to perform tasks that require that permission, but allows membership in a group that does have that permission set to take precedence, also known as Allow (inherited) or Inherited allow and Deny (inherited) or Inherited deny.

On most groups and almost all permissions, Deny overrides Allow. If a user belongs to two groups, and one of them has a specific permission set to Deny, that user is not able to perform tasks that require that permission even if they belong to a group that has that permission set to Allow.

For members of the Project Collection Administrators or Team Foundation Administrators groups, Deny doesn't trump Allow. Permissions assigned to these groups take precedence over any Deny set within any other group to which that member might belong.

Changing permission for a group changes that permission for all users who are members of that group. In other words, depending on the size of the group, you might affect the ability of hundreds of users to do their jobs by changing just one permission. So make sure you understand the impact before you make a change.

One feature of interest in tracking down how, or more precisely where, a permission has been applied is to use the 'Why?' link that is available when hovering over a given permission that is inherited. The trace permission feature gives an insight into where the permission is applied as shown:

Note* When navigating Groups at the Organisational level, ensure you use double click to move between groups resulting in an updated view of members and permissions. Single select, at the time of writing does not always update the details, which can lead to some confusion.

The most time consuming part of changing permissions in my experience has been finding the correct permission to apply. The reference section contains a handy Permissions lookup guide for Azure DevOps link which is essentially an index for specific permissions, grouped by Organisation | Project | Object | Role | Team

Access Levels

In order to access certain features of the Azure DevOps portal, users also need to be assigned an access level. The ones of interest are currently:

Basic
VS Enterprise
Stakeholder

By default, an organisation has 5 Basic licenses and unlimited Stakeholders. A license is assigned to a user by selecting the access level, as shown below. Additional licenses need to be purchased via the Azure Marketplace.

To do anything meaningful, other than read and comment, at least the Basic access level is required. A basic access level enables code, build, test, release and most of what is required to be productive.

Note* Applying access levels alone does not grant access to the project in the portal. Users still need to be added to a security group or team which is a member of an existing group.

Membership and Permission Management at a glance

Below is a infographic which helps to visualise the relationship between the built-in groups and corresponding permissions.

Conclusion

There is a fair bit to comprehend with Azure DevOps authorisation as it inherits much from TFS. Hopefully the areas covered in this article will get you up to speed as soon as possible by highlighting the touch points you will need to be aware of.

Also bear in mind there are a number of ways to skin a solution to your organisational needs. Once defined, it is important to remain consistent to keep a high degree of clarity.

During investigation, within a sandbox environment, the creation of AAD groups and MSA users with a specific goal in mind helped. I would encourage you to do the same and learn from doing across Repos, Builds and Release Pipelines.

If you would like some hands on expertise for your business feel free to reach via my company assemblysoft or checkout some other musings via my blazor.net and azure blog here carlrandall.net