使用 Azure PowerShell 建立或更新 Azure 自定義角色

發行項
06/03/2024

如果 Azure 內建角色不符合組織的特定需求，您可以建立自己的自定義角色。本文說明如何使用 Azure PowerShell 列出、建立、更新或刪除自定義角色。

如需如何建立自定義角色的逐步教學課程，請參閱教學課程：使用 Azure PowerShell 建立 Azure 自定義角色。

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。若要開始使用，請參閱安裝 Azure PowerShell。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

必要條件

若要建立自定義角色，您需要：

建立自定義角色的許可權，例如使用者存取管理員 istrator
Azure Cloud Shell 或 Azure PowerShell

列出自訂角色

若要列出可在範圍指派的角色，請使用 Get-AzRoleDefinition 命令。下列範例會列出所選訂用帳戶中可用於指派的所有角色。

Get-AzRoleDefinition | FT Name, IsCustom

Name                                              IsCustom
----                                              --------
Virtual Machine Operator                              True
AcrImageSigner                                       False
AcrQuarantineReader                                  False
AcrQuarantineWriter                                  False
API Management Service Contributor                   False
...

下列範例只會列出可在所選訂用帳戶中指派的自定義角色。

Get-AzRoleDefinition -Custom | FT Name, IsCustom

Name                     IsCustom
----                     --------
Virtual Machine Operator     True

如果選取的訂用帳戶不在角色的中 AssignableScopes ，將不會列出自定義角色。

列出自定義角色定義

若要列出自定義角色定義，請使用 Get-AzRoleDefinition。這與您用於內建角色的命令相同。

Get-AzRoleDefinition <role_name> | ConvertTo-Json

PS C:\> Get-AzRoleDefinition "Virtual Machine Operator" | ConvertTo-Json

{
  "Name": "Virtual Machine Operator",
  "Id": "00000000-0000-0000-0000-000000000000",
  "IsCustom": true,
  "Description": "Can monitor and restart virtual machines.",
  "Actions": [
    "Microsoft.Storage/*/read",
    "Microsoft.Network/*/read",
    "Microsoft.Compute/*/read",
    "Microsoft.Compute/virtualMachines/start/action",
    "Microsoft.Compute/virtualMachines/restart/action",
    "Microsoft.Authorization/*/read",
    "Microsoft.ResourceHealth/availabilityStatuses/read",
    "Microsoft.Resources/subscriptions/resourceGroups/read",
    "Microsoft.Insights/alertRules/*",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/11111111-1111-1111-1111-111111111111"
  ]
}

下列範例只會列出角色的動作：

(Get-AzRoleDefinition <role_name>).Actions

PS C:\> (Get-AzRoleDefinition "Virtual Machine Operator").Actions

"Microsoft.Storage/*/read",
"Microsoft.Network/*/read",
"Microsoft.Compute/*/read",
"Microsoft.Compute/virtualMachines/start/action",
"Microsoft.Compute/virtualMachines/restart/action",
"Microsoft.Authorization/*/read",
"Microsoft.ResourceHealth/availabilityStatuses/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Insights/alertRules/*",
"Microsoft.Insights/diagnosticSettings/*",
"Microsoft.Support/*"

建立自訂角色

若要建立自定義角色，請使用 New-AzRoleDefinition 命令。使用物件或 JSON 範本建構角色 PSRoleDefinition 的方法有兩種。

取得資源提供者的作業

當您建立自定義角色時，請務必知道來自資源提供者的所有可能作業。您可以檢視資源提供者作業的清單，或使用 Get-AzProviderOperation 命令來取得此資訊。例如，如果您想要檢查虛擬機的所有可用作業，請使用此命令：

Get-AzProviderOperation <operation> | FT OperationName, Operation, Description -AutoSize

PS C:\> Get-AzProviderOperation "Microsoft.Compute/virtualMachines/*" | FT OperationName, Operation, Description -AutoSize

OperationName                                  Operation                                                      Description
-------------                                  ---------                                                      -----------
Get Virtual Machine                            Microsoft.Compute/virtualMachines/read                         Get the propertie...
Create or Update Virtual Machine               Microsoft.Compute/virtualMachines/write                        Creates a new vir...
Delete Virtual Machine                         Microsoft.Compute/virtualMachines/delete                       Deletes the virtu...
Start Virtual Machine                          Microsoft.Compute/virtualMachines/start/action                 Starts the virtua...
...

使用 PSRoleDefinition 物件建立自定義角色

當您使用PowerShell建立自訂角色時，您可以使用其中一個內建角色作為起點，也可以從頭開始。本節中的第一個範例會以內建角色開頭，然後使用更多許可權加以自定義。編輯屬性以新增您想要的 Actions、 NotActions或 AssignableScopes ，然後將變更儲存為新角色。

下列範例會從虛擬機參與者內建角色開始，以建立名為 Virtual Machine Operator 的自定義角色。新的角色會授與 Microsoft.Compute、Microsoft.儲存體 和 Microsoft.Network 資源提供者之所有讀取動作的存取權，並授與啟動、重新啟動及監視虛擬機的存取權。自定義角色可用於兩個訂用帳戶。

$role = Get-AzRoleDefinition "Virtual Machine Contributor"
$role.Id = $null
$role.Name = "Virtual Machine Operator"
$role.Description = "Can monitor and restart virtual machines."
$role.Actions.Clear()
$role.Actions.Add("Microsoft.Storage/*/read")
$role.Actions.Add("Microsoft.Network/*/read")
$role.Actions.Add("Microsoft.Compute/*/read")
$role.Actions.Add("Microsoft.Compute/virtualMachines/start/action")
$role.Actions.Add("Microsoft.Compute/virtualMachines/restart/action")
$role.Actions.Add("Microsoft.Authorization/*/read")
$role.Actions.Add("Microsoft.ResourceHealth/availabilityStatuses/read")
$role.Actions.Add("Microsoft.Resources/subscriptions/resourceGroups/read")
$role.Actions.Add("Microsoft.Insights/alertRules/*")
$role.Actions.Add("Microsoft.Support/*")
$role.AssignableScopes.Clear()
$role.AssignableScopes.Add("/subscriptions/00000000-0000-0000-0000-000000000000")
$role.AssignableScopes.Add("/subscriptions/11111111-1111-1111-1111-111111111111")
New-AzRoleDefinition -Role $role

下列範例示範另一種建立 虛擬機操作員 自定義角色的方式。它會從建立新的 PSRoleDefinition 對象開始。動作會在變數中 perms 指定，並設定為 Actions 屬性。從NotActions虛擬機參與者內建角色讀取 NotActions 來設定屬性。由於虛擬機參與者沒有任何 NotActions，因此不需要此行，但它會顯示如何從另一個角色擷取資訊。

$role = [Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition]::new()
$role.Name = 'Virtual Machine Operator 2'
$role.Description = 'Can monitor and restart virtual machines.'
$role.IsCustom = $true
$perms = 'Microsoft.Storage/*/read','Microsoft.Network/*/read','Microsoft.Compute/*/read'
$perms += 'Microsoft.Compute/virtualMachines/start/action','Microsoft.Compute/virtualMachines/restart/action'
$perms += 'Microsoft.Authorization/*/read'
$perms += 'Microsoft.ResourceHealth/availabilityStatuses/read'
$perms += 'Microsoft.Resources/subscriptions/resourceGroups/read'
$perms += 'Microsoft.Insights/alertRules/*','Microsoft.Support/*'
$role.Actions = $perms
$role.NotActions = (Get-AzRoleDefinition -Name 'Virtual Machine Contributor').NotActions
$subs = '/subscriptions/00000000-0000-0000-0000-000000000000','/subscriptions/11111111-1111-1111-1111-111111111111'
$role.AssignableScopes = $subs
New-AzRoleDefinition -Role $role

使用 JSON 範本建立自定義角色

JSON 範本可作為自定義角色的來源定義。下列範例會建立自定義角色，以允許讀取記憶體和計算資源的存取權、支援存取權，並將該角色新增至兩個訂用帳戶。使用下列範例建立新的檔案 C:\CustomRoles\customrole1.json 。標識元應該在初始角色建立時設定為 null ，因為系統會自動產生新的標識碼。

{
  "Name": "Custom Role 1",
  "Id": null,
  "IsCustom": true,
  "Description": "Allows for read access to Azure storage and compute resources and access to support",
  "Actions": [
    "Microsoft.Compute/*/read",
    "Microsoft.Storage/*/read",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000",
    "/subscriptions/11111111-1111-1111-1111-111111111111"
  ]
}

若要將角色新增至訂用帳戶，請執行下列 PowerShell 命令：

New-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"

更新自訂角色

類似於建立自定義角色，您可以使用物件或 JSON 範本來修改現有的自訂角色 PSRoleDefinition 。

使用 PSRoleDefinition 物件更新自定義角色

若要修改自定義角色，請先使用 Get-AzRoleDefinition 命令來擷取角色定義。其次，對角色定義進行所需的變更。最後，使用 Set-AzRoleDefinition 命令來儲存修改的角色定義。

下列範例會將 Microsoft.Insights/diagnosticSettings/* 動作新增至 虛擬機操作員 自定義角色。

$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.Actions.Add("Microsoft.Insights/diagnosticSettings/*")
Set-AzRoleDefinition -Role $role

PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.Actions.Add("Microsoft.Insights/diagnosticSettings/*")
PS C:\> Set-AzRoleDefinition -Role $role

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111}

下列範例會將 Azure 訂用帳戶新增至虛擬機操作員自定義角色的可指派範圍。

Get-AzSubscription -SubscriptionName Production3

$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")
Set-AzRoleDefinition -Role $role

PS C:\> Get-AzSubscription -SubscriptionName Production3

Name     : Production3
Id       : 22222222-2222-2222-2222-222222222222
TenantId : 99999999-9999-9999-9999-999999999999
State    : Enabled

PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")
PS C:\> Set-AzRoleDefinition -Role $role

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111,
                   /subscriptions/22222222-2222-2222-2222-222222222222}

下列範例會將管理群組新增至AssignableScopes虛擬機操作員自定義角色。

Get-AzManagementGroup

$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/{groupId1}")
Set-AzRoleDefinition -Role $role

PS C:\> Get-AzManagementGroup

Id          : /providers/Microsoft.Management/managementGroups/marketing-group
Type        : /providers/Microsoft.Management/managementGroups
Name        : marketing-group
TenantId    : 99999999-9999-9999-9999-999999999999
DisplayName : Marketing group

PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/marketing-group")
PS C:\> Set-AzRoleDefinition -Role $role

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111,
                   /subscriptions/22222222-2222-2222-2222-222222222222,
                   /providers/Microsoft.Management/managementGroups/marketing-group}

使用 JSON 範本更新自定義角色

使用先前的 JSON 範本，您可以輕鬆地修改現有的自定義角色來新增或移除動作。更新 JSON 範本並新增網路讀取動作，如下列範例所示。範本中所列的定義不會累計套用至現有的定義，這表示角色會與您在範本中指定的完全一樣顯示。您也需要使用角色的識別碼來更新 [標識符] 欄位。如果您不確定此值是什麼，您可以使用 Get-AzRoleDefinition Cmdlet 來取得此資訊。

{
  "Name": "Custom Role 1",
  "Id": "acce7ded-2559-449d-bcd5-e9604e50bad1",
  "IsCustom": true,
  "Description": "Allows for read access to Azure storage and compute resources and access to support",
  "Actions": [
    "Microsoft.Compute/*/read",
    "Microsoft.Storage/*/read",
    "Microsoft.Network/*/read",
    "Microsoft.Support/*"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000",
    "/subscriptions/11111111-1111-1111-1111-111111111111"
  ]
}

若要更新現有的角色，請執行下列 PowerShell 命令：

Set-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"

刪除自定義角色

拿掉任何使用自定義角色的角色指派。如需詳細資訊，請參閱尋找刪除自定義角色的角色指派。

使用 Remove-AzRoleDefinition 命令來刪除自定義角色。

下列範例會 移除虛擬機操作員 自定義角色。

Get-AzRoleDefinition "Virtual Machine Operator"
Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition

PS C:\> Get-AzRoleDefinition "Virtual Machine Operator"

Name             : Virtual Machine Operator
Id               : 88888888-8888-8888-8888-888888888888
IsCustom         : True
Description      : Can monitor and restart virtual machines.
Actions          : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
                   Microsoft.Compute/virtualMachines/start/action...}
NotActions       : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
                   /subscriptions/11111111-1111-1111-1111-111111111111}

PS C:\> Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition

Confirm
Are you sure you want to remove role definition with name 'Virtual Machine Operator'.
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): Y

共用方式為