Azure Runbook为用户分配托管标识分配角色报错解决方案

在运行时版本为5.1的PowerShell Runbook中执行托管标识角色分配操作，使用命令如下：

$roleAssignment = New-AzRoleAssignment -ObjectId 'xxxx-xxxx-xxxx-xxxx' -Scope '/subscriptions/xxxx-xxxx-xxxx/resourceGroups/xxxxxxxxx' -RoleDefinitionName 'Contributor'

执行时触发泛型报错：

Exception of type 'Microsoft.Rest.Azure.CloudException' was thrown.

完全相同的命令在本地PowerShell ISE中执行可顺利完成角色分配，无报错。

该问题90%以上由三类原因导致：

1. Runbook实际执行身份（自动化账户关联的托管标识）缺少角色分配操作的对应权限：本地执行时使用的是个人登录的Azure AD账号权限，通常账号本身有较高的授权权限，但贡献者角色默认不包含创建/修改角色分配的权限，多数用户仅给自动化账户托管标识分配了贡献者角色，导致权限不足。
2. 自动化账户中导入的Az模块版本过旧：低版本Az.Resources模块在PowerShell 5.1运行时下存在已知bug，会吞掉API返回的具体错误信息，仅抛出无详情的CloudException泛型异常。
3. Runbook中未正确通过托管标识完成Azure认证，或参数存在拼写错误。

按顺序执行以下配置即可解决问题：

• 配置自动化账户托管标识的权限
  找到自动化账户启用的系统分配托管标识/绑定的用户分配托管标识，在要执行角色分配的目标作用域（对应资源组/订阅/管理组）上，给该托管标识授予用户访问管理员内置角色，该角色包含角色分配写入的最小权限，不会授予过度的资源操作权限。注意不要仅分配贡献者角色，贡献者无角色分配操作权限。
• 更新自动化账户的Az模块
  进入自动化账户的模块管理页，从模块库中更新Az.Accounts、Az.Resources两个模块到最新稳定版本，更新完成后确认模块版本不低于2.0，避免旧版本的异常吞错问题。
• 补全Runbook的认证逻辑
  在执行New-AzRoleAssignment命令前，必须先通过托管标识完成Azure认证，根据使用的托管标识类型选择对应命令：

  # 使用系统分配托管标识认证
  Connect-AzAccount -Identity
  
  # 使用用户分配托管标识认证时，替换为以下命令，<>中替换为用户分配托管标识的客户端ID
  # Connect-AzAccount -Identity -AccountId <用户分配托管标识客户端ID>
  

• 校验命令参数
  确认命令中-ObjectId为待授权主体的正确Azure AD对象ID，-Scope的资源ID无拼写错误，-RoleDefinitionName的角色名在目标作用域下真实存在。

如果按以上步骤配置后仍有报错，可以在角色分配命令前添加$DebugPreference = 'Continue'开启调试日志，再次执行Runbook即可看到Azure API返回的具体错误详情，快速定位剩余问题。

内容的提问来源于stack exchange，提问作者user6264