Azure Synapse 的托管标识

项目
03/14/2024

本文将帮助你了解 Azure Synapse 中的托管标识（以前称为“托管服务标识/MSI”）及其工作原理。

注意

建议使用 Azure Az PowerShell 模块与 Azure 交互。请参阅安装 Azure PowerShell 以开始使用。若要了解如何迁移到 Az PowerShell 模块，请参阅将 Azure PowerShell 从 AzureRM 迁移到 Az。

概述

使用托管标识，则无需管理凭据。托管标识为服务实例提供一个标识，可以在连接到支持 Microsoft Entra 身份验证的资源时使用。例如，该服务可以使用托管标识来访问 Azure Key Vault 等资源，开发人员可以采用安全的方式存储凭据或访问存储帐户。该服务可以使用托管标识来获取 Microsoft Entra 令牌。

有两种类型的受支持托管标识：

系统分配的标识：可以直接在服务实例上启用托管标识。如果在创建服务期间允许系统分配的托管标识，则会在与该服务实例的生命周期相关联的 Microsoft Entra 中创建标识。按照设计，只有该 Azure 资源可使用此标识从 Microsoft Entra ID 请求令牌。因此，资源被删除时，Azure 会自动删除标识。 Azure Synapse Analytics 要求系统分配的托管标识必须与 Synapse 工作区一起创建。
用户分配：你也可以将托管标识创建为独立的 Azure 资源。可以创建用户分配的托管标识，并将其分配给 Synapse 工作区的一个或多个实例。对于用户分配的托管标识，标识与使用标识的资源分开进行管理。

托管标识提供以下优势：

在 Azure Key Vault 中存储凭据，在这种情况下，托管标识用于 Azure Key Vault 身份验证。
使用托管标识身份验证访问数据存储或计算，包括 Azure Blob 存储、Azure Data Lake Storage Gen2、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics、REST、Databricks 活动、Web 活动等。有关详细信息，请查看连接器和活动文章。
托管标识还用于通过存储在 Azure Key Vault 中的客户管理的密钥对数据和元数据进行加密/解密，从而提供双重加密。

系统分配的托管标识

注意

为了向后兼容，系统分配的托管标识在此文档和 Synapse Studio UI 的其他地方也称为“托管标识”。我们将在引用时明确提及“用户分配的托管标识”。

生成系统分配的托管标识

系统分配的托管标识按如下方式生成：

通过 Azure 门户或 PowerShell 创建 Synapse 工作区时，始终会自动创建托管标识。
通过 SDK 创建工作区时，只有在 Synapse 工作区对象中指定”Identity = new ManagedIdentity”以进行创建时，才会创建托管标识。请参阅 .NET 快速入门 - 创建数据工厂中的示例。
通过 REST API 创建 Synapse 工作区时，只有在请求正文中指定了“identity”部分时，才会创建托管标识。请参阅 REST 快速入门 - 创建数据工厂中的示例。

如果发现服务实例没有与以下检索托管标识说明相关的托管标识，可以使用标识发起程序以编程方式更新服务实例，从而显式生成一个托管标识：

使用 PowerShell 生成托管标识
使用 REST API 生成托管标识
使用 Azure 资源管理器模板生成托管标识
使用 SDK 生成托管标识

注意

无法修改托管标识。更新已包含托管标识的服务实例不会产生任何影响，并且托管标识将保持不变。
如果更新已包含托管标识的服务实例，但未在工厂对象或工作区对象中指定“identity”参数，或者未在 REST 请求正文中指定“identity”部分，你将会收到错误。
删除服务实例时，相关联的托管标识将一并删除。

使用 PowerShell 生成系统分配的托管标识

调用 New-AzSynapseWorkspace 命令，然后你会看到新生成的“Identity”字段：

PS C:\> $creds = New-Object System.Management.Automation.PSCredential ("ContosoUser", $password)
PS C:\> New-AzSynapseWorkspace -ResourceGroupName <resourceGroupName> -Name <workspaceName> -Location <region> -DefaultDataLakeStorageAccountName <storageAccountName> -DefaultDataLakeStorageFileSystem <fileSystemName> -SqlAdministratorLoginCredential $creds

DefaultDataLakeStorage           : Microsoft.Azure.Commands.Synapse.Models.PSDataLakeStorageAccountDetails
ProvisioningState                : Succeeded
SqlAdministratorLogin            : ContosoUser
VirtualNetworkProfile            :
Identity                         : Microsoft.Azure.Commands.Synapse.Models.PSManagedIdentity
ManagedVirtualNetwork            :
PrivateEndpointConnections       : {}
WorkspaceUID                     : <workspaceUid>
ExtraProperties                  : {[WorkspaceType, Normal], [IsScopeEnabled, False]}
ManagedVirtualNetworkSettings    :
Encryption                       : Microsoft.Azure.Commands.Synapse.Models.PSEncryptionDetails
WorkspaceRepositoryConfiguration :
Tags                             :
TagsTable                        :
Location                         : <region>
Id                               : /subscriptions/<subsID>/resourceGroups/<resourceGroupName>/providers/
                                   Microsoft.Synapse/workspaces/<workspaceName>
Name                             : <workspaceName>
Type                             : Microsoft.Synapse/workspaces

使用 REST API 生成系统分配的托管标识

注意

如果你试图更新已包含托管标识的服务实例，但未在工作区对象中指定“identity”参数，或者未在 REST 请求正文中提供“identity”部分，你将会收到错误。

调用以下 API 并在请求正文中包含“identity”部分：

PATCH https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Synapse/workspaces/{workspaceName}?api-version=2018-06-01

请求正文：添加 "identity": { "type": "SystemAssigned" }。

{
    "name": "<workspaceName>",
    "location": "<region>",
    "properties": {},
    "identity": {
        "type": "SystemAssigned"
    }
}

响应：自动创建托管标识并相应地填充 "identity" 部分。

{
    "name": "<workspaceName>",
    "tags": {},
    "properties": {
        "provisioningState": "Succeeded",
        "loggingStorageAccountKey": "**********",
        "createTime": "2021-09-26T04:10:01.1135678Z",
        "version": "2018-06-01"
    },
    "identity": {
        "type": "SystemAssigned",
        "principalId": "765ad4ab-XXXX-XXXX-XXXX-51ed985819dc",
        "tenantId": "72f988bf-XXXX-XXXX-XXXX-2d7cd011db47"
    },
    "id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Synapse/workspaces/<workspaceName>",
    "type": "Microsoft.Synapse/workspaces",
    "location": "<region>"
}

使用 Azure 资源管理器模板生成系统分配的托管标识

模版：添加 "identity": { "type": "SystemAssigned" }。

{
    "contentVersion": "1.0.0.0",
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "resources": [{
        "name": "<workspaceName>",
        "apiVersion": "2018-06-01",
        "type": "Microsoft.Synapse/workspaces",
        "location": "<region>",
        "identity": {
            "type": "SystemAssigned"
        }
    }]
}

使用 SDK 生成系统分配的托管标识

Workspace workspace = new Workspace
{
    Identity = new ManagedIdentity
    {
        Type = ResourceIdentityType.SystemAssigned
    },
    DefaultDataLakeStorage = new DataLakeStorageAccountDetails
    {
        AccountUrl = <defaultDataLakeStorageAccountUrl>,
        Filesystem = <DefaultDataLakeStorageFilesystem>
    },
    SqlAdministratorLogin = <SqlAdministratorLoginCredentialUserName>
    SqlAdministratorLoginPassword = <SqlAdministratorLoginCredentialPassword>,
    Location = <region>
};
client.Workspaces.CreateOrUpdate(resourceGroupName, workspaceName, workspace);

检索系统分配的托管标识

可以通过 Azure 门户或以编程方式检索托管标识。以下部分演示了一些示例。

提示

如果看不到托管标识，请通过更新服务实例来生成托管标识。

使用 Azure 门户检索系统分配的托管标识

可以通过 Azure 门户 -> 你的 Synapse 工作区 ->“属性”找到托管标识信息。

托管标识对象 ID

当你创建支持托管标识身份验证的链接服务（如 Azure Blob、Azure Data Lake Storage、Azure Key Vault 等）时，托管标识信息也会显示。

若要授予权限，请执行以下步骤。有关详细步骤，请参阅使用 Azure 门户分配 Azure 角色。

选择“访问控制(IAM)”。
选择“添加”>“添加角色分配”。
在“成员”选项卡上，选择“托管标识”，然后选择“选择成员”。
选择 Azure 订阅。
在“系统分配的托管标识”下，选择“Synapse 工作区”，然后选择一个工作区。也可以使用对象 ID 或工作区名称（作为托管标识名称）来查找此标识。若要获取托管标识的应用程序 ID，请使用 PowerShell。
在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

使用 PowerShell 检索系统分配的托管标识

获取特定的服务实例时，会返回托管标识主体 ID 和租户 ID，如下所示。使用 PrincipalId 授予访问权限：

PS C:\> (Get-AzSynapseWorkspace -ResourceGroupName <resourceGroupName> -Name <workspaceName>).Identity

IdentityType   PrincipalId                          TenantId                            
------------   -----------                          --------                            
SystemAssigned cadadb30-XXXX-XXXX-XXXX-ef3500e2ff05 72f988bf-XXXX-XXXX-XXXX-2d7cd011db47

可通过复制上面的主体 ID 并将主体 ID 作为参数运行以下 Microsoft Entra ID 命令来获取应用程序 ID。

PS C:\> Get-AzADServicePrincipal -ObjectId cadadb30-XXXX-XXXX-XXXX-ef3500e2ff05

ServicePrincipalNames : {76f668b3-XXXX-XXXX-XXXX-1b3348c75e02, https://identity.azure.cn/P86P8g6nt1QxfPJx22om8MOooMf/Ag0Qf/nnREppHkU=}
ApplicationId         : 76f668b3-XXXX-XXXX-XXXX-1b3348c75e02
DisplayName           : <workspaceName>
Id                    : cadadb30-XXXX-XXXX-XXXX-ef3500e2ff05
Type                  : ServicePrincipal

使用 REST API 检索托管标识

获取特定的服务实例时，会返回托管标识主体 ID 和租户 ID，如下所示。

在请求中调用以下 API：

GET https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Synapse/workspaces/{workspaceName}?api-version=2018-06-01

响应：你将获得如下所示的响应。 “标识”部分会相应进行填充。

{
  "properties": {
    "defaultDataLakeStorage": {
      "accountUrl": "https://exampledatalakeaccount.dfs.core.chinacloudapi.cn",
      "filesystem": "examplefilesystem"
    },
    "encryption": {
      "doubleEncryptionEnabled": false
    },
    "provisioningState": "Succeeded",
    "connectivityEndpoints": {
      "web": "https://web.azuresynapse.azure.cn?workspace=%2fsubscriptions%2{subscriptionId}%2fresourceGroups%2f{resourceGroupName}%2fproviders%2fMicrosoft.Synapse%2fworkspaces%2f{workspaceName}",
      "dev": "https://{workspaceName}.dev.azuresynapse.azure.cn",
      "sqlOnDemand": "{workspaceName}-ondemand.sql.azuresynapse.azure.cn",
      "sql": "{workspaceName}.sql.azuresynapse.azure.cn"
    },
    "managedResourceGroupName": "synapseworkspace-managedrg-f77f7cf2-XXXX-XXXX-XXXX-c4cb7ac3cf4f",
    "sqlAdministratorLogin": "sqladminuser",
    "privateEndpointConnections": [],
    "workspaceUID": "e56f5773-XXXX-XXXX-XXXX-a0dc107af9ea",
    "extraProperties": {
      "WorkspaceType": "Normal",
      "IsScopeEnabled": false
    },
    "publicNetworkAccess": "Enabled",
    "cspWorkspaceAdminProperties": {
      "initialWorkspaceAdminObjectId": "3746a407-XXXX-XXXX-XXXX-842b6cf1fbcc"
    },
    "trustedServiceBypassEnabled": false
  },
  "type": "Microsoft.Synapse/workspaces",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Synapse/workspaces/{workspaceName}",
  "location": "chinanorth3",
  "name": "{workspaceName}",
  "identity": {
    "type": "SystemAssigned",
    "tenantId": "72f988bf-XXXX-XXXX-XXXX-2d7cd011db47",
    "principalId": "cadadb30-XXXX-XXXX-XXXX-ef3500e2ff05"
  },
  "tags": {}
}

提示

若要从 ARM 模板检索托管标识，请在 ARM JSON 中添加“输出”部分：

{
    "outputs":{
        "managedIdentityObjectId":{
            "type":"string",
            "value":"[reference(resourceId('Microsoft.Synapse/workspaces', parameters('<workspaceName>')), '2018-06-01', 'Full').identity.principalId]"
        }
    }
}

使用系统分配的托管标识执行 Azure Synapse Spark Notebooks

通过从“配置会话”菜单中启用“以托管标识身份运行”，可以轻松地使用系统分配的托管标识（或工作区托管标识）执行 Synapse Spark Notebooks。若要使用工作区托管标识执行 Spark Notebooks，用户需要具有以下 RBAC 角色：

工作区或选定的 Spark 池上的 Synapse 计算操作员
工作区托管标识上的 Synapse 凭据用户

synapse-run-as-msi-1

synapse-run-as-msi-2

synapse-run-as-msi-3

注意

Synapse 笔记本和 Spark 作业定义仅支持通过链接服务和 mssparkutils API 使用系统分配的托管标识。 MSAL 和其他身份验证库无法使用系统分配的托管标识。可以改为生成服务主体，并将凭据存储在 Key Vault 中。

用户分配的托管标识

可以在 Microsoft Entra ID 中创建、删除、管理用户分配的托管标识。有关更多详细信息，请参阅使用 Azure 门户创建、列出、删除用户分配的托管标识或为其分配角色。

若要使用用户分配的托管标识，必须先在服务实例中为 UAMI 创建凭据。

注意

Synapse 笔记本和 Spark 作业定义当前不支持用户分配的托管标识。

后续步骤

创建凭据。

请参阅以下主题，其中介绍了使用托管标识的场景和方式：

在 Azure Key Vault 中存储凭据。

请参阅 Azure 资源的托管标识概述，了解有关 Azure 资源的托管标识（Azure Synapse 中的托管标识基于这些托管标识）的更多背景信息。