Использование управляемых удостоверений в Службе приложений и Функциях AzureHow to use managed identities for App Service and Azure Functions

В этой статье показано, как создавать управляемое удостоверение для приложений Службы приложений и Функций Azure, а также как их использовать для получения доступа к другим ресурсам.This topic shows you how to create a managed identity for App Service and Azure Functions applications and how to use it to access other resources.

Важно!

При переносе приложения между подписками или клиентами управляемые удостоверения для Службы приложений и Функций Azure не будут работать в надлежащем режиме.Managed identities for App Service and Azure Functions won't behave as expected if your app is migrated across subscriptions/tenants. Для приложения нужно получить новое удостоверение, отключив службу и включив ее снова.The app needs to obtain a new identity, which is done by disabling and re-enabling the feature. См. раздел Удаление удостоверения ниже.See Removing an identity below. Также нужно обновить политики доступа для всех зависимых ресурсов, чтобы они использовали новое удостоверение.Downstream resources also need to have access policies updated to use the new identity.

Управляемое удостоверение от Azure Active Directory (Azure AD) позволяет приложению легко получать доступ к другим ресурсам, защищенным Azure AD, таким как Azure Key Vault.A managed identity from Azure Active Directory (Azure AD) allows your app to easily access other Azure AD-protected resources such as Azure Key Vault. Удостоверения управляются платформой Azure, и для них не нужно подготавливать или изменять секреты.The identity is managed by the Azure platform and does not require you to provision or rotate any secrets. Дополнительные сведения об управляемых удостоверениях в Azure AD см. в статье Что такое управляемые удостоверения для ресурсов Azure?For more about managed identities in Azure AD, see Managed identities for Azure resources.

Приложению можно предоставить два типа удостоверений:Your application can be granted two types of identities:

  • Назначаемое системой удостоверение привязывается к приложению и удаляется при удалении приложения.A system-assigned identity is tied to your application and is deleted if your app is deleted. Приложение может иметь только одно назначаемое системой удостоверение.An app can only have one system-assigned identity.
  • Назначаемое пользователем удостоверение — это изолированный ресурс Azure, который можно назначить приложению.A user-assigned identity is a standalone Azure resource that can be assigned to your app. Приложение может иметь несколько назначаемых пользователем удостоверений.An app can have multiple user-assigned identities.

Добавление назначаемого системой удостоверенияAdd a system-assigned identity

Чтобы создать приложение с назначаемым системой удостоверением, необходимо задать дополнительное свойство в приложении.Creating an app with a system-assigned identity requires an additional property to be set on the application.

Использование портала AzureUsing the Azure portal

Чтобы настроить управляемое удостоверение на портале, сначала необходимо создать обычное приложение, а затем активировать соответствующую функцию.To set up a managed identity in the portal, you will first create an application as normal and then enable the feature.

  1. Создайте приложение на портале обычным образом.Create an app in the portal as you normally would. Перейдите к нему на портале.Navigate to it in the portal.

  2. Если используется приложение-функция, перейдите к функциям платформы.If using a function app, navigate to Platform features. Для других типов приложений прокрутите вниз до группы параметров в левой области навигации.For other app types, scroll down to the Settings group in the left navigation.

  3. Выберите Удостоверение.Select Identity.

  4. На вкладке Назначено системой для параметра Состояние установите значение Вкл.Within the System assigned tab, switch Status to On. Выберите команду Сохранить.Click Save.

    Управляемое удостоверение в Службе приложений

Примечание

Чтобы найти управляемое удостоверение для веб-приложения или приложения слота в портал Azure, в разделе корпоративные приложенияпросмотрите раздел Параметры пользователя .To find the managed identity for your web app or slot app in the Azure portal, under Enterprise applications, look in the User settings section. Обычно имя слота аналогично <app name>/slots/<slot name> .Usually, the slot name is similar to <app name>/slots/<slot name>.

Использование Azure CLIUsing the Azure CLI

Чтобы настроить управляемое удостоверение с помощью Azure CLI, используйте команду az webapp identity assign для имеющегося приложения.To set up a managed identity using the Azure CLI, you will need to use the az webapp identity assign command against an existing application. Примеры из этого раздела можно выполнять тремя способами:You have three options for running the examples in this section:

  • использовать Azure Cloud Shell с портала Azure;Use Azure Cloud Shell from the Azure portal.
  • использовать внедренный компонент Azure Cloud Shell с помощью кнопки "Попробовать", расположенной в правом верхнем углу каждого блока кода ниже.Use the embedded Azure Cloud Shell via the "Try It" button, located in the top-right corner of each code block below.
  • установить последнюю версию Azure CLI (2.0.31 или выше), если вы предпочитаете использовать локальную консоль CLI.Install the latest version of Azure CLI (2.0.31 or later) if you prefer to use a local CLI console.

Ниже описаны действия по созданию веб-приложения и присвоению удостоверения ему с помощью CLI:The following steps will walk you through creating a web app and assigning it an identity using the CLI:

  1. Если вы используете Azure CLI в локальной консоли, сначала выполните вход в Azure с помощью команды az login.If you're using the Azure CLI in a local console, first sign in to Azure using az login. Используйте учетную запись, связанную с подпиской Azure, с помощью которой нужно развернуть приложение:Use an account that's associated with the Azure subscription under which you would like to deploy the application:

    az login
    
  2. Создайте веб-приложение с помощью CLI.Create a web application using the CLI. Дополнительные примеры использования CLI со службой приложений см. в статье Примеры Azure CLI.For more examples of how to use the CLI with App Service, see App Service CLI samples:

    az group create --name myResourceGroup --location westus
    az appservice plan create --name myPlan --resource-group myResourceGroup --sku S1
    az webapp create --name myApp --resource-group myResourceGroup --plan myPlan
    
  3. Выполните команду identity assign, чтобы создать удостоверение для этого приложения.Run the identity assign command to create the identity for this application:

    az webapp identity assign --name myApp --resource-group myResourceGroup
    

Использование Azure PowerShellUsing Azure PowerShell

Примечание

Эта статья была изменена и теперь содержит сведения о новом модуле Az для Azure PowerShell.This article has been updated to use the new Azure PowerShell Az module. Вы по-прежнему можете использовать модуль AzureRM, исправления ошибок для которого будут продолжать выпускаться как минимум до декабря 2020 г.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Дополнительные сведения о совместимости модуля Az с AzureRM см. в статье Introducing the new Azure PowerShell Az module (Знакомство с новым модулем Az для Azure PowerShell).To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Инструкции по установке модуля Az см. в статье об установке Azure PowerShell.For Az module installation instructions, see Install Azure PowerShell.

Следующие шаги помогут вам создать приложение и назначить ему удостоверение с помощью Azure PowerShell.The following steps will walk you through creating an app and assigning it an identity using Azure PowerShell. Инструкции по созданию веб-приложения и приложения функции различаются.The instructions for creating a web app and a function app are different.

Использование Azure PowerShell для веб-приложенияUsing Azure PowerShell for a web app

  1. При необходимости установите Azure PowerShell с помощью инструкций из руководства по Azure PowerShell, а затем выполните команду Login-AzAccount, чтобы создать подключение к Azure.If needed, install the Azure PowerShell using the instructions found in the Azure PowerShell guide, and then run Login-AzAccount to create a connection with Azure.

  2. Создайте веб-приложение с помощью Azure PowerShell.Create a web application using Azure PowerShell. Дополнительные примеры применения Azure PowerShell со службой приложений см. в статье Примеры сценариев Azure PowerShell.For more examples of how to use Azure PowerShell with App Service, see App Service PowerShell samples:

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create an App Service plan in Free tier.
    New-AzAppServicePlan -Name $webappname -Location $location -ResourceGroupName $resourceGroupName -Tier Free
    
    # Create a web app.
    New-AzWebApp -Name $webappname -Location $location -AppServicePlan $webappname -ResourceGroupName $resourceGroupName
    
  3. Выполните команду Set-AzWebApp -AssignIdentity, чтобы создать удостоверение для этого приложения.Run the Set-AzWebApp -AssignIdentity command to create the identity for this application:

    Set-AzWebApp -AssignIdentity $true -Name $webappname -ResourceGroupName $resourceGroupName 
    

Использование Azure PowerShell для приложения-функцииUsing Azure PowerShell for a function app

  1. При необходимости установите Azure PowerShell с помощью инструкций из руководства по Azure PowerShell, а затем выполните команду Login-AzAccount, чтобы создать подключение к Azure.If needed, install the Azure PowerShell using the instructions found in the Azure PowerShell guide, and then run Login-AzAccount to create a connection with Azure.

  2. Создание приложения-функции с помощью Azure PowerShell.Create a function app using Azure PowerShell. Дополнительные примеры использования Azure PowerShell с функциями Azure см. в справочнике по AZ. functions:For more examples of how to use Azure PowerShell with Azure Functions, see the Az.Functions reference:

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create a storage account.
    New-AzStorageAccount -Name $storageAccountName -ResourceGroupName $resourceGroupName -SkuName $sku
    
    # Create a function app with a system-assigned identity.
    New-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -Location $location -StorageAccountName $storageAccountName -Runtime $runtime -IdentityType SystemAssigned
    

Можно также обновить существующее приложение функции Update-AzFunctionApp , используя вместо этого.You can also update an existing function app using Update-AzFunctionApp instead.

Использование шаблона Azure Resource ManagerUsing an Azure Resource Manager template

Шаблон Azure Resource Manager можно использовать для автоматизации развертывания ресурсов Azure.An Azure Resource Manager template can be used to automate deployment of your Azure resources. Дополнительные сведения о развертывании в службе приложений и Функциях см. в статьях Предсказуемые подготовка и развертывание микрослужб в Azure и Автоматизация развертывания ресурсов приложения-функции для службы "Функции Azure".To learn more about deploying to App Service and Functions, see Automating resource deployment in App Service and Automating resource deployment in Azure Functions.

Любой ресурс типа Microsoft.Web/sites можно создать с помощью удостоверения, добавив следующее свойство в определение ресурса:Any resource of type Microsoft.Web/sites can be created with an identity by including the following property in the resource definition:

"identity": {
    "type": "SystemAssigned"
}

Примечание

Приложение может иметь назначаемое системой и назначаемое пользователем удостоверения одновременно.An application can have both system-assigned and user-assigned identities at the same time. В этом случае для свойства type будет задано значение SystemAssigned,UserAssigned.In this case, the type property would be SystemAssigned,UserAssigned

При добавлении назначаемого системой удостоверения Azure создает удостоверение для приложения и управляет им.Adding the system-assigned type tells Azure to create and manage the identity for your application.

Например, веб-приложение может выглядеть следующим образом:For example, a web app might look like the following:

{
    "apiVersion": "2016-08-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

Созданный сайт будет иметь следующие дополнительные свойства:When the site is created, it has the following additional properties:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<TENANTID>",
    "principalId": "<PRINCIPALID>"
}

Свойство tenantId определяет, к какому клиенту Azure AD относится это удостоверение.The tenantId property identifies what Azure AD tenant the identity belongs to. principalId — это уникальный идентификатор для нового удостоверения приложения.The principalId is a unique identifier for the application's new identity. В Azure AD субъект-служба имеет то же имя, которое вы присвоили экземпляру Службы приложений или Функций Azure.Within Azure AD, the service principal has the same name that you gave to your App Service or Azure Functions instance.

Если необходимо сослаться на эти свойства на более позднем этапе шаблона, это можно сделать с помощью reference() функции шаблона с 'Full' флагом, как показано в следующем примере:If you need to reference these properties in a later stage in the template, you can do so via the reference() template function with the 'Full' flag, as in this example:

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

Добавление назначаемого пользователем удостоверенияAdd a user-assigned identity

Для создания приложения с назначаемым пользователем удостоверением необходимо создать удостоверение, а затем добавить его идентификатор ресурса в конфигурацию приложения.Creating an app with a user-assigned identity requires that you create the identity and then add its resource identifier to your app config.

Использование портала AzureUsing the Azure portal

Сначала необходимо создать ресурс назначаемого пользователем удостоверения.First, you'll need to create a user-assigned identity resource.

  1. Создайте ресурс назначаемого пользователем управляемого удостоверения в соответствии с этими инструкциями.Create a user-assigned managed identity resource according to these instructions.

  2. Создайте приложение на портале обычным образом.Create an app in the portal as you normally would. Перейдите к нему на портале.Navigate to it in the portal.

  3. Если используется приложение-функция, перейдите к функциям платформы.If using a function app, navigate to Platform features. Для других типов приложений прокрутите вниз до группы параметров в левой области навигации.For other app types, scroll down to the Settings group in the left navigation.

  4. Выберите Удостоверение.Select Identity.

  5. На вкладке Назначаемое пользователем щелкните Добавить.Within the User assigned tab, click Add.

  6. Найдите созданное ранее удостоверение и выберите его.Search for the identity you created earlier and select it. Нажмите кнопку Добавить.Click Add.

    Управляемое удостоверение в Службе приложений

Использование Azure PowerShellUsing Azure PowerShell

Примечание

Эта статья была изменена и теперь содержит сведения о новом модуле Az для Azure PowerShell.This article has been updated to use the new Azure PowerShell Az module. Вы по-прежнему можете использовать модуль AzureRM, исправления ошибок для которого будут продолжать выпускаться как минимум до декабря 2020 г.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Дополнительные сведения о совместимости модуля Az с AzureRM см. в статье Introducing the new Azure PowerShell Az module (Знакомство с новым модулем Az для Azure PowerShell).To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Инструкции по установке модуля Az см. в статье об установке Azure PowerShell.For Az module installation instructions, see Install Azure PowerShell.

Следующие шаги помогут вам создать приложение и назначить ему удостоверение с помощью Azure PowerShell.The following steps will walk you through creating an app and assigning it an identity using Azure PowerShell.

Примечание

Текущая версия Azure PowerShell командлеты для службы приложений Azure не поддерживает назначенные пользователю удостоверения.The current version of the Azure PowerShell commandlets for Azure App Service do not support user-assigned identities. Приведенные ниже инструкции предназначены для функций Azure.The below instructions are for Azure Functions.

  1. При необходимости установите Azure PowerShell с помощью инструкций из руководства по Azure PowerShell, а затем выполните команду Login-AzAccount, чтобы создать подключение к Azure.If needed, install the Azure PowerShell using the instructions found in the Azure PowerShell guide, and then run Login-AzAccount to create a connection with Azure.

  2. Создание приложения-функции с помощью Azure PowerShell.Create a function app using Azure PowerShell. Дополнительные примеры использования Azure PowerShell с функциями Azure см. в справочнике по AZ. functions.For more examples of how to use Azure PowerShell with Azure Functions, see the Az.Functions reference. В приведенном ниже скрипте также используется, New-AzUserAssignedIdentity который должен быть установлен отдельно при создании, перечислении или удалении назначенного пользователем управляемого удостоверения с помощью Azure PowerShell.The below script also makes use of New-AzUserAssignedIdentity which must be installed separately as per Create, list or delete a user-assigned managed identity using Azure PowerShell.

    # Create a resource group.
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    
    # Create a storage account.
    New-AzStorageAccount -Name $storageAccountName -ResourceGroupName $resourceGroupName -SkuName $sku
    
    # Create a user-assigned identity. This requires installation of the "Az.ManagedServiceIdentity" module.
    $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
    
    # Create a function app with a user-assigned identity.
    New-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -Location $location -StorageAccountName $storageAccountName -Runtime $runtime -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id
    

Можно также обновить существующее приложение функции Update-AzFunctionApp , используя вместо этого.You can also update an existing function app using Update-AzFunctionApp instead.

Использование шаблона Azure Resource ManagerUsing an Azure Resource Manager template

Шаблон Azure Resource Manager можно использовать для автоматизации развертывания ресурсов Azure.An Azure Resource Manager template can be used to automate deployment of your Azure resources. Дополнительные сведения о развертывании в службе приложений и Функциях см. в статьях Предсказуемые подготовка и развертывание микрослужб в Azure и Автоматизация развертывания ресурсов приложения-функции для службы "Функции Azure".To learn more about deploying to App Service and Functions, see Automating resource deployment in App Service and Automating resource deployment in Azure Functions.

Любой ресурс типа Microsoft.Web/sites можно создать с помощью удостоверения, добавив следующий блок в определение ресурса, заменив <RESOURCEID> идентификатором ресурса необходимого удостоверения:Any resource of type Microsoft.Web/sites can be created with an identity by including the following block in the resource definition, replacing <RESOURCEID> with the resource ID of the desired identity:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

Примечание

Приложение может иметь назначаемое системой и назначаемое пользователем удостоверения одновременно.An application can have both system-assigned and user-assigned identities at the same time. В этом случае для свойства type будет задано значение SystemAssigned,UserAssigned.In this case, the type property would be SystemAssigned,UserAssigned

При добавлении назначаемого пользователем типа служба Azure будет использовать назначаемое пользователем удостоверение, указанное для вашего приложения.Adding the user-assigned type tells Azure to use the user-assigned identity specified for your application.

Например, веб-приложение может выглядеть следующим образом:For example, a web app might look like the following:

{
    "apiVersion": "2016-08-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

Созданный сайт будет иметь следующие дополнительные свойства:When the site is created, it has the following additional properties:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {
            "principalId": "<PRINCIPALID>",
            "clientId": "<CLIENTID>"
        }
    }
}

principalId — это уникальный идентификатор удостоверения, используемый для администрирования Azure AD.The principalId is a unique identifier for the identity that's used for Azure AD administration. clientId — это уникальный идентификатор нового удостоверения приложения, который используется для того, чтобы указать, какое удостоверение следует использовать во время вызовов среды выполнения.The clientId is a unique identifier for the application's new identity that's used for specifying which identity to use during runtime calls.

Получение маркеров для ресурсов AzureObtain tokens for Azure resources

Приложение может использовать управляемое удостоверение для получения маркеров доступа к другим ресурсам, защищенным Azure AD (например, Azure Key Vault).An app can use its managed identity to get tokens to access other resources protected by Azure AD, such as Azure Key Vault. Эти маркеры представляют приложение, получающее доступ к ресурсам, а не конкретного пользователя приложения.These tokens represent the application accessing the resource, and not any specific user of the application.

Чтобы разрешить доступ из приложения, необходимо настроить целевой ресурс.You may need to configure the target resource to allow access from your application. Например, если вы запрашиваете маркер для получения доступа к Key Vault, необходимо добавить политику доступа, включающую в себя удостоверение приложения.For example, if you request a token to access Key Vault, you need to make sure you have added an access policy that includes your application's identity. В противном случае вызовы Key Vault будут отклонены, даже если они включают маркеры.Otherwise, your calls to Key Vault will be rejected, even if they include the token. Чтобы узнать больше о том, какие ресурсы поддерживают маркеры Azure Active Directory, см. сведения в разделе о службах Azure, поддерживающих аутентификацию Azure AD.To learn more about which resources support Azure Active Directory tokens, see Azure services that support Azure AD authentication.

Важно!

Внутренние службы для управляемых удостоверений организуют кэш для каждого URI-кода ресурса на период времени примерно в 8 часов.The back-end services for managed identities maintain a cache per resource URI for around 8 hours. Если вы обновляете политику доступа для определенного целевого ресурса и сразу получаете маркер для этого ресурса, вы можете постоянно получать кэшированный маркер с устаревшими разрешениями до тех пор, пока не истечет срок действия этого маркера.If you update the access policy of a particular target resource and immediately retrieve a token for that resource, you may continue to get a cached token with outdated permissions until that token expires. В настоящее время невозможно принудительно обновить маркер.There's currently no way to force a token refresh.

Существует простой протокол REST для получения маркера в службе приложений и Функциях Azure.There is a simple REST protocol for obtaining a token in App Service and Azure Functions. Его можно использовать для всех приложений и языков.This can be used for all applications and languages. Для .NET и Java пакет Azure SDK предоставляет абстракцию для работы с этим протоколом и упрощает процесс разработки в локальной среде.For .NET and Java, the Azure SDK provides an abstraction over this protocol and facilitates a local development experience.

Использование протокола RESTUsing the REST protocol

Примечание

В более старой версии этого протокола, поддерживающей версию API "2017-09-01", использовался заголовок secret вместо X-IDENTITY-HEADER и принималось только свойство clientid для назначаемого пользователем удостоверения.An older version of this protocol, using the "2017-09-01" API version, used the secret header instead of X-IDENTITY-HEADER and only accepted the clientid property for user-assigned. В ней также возвращался параметр expires_on в формате метки времени.It also returned the expires_on in a timestamp format. MSI_ENDPOINT можно использовать в качестве псевдонима для IDENTITY_ENDPOINT, а MSI_SECRET — в качестве псевдонима для IDENTITY_HEADER.MSI_ENDPOINT can be used as an alias for IDENTITY_ENDPOINT, and MSI_SECRET can be used as an alias for IDENTITY_HEADER. Эта версия протокола в настоящее время требуется для планов размещения потребления Linux.This version of the protocol is currently required for Linux Consumption hosting plans.

Приложение с управляемым удостоверением содержит две заданные переменные среды:An app with a managed identity has two environment variables defined:

  • IDENTITY_ENDPOINT — URL-адрес локальной службы токенов.IDENTITY_ENDPOINT - the URL to the local token service.
  • IDENTITY_HEADER — заголовок, который используется для противостояния атакам с подделкой серверных запросов (SSRF).IDENTITY_HEADER - a header used to help mitigate server-side request forgery (SSRF) attacks. Это значение меняется платформой.The value is rotated by the platform.

IDENTITY_ENDPOINT — это локальный URL-адрес, из которого приложение может запрашивать маркеры.The IDENTITY_ENDPOINT is a local URL from which your app can request tokens. Чтобы получить маркер для ресурса, отправьте запрос HTTP GET к этой конечной точке, задав следующие параметры:To get a token for a resource, make an HTTP GET request to this endpoint, including the following parameters:

Имя параметраParameter name ВIn ОписаниеDescription
ресурсresource ЗапросQuery Универсальный код ресурса (URI) Azure AD, для которого нужно получить маркер.The Azure AD resource URI of the resource for which a token should be obtained. Это может быть URI одной из служб Azure, которая поддерживает аутентификацию Azure AD, или любой другой URI ресурса.This could be one of the Azure services that support Azure AD authentication or any other resource URI.
api-versionapi-version ЗапросQuery Версия API маркеров, которая будет использоваться.The version of the token API to be used. Используйте "2019-08-01" или более позднюю версию (если не используется Linux, в настоящее время предлагается только "2017-09-01" — см. примечание выше).Please use "2019-08-01" or later (unless using Linux Consumption, which currently only offers "2017-09-01" - see note above).
X-IDENTITY-HEADERX-IDENTITY-HEADER ЗаголовокHeader Значение переменной среды IDENTITY_HEADER.The value of the IDENTITY_HEADER environment variable. Заголовок, который используется при устранении атак с подделкой серверных запросов (SSRF).This header is used to help mitigate server-side request forgery (SSRF) attacks.
client_idclient_id ЗапросQuery (Необязательно.) Идентификатор клиента назначаемого пользователем удостоверения, которое следует использовать.(Optional) The client ID of the user-assigned identity to be used. Не может использоваться для запроса, который включает в себя идентификатор principal_id, mi_res_idили object_id.Cannot be used on a request that includes principal_id, mi_res_id, or object_id. Если все параметры ИД (client_id, principal_id, object_id и mi_res_id) опущены, используется назначаемое системой удостоверение.If all ID parameters (client_id, principal_id, object_id, and mi_res_id) are omitted, the system-assigned identity is used.
principal_idprincipal_id ЗапросQuery (Необязательно.) Идентификатор субъекта назначаемого пользователем удостоверения, которое следует использовать.(Optional) The principal ID of the user-assigned identity to be used. object_id — псевдоним, который можно использовать вместо этого.object_id is an alias that may be used instead. Не может использоваться для запроса, который включает в себя идентификатор client_id, mi_res_id или object_id.Cannot be used on a request that includes client_id, mi_res_id, or object_id. Если все параметры ИД (client_id, principal_id, object_id и mi_res_id) опущены, используется назначаемое системой удостоверение.If all ID parameters (client_id, principal_id, object_id, and mi_res_id) are omitted, the system-assigned identity is used.
mi_res_idmi_res_id ЗапросQuery (Необязательно.) Идентификатор ресурса Azure для назначаемого пользователем удостоверения, которое следует использовать.(Optional) The Azure resource ID of the user-assigned identity to be used. Не может использоваться для запроса, который включает в себя идентификатор principal_id, client_idили object_id.Cannot be used on a request that includes principal_id, client_id, or object_id. Если все параметры ИД (client_id, principal_id, object_id и mi_res_id) опущены, используется назначаемое системой удостоверение.If all ID parameters (client_id, principal_id, object_id, and mi_res_id) are omitted, the system-assigned identity is used.

Важно!

Если вы хотите получить маркеры для назначаемых пользователем удостоверений, необходимо указать одно из дополнительных свойств.If you are attempting to obtain tokens for user-assigned identities, you must include one of the optional properties. В противном случае служба токенов попытается получить маркер для назначаемого системой удостоверения, которое может и отсутствовать.Otherwise the token service will attempt to obtain a token for a system-assigned identity, which may or may not exist.

Успешный ответ 200 — OK включает текст JSON со следующими свойствами:A successful 200 OK response includes a JSON body with the following properties:

Имя свойстваProperty name ОписаниеDescription
access_tokenaccess_token Запрашиваемый маркер доступа.The requested access token. Вызывающая веб-служба может использовать этот маркер для проверки подлинности принимающей веб-службы.The calling web service can use this token to authenticate to the receiving web service.
client_idclient_id Идентификатор клиента используемого удостоверения.The client ID of the identity that was used.
expires_onexpires_on Период времени после истечения срока действия маркера доступа.The timespan when the access token expires. Дата представляется как количество секунд с 1970-01-01T0:0:0Z в формате UTC (соответствует утверждению exp маркера).The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's exp claim).
not_beforenot_before Период времени, когда маркер доступа вступает в силу и может быть принят.The timespan when the access token takes effect, and can be accepted. Дата представляется как количество секунд с 1970-01-01T0:0:0Z в формате UTC (соответствует утверждению nbf маркера).The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's nbf claim).
ресурсresource Ресурс, для которого был запрошен маркер доступа, соответствует параметру строки запроса resource.The resource the access token was requested for, which matches the resource query string parameter of the request.
token_typetoken_type Указывает значение типа маркера.Indicates the token type value. Единственный тип, который поддерживается Azure AD, — это FBearer.The only type that Azure AD supports is FBearer. Дополнительные сведения о маркерах носителей см. в спецификации OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750) (OAuth2.0 Authorization Framework: использование маркера носителя (RFC 6750)).For more information about bearer tokens, see The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750).

Этот ответ совпадает с ответом для запроса маркера взаимного доступа между службами Azure AD.This response is the same as the response for the Azure AD service-to-service access token request.

Примеры протокола RESTREST protocol examples

Пример запроса может выглядеть следующим образом:An example request might look like the following:

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: localhost:4141
X-IDENTITY-HEADER: 853b9a84-5bfa-4b22-a3f3-0b9a43d9ad8a

Пример ответа может выглядеть следующим образом:And a sample response might look like the following:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "5E29463D-71DA-4FE0-8E69-999B57DB23B0"
}

Примеры кодаCode examples

Совет

Для языков .NET можно также использовать пакет Microsoft.Azure.Services.AppAuthentication, вместо того чтобы создавать этот запрос самостоятельно.For .NET languages, you can also use Microsoft.Azure.Services.AppAuthentication instead of crafting this request yourself.

private readonly HttpClient _client;
// ...
public async Task<HttpResponseMessage> GetToken(string resource)  {
    var request = new HttpRequestMessage(HttpMethod.Get, 
        String.Format("{0}/?resource={1}&api-version=2019-08-01", Environment.GetEnvironmentVariable("IDENTITY_ENDPOINT"), resource));
    request.Headers.Add("X-IDENTITY-HEADER", Environment.GetEnvironmentVariable("IDENTITY_HEADER"));
    return await _client.SendAsync(request);
}

Использование библиотеки Microsoft.Azure.Services.AppAuthentication для .NETUsing the Microsoft.Azure.Services.AppAuthentication library for .NET

Самый простой способ для приложений и функций .NET работать с управляемыми удостоверениями заключается в использовании пакета Microsoft.Azure.Services.AppAuthentication.For .NET applications and functions, the simplest way to work with a managed identity is through the Microsoft.Azure.Services.AppAuthentication package. Эта библиотека также позволяет локально тестировать код на компьютере разработки с использованием учетной записи пользователя из Visual Studio, Azure CLI или встроенной проверки подлинности Active Directory.This library will also allow you to test your code locally on your development machine, using your user account from Visual Studio, the Azure CLI, or Active Directory Integrated Authentication. При размещении в облаке по умолчанию будет использоваться назначенное системой удостоверение, но это поведение можно изменить с помощью переменной среды строки подключения, которая ссылается на идентификатор клиента для назначенного пользователю удостоверения.When hosted in the cloud, it will default to using a system-assigned identity, but you can customize this behavior using a connection string environment variable which references the client ID of a user-assigned identity. Дополнительные сведения о вариантах разработки с этой библиотекой см. в [справочнике по Microsoft. Azure. Services. AppAuthentication].For more on development options with this library, see the Microsoft.Azure.Services.AppAuthentication reference. В этом разделе показано, как начать работу с библиотекой в коде.This section shows you how to get started with the library in your code.

  1. Добавьте ссылки на пакет Microsoft.Azure.Services.AppAuthentication и другие пакеты NuGet в приложение.Add references to the Microsoft.Azure.Services.AppAuthentication and any other necessary NuGet packages to your application. В примерах ниже также используется Microsoft.Azure.KeyVault.The below example also uses Microsoft.Azure.KeyVault.

  2. Добавьте приведенный ниже код в приложение, указав необходимый целевой ресурс.Add the following code to your application, modifying to target the correct resource. В этом примере показано два способа работы с Azure Key Vault:This example shows two ways to work with Azure Key Vault:

    using Microsoft.Azure.Services.AppAuthentication;
    using Microsoft.Azure.KeyVault;
    // ...
    var azureServiceTokenProvider = new AzureServiceTokenProvider();
    string accessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://vault.azure.net");
    // OR
    var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));
    

Если вы хотите использовать управляемое пользователем удостоверение, можно задать AzureServicesAuthConnectionString для параметра приложения значение RunAs=App;AppId=<clientId-guid> .If you want to use a user-assigned managed identity, you can set the AzureServicesAuthConnectionString application setting to RunAs=App;AppId=<clientId-guid>. Замените <clientId-guid> идентификатором клиента идентификатора, который вы хотите использовать.Replace <clientId-guid> with the client ID of the identity you want to use. Можно определить несколько таких строк подключения с помощью пользовательских параметров приложения и передать их значения в конструктор AzureServiceTokenProvider.You can define multiple such connection strings by using custom application settings and passing their values into the AzureServiceTokenProvider constructor.

    var identityConnectionString1 = Environment.GetEnvironmentVariable("UA1_ConnectionString");
    var azureServiceTokenProvider1 = new AzureServiceTokenProvider(identityConnectionString1);
    
    var identityConnectionString2 = Environment.GetEnvironmentVariable("UA2_ConnectionString");
    var azureServiceTokenProvider2 = new AzureServiceTokenProvider(identityConnectionString2);

Дополнительные сведения о настройке AzureServiceTokenProvider и предоставляемых ею операциях см. в [справочнике по Microsoft. Azure. Services. AppAuthentication] и службе приложений и KEYVAULT с примером MSI .NET.To learn more about configuring AzureServiceTokenProvider and the operations it exposes, see the Microsoft.Azure.Services.AppAuthentication reference and the App Service and KeyVault with MSI .NET sample.

Использование пакета Azure SDK для JavaUsing the Azure SDK for Java

Для приложений и функций Java при работе с управляемым удостоверением проще всего использовать пакет Azure SDK для Java.For Java applications and functions, the simplest way to work with a managed identity is through the Azure SDK for Java. В этом разделе показано, как начать работу с библиотекой в коде.This section shows you how to get started with the library in your code.

  1. Добавьте ссылку на библиотеку Azure SDK.Add a reference to the Azure SDK library. В проектах Maven можно добавить в раздел dependencies файла POM вашего проекта следующий фрагмент кода:For Maven projects, you might add this snippet to the dependencies section of the project's POM file:

    <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>azure</artifactId>
        <version>1.23.0</version>
    </dependency>
    
  2. Для проверки подлинности используйте объект AppServiceMSICredentials.Use the AppServiceMSICredentials object for authentication. Следующий пример демонстрирует, как можно использовать этот механизм для работы с Azure Key Vault:This example shows how this mechanism may be used for working with Azure Key Vault:

    import com.microsoft.azure.AzureEnvironment;
    import com.microsoft.azure.management.Azure;
    import com.microsoft.azure.management.keyvault.Vault
    //...
    Azure azure = Azure.authenticate(new AppServiceMSICredentials(AzureEnvironment.AZURE))
            .withSubscription(subscriptionId);
    Vault myKeyVault = azure.vaults().getByResourceGroup(resourceGroup, keyvaultName);
    
    

Удаление удостоверенияRemove an identity

Чтобы удалить назначаемое системой удостоверение, нужно отключить возможность с помощью портала, PowerShell или интерфейса командной строки точно так же, как и при его создании.A system-assigned identity can be removed by disabling the feature using the portal, PowerShell, or CLI in the same way that it was created. Назначаемые пользователем удостоверения можно удалить по отдельности.User-assigned identities can be removed individually. Чтобы удалить все удостоверения, задайте для параметра Тип удостоверения значение "нет".To remove all identities, set the identity type to "None".

Если назначаемое системой удостоверение удаляется таким способом, то оно также удаляется и из Azure AD.Removing a system-assigned identity in this way will also delete it from Azure AD. Назначаемые системой удостоверения также автоматически удаляются из Azure AD, когда удаляется ресурс приложения.System-assigned identities are also automatically removed from Azure AD when the app resource is deleted.

Чтобы удалить все удостоверения в шаблоне ARM, выполните следующие действия.To remove all identities in an ARM template:

"identity": {
    "type": "None"
}

Чтобы удалить все удостоверения в Azure PowerShell (только для функций Azure):To remove all identities in Azure PowerShell (Azure Functions only):

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType None

Примечание

Также вы можете установить параметр приложения WEBSITE_DISABLE_MSI, который отключает локальную службу маркеров.There is also an application setting that can be set, WEBSITE_DISABLE_MSI, which just disables the local token service. Но при этом само удостоверение сохранится, а управляемое удостоверение будет отображаться как "включенное".However, it leaves the identity in place, and tooling will still show the managed identity as "on" or "enabled." По этой причине мы рекомендуем не использовать такой параметр.As a result, use of this setting is not recommended.

Дальнейшие действияNext steps