Patterns and Practices - Organization & Authorization Design
Organization Design
The Organization And Its Administration Processes
The organization in Azure DevOps is called MDTProductDevelopment which, in turn, is subdivided into projects that are based on products, capabilities or functional areas. Each project will have assigned managers to handle membership approvals.
This image is for illustration purposes to show what the structure will look like. It is not an accurate depiction of the structure of the organization nor are the names accurate.
There will be different default behaviors for capabilities and functional areas than what exists for the product based Projects. Product based Projects are shown in the image above in yellow boxes; shared projects are shown in green.
Specific examples would be that the Systems groups would need access to all Projects and all product teams should have Reader access to the DevOps backlogs. More information about DLs and access can be found in the remainder of this document.
Authorization Design
In the summer of 2020 Azure DevOps added Azure Active Directory (AAD) group-based processing that automates much of the group processing rules. The recommended design leverages the AAD groups we use already in the form of Distribution Lists (DLs). This approach minimizes manual work and takes advantage of the new group processing features. This is especially nice for automatic processing when a person leaves or joins the company or switches teams. It also allows group-based security memberships to be able to use it for both organization membership and project/role membership.
Starting with an understanding of how the group rule system works at the organization level in Azure DevOps influences how we manage security at levels below. The driving goal is to minimize manual work as people come and leave the company or change teams. By leveraging Azure AD Groups, managers will be approving who belongs in what group with what permissions.
Each user requires some sort of entitlement in Azure DevOps. The entitlement piece provides access to the organization and certain functionality in the org (such as test execution management). Review the Migration Workflow document to determine which entitlement DL a person belongs to, and review the table below to better understand what membership to each of these groups provides.
In addition to the entitlement / org DL, each user will be added to a DL to specify which team(s) they belong to and what level of access they have in that team (e.g. contributor or administrator). Note this is at least 2 DLs that a person must be a member of to gain contributor access to MDTProductDevelopment. Another important thing to remember about the use of DLs in Azure DevOps is that nested DLs will not work. This has been an issue / enhancement in Microsoft's backlog since 2016 as you can see at this link.
Entitlement / Org DL Explanation
| DL Name | Description | Default Permissions |
|---|---|---|
| DL MDTProductDevelopment MSDN | MDT Employees only Microsoft account identity comes from Visual Studio Subscription Seat cost is included in Subscription cost (approximately $2500 / year as of June 2021) |
Member of Contributors for Shared project Member of Readers group for all other projects |
| DL MDTProductDevelopment Consultant MSDN | MDT Consultant only Must set up an alternate Identity in VSS Seat cost is included in Subscription cost |
Member of Contributors for Shared project Member of Readers group for all other projects |
| DL MDTProductDevelopment Basic | Users who do not have a VSS and do not need access to test plans should be added to this group Microsoft account identity comes from Medtronic's Azure Active Directory (AAD) Note that the identity has to be in the form of [userid]@medtronic.com Seat cost is $6 / month |
Member of Contributors for Shared project Member of Readers group for all other projects |
| DL MDTProductDevelopment Basic - Test | Provides users access to Test Plans in addition to the other functionality available in Azure DevOps Seat cost is $52 / month |
Member of Contributors for Shared project Member of Readers group for all other projects |
| DL MDTProductDevelopment Stakeholder | Stakeholders can add to the discussion on work items and view information in Azure DevOps but they cannot view Wikis that are published via a repo nor can they modify any code or work items Seat cost is free |
Member of Readers group for all projects |
Team / Functional Area DL Explanation
| DL Type | Description |
|---|---|
| Team DL | Member of Project Contributors group for the project team Member of Readers group for other project teams (via the org DL, as described above) Read / write access to project backlogs, repos, etc Restricted access for creating (repos, new paths, etc) |
| Team Admin DL | Member of the Project Administrators group for the project team In addition to all the things that are true for contributors, admins can create repos, service connections, new paths |
| Functional Area DL | Member of Project Contributors group for all projects in MDTProductDevelopment org Read/write access to project backlogs, repos, etc Restricted access for creating (repos, new paths, etc) |
Key note: When combining access across the organization and projects, things can get tricky. Generally speaking the following rules apply: - The least restrictive settings apply within the same level (i.e. within a project or at the organization level). - So if you are in the Admin group and the Reader group you will get Admin access at that level. - The most restrictive settings apply between the project groups and org entitlement. - So if you are in the Project Admin group and have stakeholder entitlement at the org level, you will only have Stakeholder's capabilities (e.g. you will have reader permissions).
As yet another attempt to explain how things work, you can find a decoder ring table below that (might) better explain each scenario:
Group Access Decoder Ring
| Org Entitlement DL | Team / Functional DL | Overall Permissions |
|---|---|---|
| VSS | Admin | Admin in this project Contributor in Shared Reader in all other projects |
| VSS | Contributor (includes Functional areas) | Contributor in this project Contributor in Shared Reader in all other projects |
| VSS | Reader | Contributor in Shared Reader in all other projects |
| VSS with non-MDT identity | Admin | Reader in all projects (when the identity in VSS does not match the MDT identity used to log into AzDo) |
| Basic | Admin | Admin in this project Contributor in Shared Reader in all other projects |
| Basic | Contributor | Contributor in this project Contributor in Shared Reader in all other projects |
| Basic | Reader | Contributor in Shared Reader in all other projects |
| Basic + Test | Admin | Access to Test Plans and related functionality Admin in this project Contributor in Shared Reader in all other projects |
| Basic + Test | Contributor | Access to Test Plans and related functionality Contributor in this project Contributor in Shared Reader in all other projects |
| Basic + Test | Reader | Access to Test Plans and related functionality Contributor in Shared Reader in all other projects |
| Stakeholder | [any] | Reader in all projects |
Distribution List Management
Authentication for new employees and terminations are to be managed by their managers via AD group membership as per standard procedure. Visit this link to initiate DL related requests such as adding and removing members (which sends a notification to the group owner), changing the owner of the DL and more.
As we begin this transition, it will be important for the owners of these groups to understand the repercussions of group memberships. The Energizers team will meet with each team (at the project and team level) as they are transitioned to the new organization in Azure DevOps, and at that time we will cover the details of adding members to the AD groups to be used in Azure DevOps. We will review the default permissions described in this document and make adjustments to accommodate the team's needs if needed.
"With great power comes great responsibility"
It will be important for scalability purposes to scale the power and responsibility of group membership. The general approach to scale the management of these groups will be to start with the key contact for the product (which will be the grouping mechanism of the project in Azure DevOps). This person will be the owner or will identify the owner of the project administrator group. The Energizers will work with the group owner to create at least two groups - administrators and members. By working together we can ensure that the groups are named as expected and the project and/or team leaders have an understanding of what one "gets" with membership.
There is some opportunity for automating reminders and audits. Items that are in scope but not yet planned for this automation work include sending a reminder to group owners to review group membership on a regular cadence as well as providing an automated alert system to watch the Auditing menu in Azure DevOps at the organization level. Visit this link for information about the audit log in general and this link for information about accessing the audit logs and streams via an API which would be a key part of automating this.
Azure DevOps Groups Default Permissions
| DL Group Types | Boards & Repos Permission Group | Pipeline Service Connections | Artifacts - Feed Permissions | Test Plans Permissions |
|---|---|---|---|---|
| Project Administrators DL | Project Administrators | Project Administrators - Role: Administrator | Project Administrators - Role: Owner | Project Administrators |
| Project Members DL | Contributors | Project Collection Valid Users - Role: Reader for Prod ; Role: User for Pre-prod | Project Collection Valid Users - Role: Reader for Formal; Role: Contributor for Developer | Contributor |
| Service Account/Connection DL[6] | Project Collection Service Accounts | Project Service Accounts - Role: User | Project Collection Build Service - Role: Contributor | Project Collection Service Accounts |
| External Team DL | Readers or Contributors[1] or None[2] | Project Collection Valid Users - Role: Reader | Project Collection Valid Users - Role: Reader | Readers or Contributors[3] |
| Org Administrators DL | Project Collection [4] Administrators | Project Administrators - Role: Administrator | Project Administrators - Role: Owner | Project Administrators |
| Org Valid Users DL | Readers or None[5] | Project Collection Valid Users - Role: Reader | Project Collection Valid Users - Role: Reader | Readers |
Definitions - Project Administrators DL Group are Administrators of a team Project. - Project Members DL Group are Members of a team Project. - Service Account/Connection DL Group are any Azure DevOps Service Principal or Service Connection Account - An External Team DL Group are teams that aren't part of the same set of core "Identities" for the team Project (Quality, Regulatory, Reliability, RPE, etc) - Org Administrators DL Group are the Administrators of the Organization. - Org Valid Users DL Group are members of the Organization.
Footnotes - [1] When a DL of a team outside of the project teams' DLs that are assigned to the project. On a case by case basis it is decided if they get reader or contributor access to boards. - [2] When a DL of a team outside of the project teams' DLs that are assigned to the project. On a case by case basis it is decided if they get reader or no access to source code. - [3] When a DL of a team outside of the project teams' DLs that are assigned to the project. On a case by case basis it is decided if they get reader or contributor access to test plans. - [4] Org admins are Project Administrators on Boards and Project Collection Administrators on Repos - [5] Org valid users can read boards but have no access to code - [6] There will be more detail to add here as we onboard teams and learn more about users' needs.
The table below summarizes the roles and access that are assigned by default by Microsoft (and should be considered best practice). Note that these can be changed, but it is not recommended.
| Action / Role | Reader | Stakeholder | Contributor | Project Administrator | Org Administrator |
|---|---|---|---|---|---|
| Search items | Yes | Yes | Yes | Yes | Yes |
| See items | Yes | Yes | Yes | Yes | Yes |
| Comment on items | Yes | Yes | Yes | Yes | Yes |
| Alter items | No | Yes | Yes | Yes | Yes |
| Add items | No | Yes | Yes | Yes | Yes |
| Delete items | No | No | Yes | Yes | Yes |
| Manage items | No | No | Yes | Yes | Yes |
| Define temporal and work scope of items | No | No | No | Yes | Yes |
| Grant permissions to items | No | No | No | Yes | Yes |
| Restructure/re-organize items | No | No | No | Yes | Yes |
| Edit process | No | No | No | Usually No | Yes |
| Create / edit queries | No | No | No | Yes | Yes |
| Contribute to repos | No | No | Yes | Yes | Yes |
| Create / Delete Repos | No | No | No | Yes | Yes |
| Edit repo policies | No | No | No | Yes | Yes |
| Create / edit Pipelines | No | No | Pre-prod / Reader in Prod | Yes | Yes |
| Access Artifacts | No | No | Developer | Yes | Yes |
Use of existing security enabled DLs
Each project will have the need for at least two groups of people. Those groups should be the administrators and the members. For larger teams, there will be one group for the administrators and several groups for the members (i.e. contributors). To facilitate this management and align with the persistent teams vision we suggest that new security enabled DL groups are only requested when one doesn't already exist. The requirements are the following for these groups:
- The distribution list is security enabled and is exposed as an AAD group (most are automatically now for Office 365)
- The manager owning the distribution list understands that approving adds and removals of members to this group will change the employee, contractor or consultants access to Medtronic source code, work item planning and other assets.
- The group name will become the team name but can be changed in Azure DevOps by an administrator in the project.
Some existing groups will also be used to add people to have read only access to shared teams and to provide access to licensing.
If new DL based security groups are needed follow the recommended naming practices as provided by Global IT teams as part of the service now request for group creation, but make the name meaningful because it can be used for a lot more than just Azure DevOps security.
Auditing of manually granted security
For this security model to succeed we need to be vigilant about not manually enabling user security changes within project teams unless it is for a temporary and limited edge case we can't cover with the DL groups based design. This is because in the large system of Azure DevOps it will become extremely difficult to reason about security, rights, and membership if that is done too often. To that point an audit will be developed to watch out for membership and RBAC assignments in Azure DevOps that were manually done. This can be done with several automated techniques using the Azure DevOps API, the AAD user graph and a pipeline that runs on a schedule. That automation will produce a report for awareness that will be managed by the Azure DevOps org administration team.
It is our intention that initially the audit would flag places where administrators deviated from this DL based model. We would use this audit to work on process improvements and figure out how to handle these edge cases with a DL based design. If it becomes problematic and significant deviation from the design happens it might be necessary to change the audit into an automated notification of removal of these manually added membership and RBAC changes. At this point the recommendation of DL based security would change into a policy versus a recommended practice and the audit would change into a compliance remediation script.
Reasons why administrators might not follow the DL based model are usually related to timing (time to get a service now request implemented), uniqueness (a security need that doesn't match any existing pattern) or knowledge gaps (people not understanding how to change membership and RBAC). This audit would serve as a way to watch for, improve processes and possibly in the future correct these mistakes in use.
References
- https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/connect-organization-to-azure-ad?view=azure-devops
- https://azure.microsoft.com/en-us/pricing/details/devops/azure-devops-services/
- https://docs.microsoft.com/en-us/azure/devops/organizations/security/permissions?view=azure-devops&tabs=preview-page
- https://docs.microsoft.com/en-us/azure/devops/organizations/security/set-permissions-access-work-tracking?view=azure-devops
- https://docs.microsoft.com/en-us/azure/devops/organizations/security/set-permissions-access-test?view=azure-devops&tabs=preview-page
- https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-permissions?toc=%2Fazure%2Fdevops%2Forganizations%2Ftoc.json&bc=%2Fazure%2Fdevops%2Forganizations%2Fbreadcrumb%2Ftoc.json&view=azure-devops
- https://docs.microsoft.com/en-us/azure/devops/pipelines/policies/set-permissions?toc=%2Fazure%2Fdevops%2Forganizations%2Ftoc.json&bc=%2Fazure%2Fdevops%2Forganizations%2Fbreadcrumb%2Ftoc.json&view=azure-devops
- https://docs.microsoft.com/en-us/azure/devops/organizations/security/access-levels?view=azure-devops