Wednesday, 8 May 2019

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.



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 namePermissionsMembership
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 namePermissionsMembership
Build AdministratorsHas permissions to administer
build resources and build permissions
for the project. Members can manage
test environments, create test runs,
and manage builds.
ContributorsHas 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.
ReadersHas 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 AdministratorsHas 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

PermissionDescription
Administer build resource permissionsCan modify permissions for build pipelines at the organization or
project collection-level. This includes:
Administer process permissionsCan modify permissions for customizing work tracking by
creating and customizing inherited 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 integrationCan 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 changesCan delete shelvesets created by other users. Applies when TFVC is used as the source control.
Administer workspacesCan create and delete workspaces for other users. Applies when TFVC is used as the source control.
Alter trace settingsCan change the trace settings for gathering more detailed diagnostic information about Azure DevOps Web services.
Create a workspaceCan 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 processCan 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 accountCan 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 processCan 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 projectCan 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 informationCan 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 processCan 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 othersCan perform operations on behalf of other users or services. You should assign this permission only to on-premises service accounts.
Manage build resourcesCan manage build computers, build agents, and build controllers.
Manage process templateCan 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 controllersCan register and de-register test controllers.
Trigger eventsCan 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 resourcesCan reserve and allocate build agents. Assign only to service accounts for build services.
View build resourcesCan 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 informationCan call the synchronization application programming interfaces. Assign only to service accounts.

Project-level

PermissionDescription
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 projectCan 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 definitionCan 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 runsCan 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 viewCan delete Analytics views that have been saved under the Shared area. Applies to Azure DevOps Services and Azure DevOps Server 2019.
Delete projectCan delete a project from an organization or project collection.
Delete test runsCan delete a test run.
Edit project-level informationCan 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 viewCan create and modify shared Analytics views. Applies to Azure DevOps Services and Azure DevOps Server 2019.
Manage project propertiesCan 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 configurationsCan create and delete test configurations.
Manage test environmentsCan create and delete test environments.
Move work items out of this projectCan 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 projectCan 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 projectCan 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 visibilityCan change the project visibility from private to public or public to private. Applies to Azure DevOps Services only.
View analyticsCan 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 informationCan view project level group membership and permissions.
View test runsCan 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 AllowDenyInherited allowInherited 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.

References