迁移到群集配置的基于角色的细化访问权限Migrate to granular role-based access for cluster configurations

我们正在引入一些重要更改,以支持使用更细化的基于角色的访问来获取敏感信息。We are introducing some important changes to support more fine-grained role-based access to obtain sensitive information. 在实施这些更改的过程中,如果你使用的是某个受影响的实体/方案,则可能需要在 2019 年 9 月 3 日之前采取某种措施。As part of these changes, some action may be required by September 3, 2019 if you are using one of the affected entities/scenarios.

有什么变化?What is changing?

以前,处理“所有者”、“参与者”或“读取者”RBAC 角色的群集用户可以通过 HDInsight API 获取机密,因为这些机密可以通过给具有 */read 权限的任何人。Previously, secrets could be obtained via the HDInsight API by cluster users possessing the Owner, Contributor, or Reader RBAC roles, as they were available to anyone with the */read permission. 机密定义为值,可用于获取比用户角色允许的访问权限更高的权限。Secrets are defined as values that could be used to obtain more elevated access than a user's role should allow. 这些值包括群集网关 HTTP 凭据、存储帐户密钥和数据库凭据等值。These include values such as cluster gateway HTTP credentials, storage account keys, and database credentials. 从 2019 年 9 月 3 日开始,访问这些机密需要 Microsoft.HDInsight/clusters/configurations/action 权限,这意味着这些机密不再可供具有“读取者”角色的用户访问。Beginning on September 3, 2019, accessing these secrets will require the Microsoft.HDInsight/clusters/configurations/action permission, meaning they can no longer be accessed by users with the Reader role. 拥有此权限的角色为“参与者”、“所有者”和新的“HDInsight 群集操作员”角色(下面将详细说明)。The roles that have this permission are Contributor, Owner, and the new HDInsight Cluster Operator role (more on that below).

另外,我们正在引入新的 HDInisght 群集操作员角色,无需向此角色授予“参与者”或“所有者”的管理权限,即可让他们检索机密。We are also introducing a new HDInsight Cluster Operator role that will be able to retrieve secrets without being granted the administrative permissions of Contributor or Owner. 总结:To summarize:

角色Role 以前Previously NowNow
读取器Reader - 读取访问权限,包括机密- Read access, including secrets - 读取访问权限,包括机密- Read access, excluding secrets
HDInsight 群集操作员HDInsight Cluster Operator
(新角色)(New Role)
不适用N/A - 读/写访问权限,包括机密- Read/write access, including secrets
参与者Contributor - 读/写访问权限,包括机密- Read/write access, including secrets
- 创建和管理所有类型的 Azure 资源。- Create and manage all of types of Azure resources.
没有变化No change
所有者Owner - 读/写访问权限,包括机密- Read/write access including secrets
- 对所有资源的完全访问权限- Full access to all resources
- 将访问权限委托给其他人- Delegate access to others
没有变化No change

了解如何向用户添加 HDInsight 群集操作员角色分配,以授予其对群集机密的读/写访问权限的信息,请参阅以下部分将 HDInsight 群集操作员角色分配添加到用户For information on how to add the HDInsight Cluster Operator role assignment to a user to grant them read/write access to cluster secrets, see the below section, Add the HDInsight Cluster Operator role assignment to a user.

我是否受这些更改的影响?Am I affected by these changes?

以下实体和方案将受到影响:The following entities and scenarios are affected:

APIAPI

以下 API 将会更改或弃用:The following APIs will be changed or deprecated:

  • GET /configurations/{configurationName} (已删除敏感信息)GET /configurations/{configurationName} (sensitive information removed)
    • 以前用于获取单个配置类型(包括机密)。Previously used to obtain individual configuration types (including secrets).
    • 从 2019 年 9 月 3 日开始,此 API 调用现在会返回省略机密的单个配置类型。Beginning on September 3, 2019, this API call will now return individual configuration types with secrets omitted. 若要获取所有配置(包括机密),请使用新的 POST /configurations 调用。To obtain all configurations, including secrets, use the new POST /configurations call. 如果只要获取网关设置,请使用新的 POST /getGatewaySettings 调用。To obtain just gateway settings, use the new POST /getGatewaySettings call.
  • GET /configurations(已弃用)GET /configurations (deprecated)
    • 以前用于获取所有配置(包括机密)Previously used to obtain all configurations (including secrets)
    • 从 2019 年 9 月 3 日开始,此 API 调用将弃用且不再受支持。Beginning on September 3, 2019, this API call will be deprecated and no longer be supported. 今后若要获取所有配置,请使用新的 POST /configurations 调用。To obtain all configurations going forward, use the new POST /configurations call. 若要获取省略敏感参数的配置,请使用 GET /configurations/{configurationName} 调用。To obtain configurations with sensitive parameters omitted, use the GET /configurations/{configurationName} call.
  • POST /configurations/{configurationName} (已弃用)POST /configurations/{configurationName} (deprecated)
    • 以前用于更新网关凭据。Previously used to update gateway credentials.
    • 从 2019 年 9 月 3 日开始,此 API 调用将弃用且不再受支持。Beginning on September 3, 2019, this API call will be deprecated and no longer supported. 请改用新的 POST /updateGatewaySettings。Use the new POST /updateGatewaySettings instead.

已添加以下替换用的 API:The following replacement APIs have been added:

Azure HDInsight Tools for Visual Studio CodeAzure HDInsight Tools for Visual Studio Code

如果使用版本 1.1.1 或更低版本,请更新到最新版本的 Azure HDInsight Tools for Visual Studio Code,以避免中断。If you are using version 1.1.1 or below, update to the latest version of Azure HDInsight Tools for Visual Studio Code to avoid interruptions.

Azure Toolkit for IntelliJAzure Toolkit for IntelliJ

如果使用版本 3.20.0 或更低版本,请更新到最新版本的 Azure Toolkit for IntelliJ 插件,以避免中断。If you are using version 3.20.0 or below, update to the latest version of the Azure Toolkit for IntelliJ plugin to avoid interruptions.

用于 Visual Studio 的 Azure Data Lake 和流分析工具Azure Data Lake and Stream Analytics Tools for Visual Studio

更新到 2.3.9000.1 或更高版本的用于 Visual Studio 的 Azure Data Lake 和流分析工具可以避免中断。Update to version 2.3.9000.1 or later of Azure Data Lake and Stream Analytics Tools for Visual Studio to avoid interruptions. 如需更新方面的帮助,请参阅文档:更新用于 Visual Studio 的 Data Lake 工具For help with updating, see our documentation, Update Data Lake Tools for Visual Studio.

Azure Toolkit for EclipseAzure Toolkit for Eclipse

如果使用 3.15.0 或更低版本,请更新到最新版本的 Azure Toolkit for Eclipse,以避免中断。If you are using version 3.15.0 or below, update to the latest version of the Azure Toolkit for Eclipse to avoid interruptions.

SDK for .NETSDK for .NET

版本 1.x 和 2.xVersions 1.x and 2.x

请更新到 HDInsight SDK for .NET 版本 2.1.0Update to version 2.1.0 of the HDInsight SDK for .NET. 如果使用受这些更改影响的方法,则可能需要对代码进行少量的修改:Minimal code modifications may be required if you are using a method affected by these changes:

  • ClusterOperationsExtensions.GetClusterConfigurations不再返回敏感参数,例如存储密钥(核心站点)或 HTTP 凭据(网关)。ClusterOperationsExtensions.GetClusterConfigurations will no longer return sensitive parameters like storage keys (core-site) or HTTP credentials (gateway).

    • 今后若要检索所有配置(包括敏感参数),请使用 ClusterOperationsExtensions.ListConfigurationsTo retrieve all configurations, including sensitive parameters, use ClusterOperationsExtensions.ListConfigurations going forward. 请注意,具有“读取者”角色的用户将无法使用此方法。Note that users with the 'Reader' role will not be able to use this method. 这样便可以精细控制哪些用户可以访问群集的敏感信息。This allows for granular control over which users can access sensitive information for a cluster.
    • 如果只要检索 HTTP 网关凭据,请使用 ClusterOperationsExtensions.GetGatewaySettingsTo retrieve just HTTP gateway credentials, use ClusterOperationsExtensions.GetGatewaySettings.
  • ClusterOperationsExtensions.GetConnectivitySettings 现已弃用,已由 ClusterOperationsExtensions.GetGatewaySettings 取代。ClusterOperationsExtensions.GetConnectivitySettings is now deprecated and has been replaced by ClusterOperationsExtensions.GetGatewaySettings.

  • ClusterOperationsExtensions.ConfigureHttpSettings 现已弃用,已由 ClusterOperationsExtensions.UpdateGatewaySettings 取代。ClusterOperationsExtensions.ConfigureHttpSettings is now deprecated and has been replaced by ClusterOperationsExtensions.UpdateGatewaySettings.

  • ConfigurationsOperationsExtensions.EnableHttpDisableHttp 现已弃用。ConfigurationsOperationsExtensions.EnableHttp and DisableHttp are now deprecated. 现在始终会启用 HTTP,因此不再需要这些方法。HTTP is now always enabled, so these methods are no longer needed.

版本 3.x 及更高版本Versions 3.x and up

请更新到 HDInsight SDK for .NET 版本 5.0.0 或更高版本。Update to version 5.0.0 or later of the HDInsight SDK for .NET. 如果使用受这些更改影响的方法,则可能需要对代码进行少量的修改:Minimal code modifications may be required if you are using a method affected by these changes:

SDK for PythonSDK for Python

请更新到 HDInsight SDK for Python 版本 1.0.0 或更高版本。Update to version 1.0.0 or later of the HDInsight SDK for Python. 如果使用受这些更改影响的方法,则可能需要对代码进行少量的修改:Minimal code modifications may be required if you are using a method affected by these changes:

SDK For JavaSDK For Java

请更新到 HDInsight SDK for Java 版本 1.0.0 或更高版本。Update to version 1.0.0 or later of the HDInsight SDK for Java. 如果使用受这些更改影响的方法,则可能需要对代码进行少量的修改:Minimal code modifications may be required if you are using a method affected by these changes:

SDK For GoSDK For Go

请更新到 HDInsight SDK for Go 版本 27.1.0 或更高版本。Update to version 27.1.0 or later of the HDInsight SDK for Go. 如果使用受这些更改影响的方法,则可能需要对代码进行少量的修改:Minimal code modifications may be required if you are using a method affected by these changes:

Az.HDInsight PowerShellAz.HDInsight PowerShell

更新到 Az PowerShell 版本 2.0.0 或更高版本以避免中断。Update to Az PowerShell version 2.0.0 or later to avoid interruptions. 如果使用受这些更改影响的方法,则可能需要对代码进行少量的修改。Minimal code modifications may be required if you are using a method affected by these changes.

  • Grant-AzHDInsightHttpServicesAccess 现已弃用,已由新的 Set-AzHDInsightGatewayCredential cmdlet 取代。Grant-AzHDInsightHttpServicesAccess is now deprecated and has been replaced by the new Set-AzHDInsightGatewayCredential cmdlet.
  • Get-AzHDInsightJobOutput 在更新后支持对存储密钥进行细化的基于角色的访问。Get-AzHDInsightJobOutput has been updated to support granular role-based access to the storage key.
    • 具有 HDInsight 群集的“操作员”、“参与者”或“所有者”角色的用户将不受影响。Users with HDInsight Cluster Operator, Contributor, or Owner roles will not be affected.
    • 只具有“读者”角色的用户将需要显式指定 DefaultStorageAccountKey 参数。Users with only the Reader role will need to specify the DefaultStorageAccountKey parameter explicitly.
  • Revoke-AzHDInsightHttpServicesAccess 现已弃用。Revoke-AzHDInsightHttpServicesAccess is now deprecated. 现在始终会启用 HTTP,因此不再需要此 cmdlet。HTTP is now always enabled, so this cmdlet is no longer needed. 如需更多详细信息,请参阅 az.HDInsight 迁移指南See the az.HDInsight migration guide for more details.

向用户添加 HDInsight 群集操作员角色分配Add the HDInsight Cluster Operator role assignment to a user

具有所有者角色的用户可以将 HDInsight 群集操作员角色分配给你希望对敏感 HDInsight 群集配置值(如群集网关凭据和存储帐户密钥)具有读/写访问权限的用户。A user with the Owner role can assign the HDInsight Cluster Operator role to users that you would want to have read/write access to sensitive HDInsight cluster configuration values (such as cluster gateway credentials and storage account keys).

使用 Azure CLIUsing the Azure CLI

添加此角色分配的最简单方法是在 Azure CLI 中使用 az role assignment create 命令。The simplest way to add this role assignment is by using the az role assignment create command in Azure CLI.

备注

此命令必须由具有“所有者”角色的用户运行,因为只有他们才能授予这些权限。This command must be run by a user with the Owner role, as only they can grant these permissions. --assignee 是要将“HDInsight 群集操作员”角色分配到的用户的服务主体名称或电子邮件地址。The --assignee is the name of the service principal or email address of the user to whom you want to assign the HDInsight Cluster Operator role. 如果收到权限不足错误,请参阅下面的常见问题解答。If you receive an insufficient permissions error, see the FAQ below.

在资源(群集)级别授予角色Grant role at the resource (cluster) level

az role assignment create --role "HDInsight Cluster Operator" --assignee <user@domain.com> --scope /subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroupName>/providers/Microsoft.HDInsight/clusters/<ClusterName>

在资源组级别授予角色Grant role at the resource group level

az role assignment create --role "HDInsight Cluster Operator" --assignee user@domain.com -g <ResourceGroupName>

在订阅级别授予角色Grant role at the subscription level

az role assignment create --role "HDInsight Cluster Operator" --assignee user@domain.com

使用 Azure 门户Using the Azure portal

或者,可以使用 Azure 门户将 HDInsight 群集操作员角色分配添加到用户。You can alternatively use the Azure portal to add the HDInsight Cluster Operator role assignment to a user. 请参阅文档使用 RBAC 和 Azure 门户管理对 Azure 资源的访问 - 添加角色分配See the documentation, Manage access to Azure resources using RBAC and the Azure portal - Add a role assignment.

常见问题FAQ

更新 API 请求和/或工具后,为何会出现 403(禁止)响应?Why am I seeing a 403 (Forbidden) response after updating my API requests and/or tool?

群集配置现在受到精细的基于角色的访问控制,需要拥有 Microsoft.HDInsight/clusters/configurations/* 权限才能访问这些配置。Cluster configurations are now behind granular role-based access control and require the Microsoft.HDInsight/clusters/configurations/* permission to access them. 若要获取此权限,请将“HDInsight 群集操作员”、“参与者”或“所有者”角色分配到尝试访问配置的用户或服务主体。To obtain this permission, assign the HDInsight Cluster Operator, Contributor, or Owner role to the user or service principal trying to access configurations.

运行 Azure CLI 命令将“HDInsight 群集操作员”角色分配到另一个用户或服务主体时,为何会出现“权限不足,无法完成该操作”?Why do I see “Insufficient privileges to complete the operation” when running the Azure CLI command to assign the HDInsight Cluster Operator role to another user or service principal?

执行该命令的用户或服务主体除了要有“所有者”角色以外,还需要有足够的 AAD 权限来查找被分配者的对象 ID。In addition to having the Owner role, the user or service principal executing the command needs to have sufficient AAD permissions to look up the object IDs of the assignee. 此消息表示 AAD 权限不足。This message indicates insufficient AAD permissions. 尝试将 -–assignee 参数替换为 –assignee-object-id,并提供被分配者的对象 ID 作为参数,而不要提供名称(如果使用托管标识,则提供主体 ID)。Try replacing the -–assignee argument with –assignee-object-id and provide the object ID of the assignee as the parameter instead of the name (or the principal ID in the case of a managed identity). 有关详细信息,请参阅 Azure 角色分配创建文档的“可选参数”部分。See the optional parameters section of the az role assignment create documentation for more info.

如果仍然解决不了问题,请联系 AAD 管理员获取适当的权限。If this still doesn’t work, contact your AAD admin to acquire the correct permissions.

如果不采取任何措施,会发生什么情况?What will happen if I take no action?

从 2019 年 9 月 3 日开始,GET /configurationsPOST /configurations/gateway 调用将不再返回任何信息,GET /configurations/{configurationName} 调用将不再返回存储帐户密钥或群集密码等敏感参数。Beginning on September 3, 2019, GET /configurations and POST /configurations/gateway calls will no longer return any information and the GET /configurations/{configurationName} call will no longer return sensitive parameters, such as storage account keys or the cluster password. 对于相应的 SDK 方法和 PowerShell cmdlet,也是如此。The same is true of corresponding SDK methods and PowerShell cmdlets.

如果使用上述适用于 Visual Studio、VSCode、IntelliJ 或 Eclipse 的旧版工具之一,在更新之前,这些工具将不再可正常运行。If you are using an older version of one of the tools for Visual Studio, VSCode, IntelliJ or Eclipse mentioned above, they will no longer function until you update.

有关更多详细信息,请参阅本文档中适用于你的方案的相应部分。For more detailed information, see the corresponding section of this document for your scenario.