Проверка подлинности в ресурсах Azure из приложений JavaScript, размещенных локально

Приложения, размещенные за пределами Azure, в локальных инфраструктурах или в сторонних центрах обработки данных, должны использовать служебный принципал приложения через Microsoft Entra ID для аутентификации в службах Azure. В следующих разделах вы узнаете:

• Регистрация приложения в Microsoft Entra для создания субъекта-службы
• Назначение ролей для разрешений области действия.
• Аутентификация с помощью учетной записи службы из кода приложения

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

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

Регистрация приложения в Azure

Объекты службы приложений создаются посредством регистрации приложений в Azure с использованием портала Azure или интерфейса командной строки Azure (Azure CLI).

Портал Azure

1. На портале Azure перейдите на страницу регистрации приложений с помощью панели поиска.

2. На странице Регистрация приложений нажмите кнопку +Создать регистрацию.

3. На странице Зарегистрировать приложение:

   • В поле Имя введите описательное значение, включающее имя приложения и целевую среду.
   • Для поддерживаемых типов учетных записейвыберите учетные записи только в этом каталоге организации (только клиент Майкрософт — один клиент)или любой вариант, который лучше всего соответствует вашим требованиям.

4. Выберите Регистрация, чтобы зарегистрировать приложение и создать служебный принципал.

   

5. На странице регистрации приложений скопируйте идентификатор приложения (клиента) и идентификатор каталога (клиента) и вставьте их во временное расположение для последующего использования в конфигурациях кода приложения.

6. Выберите Добавить сертификат или секрет, чтобы установить учетные данные для приложения.

7. На странице "Сертификаты и секреты" выберите "+ Новый секрет клиента".

8. На панели, открывающейся для добавления секрета клиента, выполните следующие действия:

   • В поле "Описание" введите значение Current.
   • Для значения "Срок действия" оставьте рекомендуемое значение 180 daysпо умолчанию.
   • Нажмите кнопку "Добавить ", чтобы добавить секрет.

9. На странице сертификатов & секретов скопируйте свойство значения секрета клиента для использования в следующем шаге.

   Замечание

   Значение секрета клиента отображается только один раз после создания регистрации приложения. Вы можете добавить дополнительные секреты клиента, не отменив этот секрет клиента, но невозможно снова отобразить это значение.

Azure CLI

Команды Azure CLI могут выполняться в Azure Cloud Shell или на рабочей станции с установленным интерфейсом Azure CLI.

1. Используйте команду az ad sp create-for-rbac, чтобы создать новую регистрацию приложения и сервисный принципал для приложения.

   az ad sp create-for-rbac --name <service-principal-name>
   

   Выходные данные этой команды похожи на следующий код JSON:

   {
     "appId": "00000000-0000-0000-0000-000000000000",
     "displayName": "<service-principal-name>",
     "password": "abcdefghijklmnopqrstuvwxyz",
     "tenant": "11111111-1111-1111-1111-111111111111"
   }
   

2. Скопируйте эти выходные данные в временный файл в текстовом редакторе, так как эти значения потребуются на следующем шаге.

   Замечание

   Значение секрета клиента отображается только один раз после создания регистрации приложения. Вы можете добавить дополнительные секреты клиента, не отменив этот секрет клиента, но невозможно снова отобразить это значение.

Назначение ролей для служебного принципала приложения

Затем определите, какие роли (разрешения) приложению требуются для каких ресурсов, и назначьте эти роли созданному субъекту-службе. Роли можно назначать на уровне ресурса, группы ресурсов или подписки. В этом примере показано, как назначать роли в области группы ресурсов, так как большинство приложений группируют все свои ресурсы Azure в одну группу ресурсов.

Портал Azure

1. На портале Azure перейдите на страницу обзора группы ресурсов, содержащей приложение.

2. Выберите управление доступом (IAM) в левой панели навигации.

3. На странице управления доступом (IAM) выберите +Добавить , а затем выберите "Добавить назначение ролей " в раскрывающемся меню. Страница "Добавление назначения ролей " предоставляет несколько вкладок для настройки и назначения ролей.

4. На вкладке "Роль" используйте поле поиска, чтобы найти роль, которую вы хотите назначить. Выберите роль и нажмите кнопку "Далее".

5. На вкладке "Члены" :

   • Чтобы назначить доступ к значению , выберите "Пользователь", "Группа" или "Субъект-служба ".
   • Для значения "Члены" нажмите кнопку "Выбрать участников ", чтобы открыть панель всплывающего меню "Выбор участников ".
   • Найдите служебный принципал, созданный ранее, и выберите его из отфильтрованных результатов. Выберите команду "Выбрать ", чтобы выбрать группу и закрыть панель всплывающего меню.
   • Выберите Обзор + Назначение внизу вкладки Члены.

   

6. На вкладке "Обзор и назначение" выберите "Обзор и назначение" в нижней части страницы.

Azure CLI

1. Используйте команду az role definition list, чтобы получить имена ролей, которым может быть назначен служебный принципал.

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

2. Используйте команду az role assignment create, чтобы назначить роль основному объекту службы приложения.

   az role assignment create \
       --assignee "<app-Id>" \
       --role "<role-name>" \
       --resource-group "<resource-group-name>"
   

   Информация о назначении разрешений на уровне ресурса или подписки с помощью Azure CLI см. в статье Назначение ролей Azure с помощью Azure CLI.

Установите переменные среды приложения

Во время выполнения некоторые учетные данные из библиотеки удостоверений Azure, такие как DefaultAzureCredential, EnvironmentCredentialи ClientSecretCredential, ищут сведения о служебном принципале по соглашению в переменных среды. Существует несколько способов настройки переменных среды при работе с JavaScript в зависимости от инструментов и среды.

Независимо от выбранного подхода настройте следующие переменные среды для субъекта-службы:

• AZURE_CLIENT_ID. Используется для идентификации зарегистрированного приложения в Azure.
• AZURE_TENANT_ID: идентификатор клиента Microsoft Entra.
• AZURE_CLIENT_SECRET: секретные учетные данные, созданные для приложения.

Visual Studio Code

В Visual Studio Code переменные среды можно задать в launch.json файле проекта. Эти значения автоматически извлекаются при запуске приложения. Однако эти конфигурации не перемещаются вместе с приложением во время развертывания, поэтому необходимо настроить переменные среды в целевой среде размещения.

"configurations": [
{
    "env": {
        "NODE_ENV": "development",
        "AZURE_CLIENT_ID": "<your-client-id>",
        "AZURE_TENANT_ID":"<your-tenant-id>",
        "AZURE_CLIENT_SECRET": "<your-client-secret>"
    }
}

Виндоус

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

# Set user environment variables
setx NODE_ENV "development"
setx AZURE_CLIENT_ID "<your-client-id>"
setx AZURE_TENANT_ID "<your-tenant-id>"
setx AZURE_CLIENT_SECRET "<your-client-secret>"

# Set system environment variables - requires running as admin
setx NODE_ENV "development" /m
setx AZURE_CLIENT_ID "<your-client-id>" /m
setx AZURE_TENANT_ID "<your-tenant-id>" /m
setx AZURE_CLIENT_SECRET "<your-client-secret>" /m

PowerShell также можно использовать для задания переменных среды на уровне пользователя или системы:

# Set user environment variables
[Environment]::SetEnvironmentVariable("NODE_ENV", "development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("NODE_ENV", "development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "<your-client-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "<your-tenant-id>", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "<your-client-secret>", "Machine")

ENV-файл

Для локальной разработки можно использовать файл .env. Node.js 20.6.0 и более поздние версии поддерживают флаг --env-file для автоматической загрузки переменных окружения из файла .env.

1. Создайте файл .env в корневом каталоге проекта.

   AZURE_CLIENT_ID=<your-client-id>
   AZURE_TENANT_ID=<your-tenant-id>
   AZURE_CLIENT_SECRET=<your-client-secret>
   

2. Запустите приложение с флагом --env-file :

   node --env-file=.env app.js
   

Для более ранних версий Node.js можно использовать пакет dotenv npm:

1. Установите пакет dotenv.

   npm install dotenv
   

2. Загрузите переменные среды в приложении:

   import 'dotenv/config';
   

Caution

Никогда не фиксируйте .env файлы или секреты клиента в системе управления версиями. Добавьте .env в .gitignore файл.

Авторизация в службах Azure из вашего приложения

Библиотека Azure Identity предоставляет различные учетные данные — реализации , адаптированные для поддержки различных сценариев и потоков аутентификации Microsoft Entra. В следующих шагах показано, как использовать ClientSecretCredential при работе со служебными учётными записями локально и в рабочей среде.

Реализация кода

Добавьте пакет @azure/identity в проект Node.js:

npm install @azure/identity

Для обращения к службам Azure используются специализированные клиентские классы из различных клиентских библиотек Azure SDK. Для любого кода JavaScript, создающего клиентский объект Azure SDK в приложении, выполните следующие действия:

1. ClientSecretCredential Импортируйте класс из @azure/identity модуля.
2. Создайте объект с ClientSecretCredential, tenantId, clientId и clientSecret.
3. Передайте экземпляр конструктору ClientSecretCredential клиентского объекта пакета SDK Azure.

Пример этого подхода показан в следующем сегменте кода:

import { BlobServiceClient } from '@azure/storage-blob';
import { ClientSecretCredential } from '@azure/identity';

// Authentication
const tenantId = process.env.AZURE_TENANT_ID;
const clientId = process.env.AZURE_CLIENT_ID;
const clientSecret = process.env.AZURE_CLIENT_SECRET;

// Azure Storage account name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!tenantId || !clientId || !clientSecret || !accountName) {
  throw Error('Required environment variables not found');
}

const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  credential
);

Альтернативный подход — передать ClientSecretCredential объект непосредственно конструктору клиента Пакета SDK Azure:

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new ClientSecretCredential(tenantId, clientId, clientSecret)
);