# 使用 Azure CLI 快速新增使用者到 Azure DevOps 組織並授予專案權限

最近公司正在急速的成長，經常需要新增 Azure DevOps Services 使用者帳號並設定專案權限，我今天特別將這些步驟全部寫成指令碼，之後直接複製貼上就可以單鍵完成設定。

> 以下命令皆使用 PowreShell 進行示範。

### 安裝 Azure CLI 並安裝 Azure DevOps Services 擴充命令

1.  安裝 Azure CLI 工具
    
    ```powershell
    choco install azure-cli -y
    ```
    
2.  登入 Azure
    
    ```powershell
    az login
    ```
    
3.  安裝 Azure DevOps Services 擴充命令
    
    ```powershell
    az extension add --name azure-devops
    ```
    
4.  設定組織預設值
    
    ```powershell
    az devops configure --defaults organization=https://dev.azure.com/YourOrgName
    ```
    

### 新增使用者到 Azure DevOps Services 組織

新增到使用者，最主要有兩個設定：

1.  輸入使用者的 E-mail 地址
    
    這個 E-mail 地址可能是 **微軟帳戶**([Microsoft Account](https://support.microsoft.com/en-us/windows/what-is-a-microsoft-account-4a7c48e9-ff5a-e9c6-5a5c-1a57d66c3bfa)) 或 **組織帳戶** ([Organizational Account](https://learn.microsoft.com/en-us/entra/identity-platform/v2-supported-account-types))
    
2.  設定授權類型
    
    你必須從 [About access levels](https://learn.microsoft.com/en-us/azure/devops/organizations/security/access-levels?view=azure-devops&WT.mc_id=DT-MVP-4015686) 的 [Programmatic mapping of access levels](https://learn.microsoft.com/en-us/azure/devops/organizations/security/access-levels?view=azure-devops&WT.mc_id=DT-MVP-4015686#programmatic-mapping-of-access-levels) 找到一個對應的 `AccountLicenseType`，目前可用的 `AccountLicenseType` 有 6 種：`stakeholder`, `express`, `advanced`, `none`, `earlyAdopter`, `professional`，但是常見大概只有前面 4 種！
    

以下我使用常見的 `AccountLicenseType` 分別說明新增使用者的指令：

> 我們假設 `$UserPrincipalName` 是 PowerShell 變數，並指向類似 `user@hotmail.com` 的電子郵件地址。

-   **Stakeholder**
    
    ```powershell
    az devops user add --email-id $UserPrincipalName --license-type "stakeholder"
    ```
    
-   **Basic**
    
    ```powershell
    az devops user add --email-id $UserPrincipalName --license-type "express"
    ```
    
-   **Basic + Test Plans**
    
    ```powershell
    az devops user add --email-id $UserPrincipalName --license-type "advanced"
    ```
    
-   **Visual Studio subscriber**
    
    ```powershell
    az devops user add --email-id $UserPrincipalName --license-type "none"
    ```
    

### 變更使用者 Azure DevOps 授權

由於 Azure DevOps 授權是[以天計費](https://learn.microsoft.com/en-us/azure/devops/organizations/billing/billing-faq?view=azure-devops&WT.mc_id=DT-MVP-4015686#what-s-the-difference-between-daily-pro-rated-charges-instead-of-monthly-committed-purchases-)的計價模式，如果使用者並不會立即使用 Azure DevOps 進階功能，這時可以設定比較便宜的授權，或是乾脆暫時設定為 `stakeholder` 免費的授權！

以下是更新 Azure DevOps 授權的指令範例：

-   **Stakeholder**
    
    ```powershell
    az devops user update --user $UserPrincipalName --license-type "stakeholder"
    ```
    
-   **Basic**
    
    ```powershell
    az devops user update --user $UserPrincipalName --license-type "express"
    ```
    
-   **Basic + Test Plans**
    
    ```powershell
    az devops user update --user $UserPrincipalName --license-type "advanced"
    ```
    
-   **Visual Studio subscriber**
    
    ```powershell
    az devops user update --user $UserPrincipalName --license-type "none"
    ```
    

### 新增使用者到特定專案下的特定群組

1.  首先，我們要先確定你要把使用者加入到哪個專案
    
    ```powershell
    $AzDO_Project = "TDCC_Futures"
    ```
    
2.  取得 Azure DevOps Services 特定專案的群組清單
    
    ```powershell
    # 取得 Azure DevOps Services 特定專案的群組清單
    $AzDO_Groups = $(az devops security group list -p $AzDO_Project -o json | ConvertFrom-Json)
    ```
    
3.  將成員加入 Contributors 群組
    
    ```powershell
    $AzDO_GroupName = "Contributors"
    
    $AzDO_GroupId = ($AzDO_Groups.graphGroups | Where-Object "displayName" -in "$AzDO_GroupName").descriptor
    az devops security group membership add --group-id $AzDO_GroupId --member-id $UserPrincipalName
    ```
    
    如果要加入專案管理員群組，可以改成：
    
    ```powershell
    $AzDO_GroupName = "Project Administrators"
    
    $AzDO_GroupId = ($AzDO_Groups.graphGroups | Where-Object "displayName" -in "$AzDO_GroupName").descriptor
    az devops security group membership add --group-id $AzDO_GroupId --member-id $UserPrincipalName
    ```
    
    目前預設的專案群組有：
    
    -   Contributors
    -   Project Administrators
    -   Build Administrators
    -   Project Valid Users
    -   Readers
    -   Release Administrators
    -   *TeamName* Team
4.  列出使用者目前擁有權限的專案清單
    
    ```powershell
    $AzDO_Projects = $(az devops user show --user $UserPrincipalName -o json | ConvertFrom-Json)
    $AzDO_Projects.projectEntitlements | ForEach-Object -Process {
        # $_.projectRef.id
        $_.projectRef.name
    }
    ```
    

### 相關連結

-   [Learn about Azure DevOps command line interface extension - Azure DevOps | Microsoft Docs](https://learn.microsoft.com/en-us/azure/devops/cli/?view=azure-devops&WT.mc_id=DT-MVP-4015686)
-   [az devops user | Microsoft Docs](https://learn.microsoft.com/en-us/cli/azure/devops/user?view=azure-cli-latest&WT.mc_id=DT-MVP-4015686)
-   [Add users to organizations and manage access - Azure DevOps | Microsoft Docs](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/add-organization-users?view=azure-devops&WT.mc_id=DT-MVP-4015686&tabs=azure-devops-cli)
-   [About access levels - Azure DevOps | Microsoft Docs](https://learn.microsoft.com/en-us/azure/devops/organizations/security/access-levels?view=azure-devops&WT.mc_id=DT-MVP-4015686#programmatic-mapping-of-access-levels)
-   [az devops security group | Microsoft Docs](https://learn.microsoft.com/en-us/cli/azure/devops/security/group?view=azure-cli-latest&WT.mc_id=DT-MVP-4015686)
-   [az devops security group membership | Microsoft Docs](https://learn.microsoft.com/en-us/cli/azure/devops/security/group/membership?view=azure-cli-latest&WT.mc_id=DT-MVP-4015686)
-   [Set project or collection-level permissions - Azure DevOps | Microsoft Docs](https://learn.microsoft.com/en-us/azure/devops/organizations/security/set-project-collection-level-permissions?view=azure-devops&WT.mc_id=DT-MVP-4015686&tabs=preview-page)