Клиентская библиотека проверки подлинности приложений для .NET — версия 1.6.0

Статья
04/03/2023

Примечание

Служба Microsoft.Azure.Services.AppAuthentication прекращена и больше не поддерживается. Он заменяется клиентской библиотекой удостоверений Azure , доступной для .NET, Java, TypeScript и Python. Сведения о переносе в Azure Identity см. в статье Руководство по переносу AppAuthentication в Azure.Identity.

Для проверки подлинности в службах Azure с помощью субъекта-службы вам потребуются учетные данные Azure Active Directory (Azure AD), общий секрет или сертификат.

Управление такими учетными данными может быть затруднено. Заманчиво объединить учетные данные в приложение, включив их в исходные файлы или файлы конфигурации. Пакет Microsoft.Azure.Services.AppAuthentication для библиотеки .NET упрощает эту проблему. Он использует учетные данные разработчика для выполнения проверки подлинности во время локальной разработки. Если решение позже развертывается в Azure, библиотека автоматически переключается на использование учетных данных приложения. Использование учетных данных разработчика во время локальной разработки является более безопасным, так как вам не нужно создавать учетные данные Azure AD или совместно использовать учетные данные между разработчиками.

Библиотека Microsoft.Azure.Services.AppAuthentication автоматически управляет проверкой подлинности, что, в свою очередь, позволяет сосредоточиться на решении, а не на учетных данных. Он поддерживает локальную разработку с помощью Microsoft Visual Studio, Azure CLI или встроенной проверки подлинности Azure AD. При развертывании в ресурс Azure, поддерживающий управляемое удостоверение, библиотека автоматически использует управляемые удостоверения для ресурсов Azure. Изменение кода или конфигурации не требуется. Библиотека также поддерживает прямое использование учетных данных Azure AD клиента, если управляемое удостоверение недоступно или когда контекст безопасности разработчика не может быть определен во время локальной разработки.

Исходный код | Пакет (nuget) | Документация по Azure Active Directory

Предварительные требования

Visual Studio 2019 или Visual Studio 2017 версии 15.5.
Расширение проверки подлинности приложений для Visual Studio, доступное в виде отдельного расширения для Visual Studio 2017 с обновлением 5 и в комплекте с продуктом в обновлении 6 и более поздних версий. С обновлением 6 или более поздней версии можно проверить установку расширения проверки подлинности приложений, выбрав Средства разработки Azure в установщике Visual Studio.

Использование библиотеки

Для приложений .NET для работы с управляемым удостоверением проще всего использовать пакет Microsoft.Azure.Services.AppAuthentication. Узнайте, как начать работу.

Выберите Сервис>Диспетчер> пакетовNuGet Управление пакетами NuGet для решения, чтобы добавить ссылки на пакеты NuGet Microsoft.Azure.Services.AppAuthentication и Microsoft.Azure.KeyVault в проект.

Используйте AzureServiceTokenProvider, чтобы упростить запрос маркеров доступа для клиентов Azure, как показано в следующих примерах:

using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;
using System.Data.SqlClient

// Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
var azureServiceTokenProvider = new AzureServiceTokenProvider();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

// Request an access token for SqlConnection
sqlConnection = new SqlConnection(YourConnectionString)) 
{ 
    sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
    sqlConnection.Open(); 
}

Потокобезопасный AzureServiceTokenProvider класс кэширует маркер в памяти и извлекает его из Azure AD незадолго до истечения срока действия. Это означает, что вам не нужно проверка срок действия маркера перед вызовом GetAccessTokenAsync метода .

Для метода GetAccessTokenAsync требуется наличие идентификатора ресурса. Дополнительные сведения о службах Microsoft Azure см. в статье Что такое управляемые удостоверения для ресурсов Azure.

Проверка подлинности среды локальной разработки

Для локальной разработки существует два основных сценария проверки подлинности: проверка подлинности в службах Azure и проверка подлинности в пользовательских службах.

Проверка подлинности в службах Azure

Локальные компьютеры не поддерживают управляемые удостоверения для ресурсов Azure. В результате библиотека Microsoft.Azure.Services.AppAuthentication использует учетные данные разработчика для запуска в среде локальной разработки. При развертывании решения в Azure библиотека использует управляемое удостоверение для переключения на поток предоставления учетных данных клиента OAuth 2.0. Такой подход означает, что вы можете тестировать один и тот же код локально и удаленно, не беспокоясь.

Для локальной разработки AzureServiceTokenProvider получает токены с помощью Visual Studio, интерфейса командной строки Azure (CLI) или встроенной проверки подлинности Azure AD. Каждый вариант применяется последовательно, и библиотека использует первый вариант, который завершается успешно. Если ни один вариант не работает, выводится исключение AzureServiceTokenProviderException с подробными сведениями.

Проверка подлинности с помощью Visual Studio

Чтобы пройти проверку подлинности с помощью Visual Studio, выполните следующие действия.

Войдите в Visual Studio и используйте параметры сервис,> чтобы открыть параметры.
Выберите Проверка подлинности службы Azure, выберите учетную запись для локальной разработки и нажмите кнопку ОК.

Если при работе с Visual Studio возникают проблемы, например ошибки, связанные с файлом поставщика маркеров, внимательно изучите описанные выше действия.

Возможно, потребуется повторно пройти проверку подлинности маркера разработчика. Для этого выберите Сервис>Параметры, а затем — Проверка подлинности службы Azure. Найдите ссылку Повторная проверка подлинности в выбранной учетной записи. Щелкните ее, чтобы выполнить проверку подлинности.

Проверка подлинности с помощью Azure CLI

Чтобы использовать Azure CLI для локальной разработки, убедитесь, что у вас установлена версия Azure CLI версии 2.0.12 или более поздней.

Чтобы использовать Azure CLI, выполните следующие действия.

Найдите Azure CLI на панели задач Windows, чтобы открыть командную строку Microsoft Azure.
Войдите в портал Azure: az login, чтобы войти в Azure.
Проверьте доступ, введя az account get-access-token --resource https://vault.azure.net. Если появляется сообщение об ошибке, проверка, что правильная версия Azure CLI установлена правильно.

Если Azure CLI не установлен в каталог по умолчанию, вы можете получить сообщение об ошибках, которые AzureServiceTokenProvider не могут найти путь к Azure CLI. Используйте переменную среды AzureCLIPath , чтобы определить папку установки Azure CLI. При необходимости AzureServiceTokenProvider добавляет каталог, указанный в переменной среды AzureCLIPath, в переменную среды Path.
Если вы вошли в Azure CLI с помощью нескольких учетных записей или ваша учетная запись имеет доступ к нескольким подпискам, необходимо указать подписку для использования. Введите команду az account set --subscription .

Эта команда создает выходные данные только при сбое. Чтобы проверить текущие параметры учетной записи, введите команду az account list.

Проверка подлинности с помощью Azure AD проверки подлинности

Чтобы использовать проверку подлинности Azure AD, убедитесь, что:

Ваш локальная служба Active Directory синхронизируется с Azure AD. Дополнительные сведения см. в статье Что такое гибридное удостоверение с помощью Azure Active Directory?.
Код выполняется на компьютере, присоединенном к домену.

Проверка подлинности в пользовательских службах

Когда служба вызывает службы Azure, можно выполнить предыдущие действия, так как службы Azure предоставляют доступ пользователям и приложениям.

При создании службы, которая вызывает пользовательскую службу, выполните проверку подлинности среды локальной разработки с помощью учетных данных клиента Azure AD. Существует два варианта.

Войдите в Azure, используя субъект-службу:
1. Создание субъекта-службы. Дополнительные сведения см. в статье Создание субъекта-службы Azure с помощью Azure CLI.
2. Используйте Azure CLI для входа с помощью следующей команды:
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  Так как субъект-служба может не иметь доступа к подписке, используйте аргумент --allow-no-subscriptions.
Укажите сведения о субъекте-службе с помощью переменных среды. Дополнительные сведения см. в статье Запуск приложения с помощью субъекта-службы.

После входа в Azure использует субъект-службу для AzureServiceTokenProvider получения маркера для локальной разработки.

Этот подход применяется только к локальной разработке. При развертывании решения в Azure библиотека переключается на выполнение проверки подлинности с использованием управляемого удостоверения.

Запуск приложения с помощью управляемого удостоверения или удостоверения, назначаемого пользователем

При выполнении кода в Службе приложений Azure или на виртуальной машине Azure с включенным управляемым удостоверением библиотека автоматически использует это удостоверение. Изменения кода не требуются, но управляемое удостоверение должно иметь разрешения для ресурсов, к которым оно будет пытаться получить доступ. Например, политики доступа требуются управляемому удостоверению для доступа к любым секретам в хранилище ключей.

Кроме того, вы можете пройти проверку подлинности с помощью удостоверения, назначаемого пользователем. Дополнительные сведения об удостоверениях, назначаемых пользователем, см. в статье Об управляемых удостоверениях для ресурсов Azure. Для проверки подлинности с помощью назначаемого пользователем удостоверения необходимо указать идентификатор клиента удостоверения, назначаемого пользователем, в строке подключения. Строка подключения указывается в разделе Поддержка строки подключения.

Запуск приложения с помощью субъекта-службы

Возможно, может понадобиться создать учетные данные клиента Azure AD для проверки подлинности. Такая ситуация может возникнуть в следующих примерах:

Ваш код выполняется в среде локальной разработки, но не использует удостоверение разработчика. Service Fabric, например, использует учетную запись NetworkService для локальной разработки.
Ваш код выполняется в среде локальной разработки и выполняется проверка подлинности в пользовательской службе, поэтому вы не можете использовать удостоверение разработчика.
Ваш код выполняется в вычислительном ресурсе Azure, который еще не поддерживает управляемые удостоверения для ресурсов Azure, таких как пакетная служба Azure.

Существует три основных метода использования субъекта-службы для запуска приложения. Чтобы использовать любой из них, необходимо сначала создать субъект-службу. Дополнительные сведения см. в статье Создание субъекта-службы Azure с помощью Azure CLI.

Использование сертификата в локальном хранилище ключей для входа в Azure AD

Создайте сертификат субъекта-службы с помощью команды Azure CLI az ad sp create-for-rbac .
```
az ad sp create-for-rbac --create-cert
```
Эта команда создает PEM-файл (закрытый ключ), хранящийся в домашнем каталоге. Преобразуйте PEM-файл в PFX-сертификат с помощью команды :
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
Присвойте переменной среды с именем AzureServicesAuthConnectionString следующее значение:
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
Замените {AppId}, {TenantId} и {Thumbprint} идентификатором приложения, идентификатором клиента и отпечатком, созданными на шаге 1. Замените {CertificateStore}на LocalMachine' или CurrentUser в зависимости от плана развертывания.
Запустите приложение.

Использование общих учетных данных секрета для входа в Azure AD

Создайте сертификат субъекта-службы с паролем с помощью команды Azure CLI az ad sp create-for-rbac с параметром --sdk-auth.
```
az ad sp create-for-rbac --sdk-auth
```
Присвойте переменной среды с именем AzureServicesAuthConnectionString следующее значение:
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
Замените {AppId}, {TenantId} и {ClientSecret} идентификатором приложения, идентификатором клиента и секретом клиента, созданными на шаге 1.
Запустите приложение.

Если установка выполнена правильно, дальнейшие изменения в коде не требуются. AzureServiceTokenProvider использует переменную среды и сертификат для выполнения проверки подлинности в Azure AD.

Использование сертификата в Key Vault для входа в Azure AD

Этот параметр позволяет хранить сертификат клиента субъекта-службы в Key Vault и использовать его для проверки подлинности субъекта-службы. Этот параметр можно использовать в следующих сценариях:

Локальная проверка подлинности, в которой требуется выполнить проверку подлинности с помощью явного субъекта-службы и безопасно хранить учетные данные субъекта-службы в хранилище ключей. Учетная запись разработчика должна иметь доступ к хранилищу ключей.
Проверка подлинности из Azure, где требуется использовать явные учетные данные и безопасно хранить учетные данные субъекта-службы в хранилище ключей. Этот параметр можно использовать для сценария с несколькими клиентами. Управляемое удостоверение должно иметь доступ к хранилищу ключей.

Управляемое удостоверение или удостоверение разработчика должны иметь разрешение на получение сертификата клиента из Key Vault. Библиотека AppAuthentication использует полученный сертификат в качестве учетных данных клиента субъекта-службы.

Чтобы использовать сертификат клиента для проверки подлинности субъекта-службы, выполните следующие действия.

Создайте сертификат субъекта-службы и автоматически сохраните его в Key Vault. Используйте команду Azure CLI az ad sp create-for-rbac --keyvaultname <> --cert <certificatename> --create-cert --skip-assignment:
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
Идентификатор сертификата будет URL-адресом в формате https://<keyvaultname>.vault.azure.net/secrets/<certificatename>
Замените {KeyVaultCertificateSecretIdentifier} в этой строке подключения идентификатором сертификата:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
```
Например, если хранилище ключей называется myKeyVault и вы создали сертификат с именем myCert, идентификатор сертификата будет следующим:
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
```

Поддержка строки подключения

По умолчанию AzureServiceTokenProvider пытается использовать следующие методы проверки подлинности для получения маркера:

Управляемое удостоверение для ресурсов Azure
Проверка подлинности Visual Studio
Проверка подлинности Azure CLI
Встроенная проверка подлинности Windows

Для управления процессом используйте строку подключения, переданную в конструктор AzureServiceTokenProvider или указанную в переменной среды AzureServicesAuthConnectionString. Поддерживаются следующие варианты.

Параметр строки подключения	Сценарий	Комментарии
`RunAs=Developer;DeveloperTool=AzureCli`	Локальная разработка	`AzureServiceTokenProvider` использует AzureCli для получения маркера.
`RunAs=Developer;DeveloperTool=VisualStudio`	Локальная разработка	`AzureServiceTokenProvider` использует Visual Studio для получения маркера.
`RunAs=CurrentUser`	Локальная разработка	Не поддерживается в .NET Core. `AzureServiceTokenProvider`использует Azure AD встроенную проверку подлинности для получения маркера.
`RunAs=App`	Управляемые удостоверения для ресурсов Azure	`AzureServiceTokenProvider` использует управляемое удостоверение для получения маркера.
`RunAs=App;AppId={ClientId of user-assigned identity}`	Назначаемое пользователем удостоверение для ресурсов Azure	`AzureServiceTokenProvider` использует назначаемое пользователем удостоверение для получения маркера.
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	Проверка подлинности пользовательских служб	`KeyVaultCertificateSecretIdentifier` — это секретный идентификатор сертификата.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	Субъект-служба	`AzureServiceTokenProvider` использует сертификат для получения токена из Azure AD.
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	Субъект-служба	`AzureServiceTokenProvider` использует сертификат для получения токена из Azure AD.
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	Субъект-служба	`AzureServiceTokenProvider` использует секрет для получения токена из Azure AD.

Примеры

Чтобы увидеть библиотеку Microsoft.Azure.Services.AppAuthentication в действии, ознакомьтесь со следующими примерами кода.

Устранение неполадок с AppAuthentication

Распространенные проблемы во время локальной разработки

Azure CLI не установлен, вы не вошли в систему или у вас нет последней версии

Выполните команду az account get-access-token , чтобы узнать, отображает ли Azure CLI маркер. Если указано, что такая программа не найдена, установите последнюю версию Azure CLI. Возможно, вам будет предложено войти в систему.

AzureServiceTokenProvider не удается найти путь для Azure CLI

AzureServiceTokenProvider ищет Azure CLI в расположениях установки по умолчанию. Если не удается найти Azure CLI, задайте переменную среды AzureCLIPath в папку установки Azure CLI. AzureServiceTokenProvider добавит переменную среды в переменную среды Path.

Вы вошли в Azure CLI с помощью нескольких учетных записей, у одной и той же учетной записи есть доступ к подпискам в нескольких клиентах, или при попытке выполнить вызовы во время локальной разработки возникает ошибка "Отказано в доступе".

С помощью Azure CLI задайте подписку по умолчанию, в которой есть учетная запись, которую вы хотите использовать. Подписка должна находиться в том же клиенте, что и ресурс, к которому вы хотите получить доступ: az account set --subscription [subscription-id]. Если выходные данные не отображаются, это выполнено успешно. Убедитесь, что правильная учетная запись теперь используется по умолчанию, используя команду az account list.

Распространенные проблемы в разных средах

Несанкционированный доступ, доступ запрещен, запрещено или подобная ошибка

У используемого субъекта нет доступа к ресурсу, к которому он пытается получить доступ. Предоставьте учетной записи пользователя или MSI-файлу Служба приложений доступ к ресурсу. Выбор зависит от того, выполняете ли вы пример на локальном компьютере или развернут в Azure на Служба приложений. Некоторые ресурсы, такие как хранилища ключей, также имеют собственные политики доступа , которые вы используете, предоставляя доступ субъектам, таким как пользователи, приложения и группы.

Распространенные проблемы при развертывании в Служба приложений Azure

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

Проверьте переменные среды MSI_ENDPOINT и MSI_SECRET существуют с помощью консоли отладки Kudu. Если эти переменные среды не существуют, управляемое удостоверение не включено на Служба приложений.

Распространенные проблемы при локальном развертывании с помощью IIS

Не удается получить маркеры при отладке приложения в IIS

По умолчанию AppAuth выполняется в другом контексте пользователя в IIS. Поэтому у него нет доступа к использованию удостоверения разработчика для получения маркеров доступа. Вы можете настроить iis для запуска с контекстом пользователя, выполнив следующие два шага:

Настройте пул приложений для запуска веб-приложения от имени текущей учетной записи пользователя. Дополнительные сведения см. здесь.
Настройте для setProfileEnvironment значение True. Дополнительные сведения см. здесь.
- Перейдите к %windir%\System32\inetsrv\config\applicationHost.config
- Выполните поиск по запросу setProfileEnvironment. Если задано значение False, измените его на True. Если он отсутствует, добавьте его в качестве атрибута в элемент processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) и задайте для него значение True.
Дополнительные сведения см. в статье Использование управляемых удостоверений в Службе приложений и Функциях Azure.
Что такое проверка подлинности?