Настройка аутентификации Microsoft Entra ID

В этом руководстве описана настройка проверки подлинности Microsoft Entra ID (прежнее название — Azure Active Directory) для построителя API данных. К концу клиентское приложение аутентифицирует пользователей через Entra, получает токены для Data API Builder, а DAB может использовать управляемую идентификацию для подключения к Azure SQL.

Построитель API данных проверяет подлинность входящих запросов с помощью валидатора токенов носителя JSON Web Token (JWT) или заголовков удостоверений, предоставляемых платформой. Для локальной разработки и тестирования разрешений используйте поставщика Simulator.

Иллюстрация того, как клиенты проходят проверку подлинности в построителе API данных с помощью токенов JWT.

Руководства для поставщиков аутентификации

Выберите руководство на основе поставщика удостоверений:

Поставщик	Guide
Майкрософт Ентра айди	Эта статья
Okta, Auth0 или другое	Настройка пользовательской проверки подлинности JWT
Служба приложений Azure	Настройка проверки подлинности службы приложений
Локальное тестирование	Настройка проверки подлинности симулятора

Поток аутентификации

Поток состоит из трех отдельных этапов:

Phase	Описание
Проверка подлинности пользователя	Пользователь входит через клиентское приложение с помощью Microsoft Entra ID
Проверка подлинности клиента	Клиентское приложение получает токен с областью действия DAB и вызывает строитель API данных
Доступ к базе данных	Построитель Data API проверяет токен, а затем подключается к базе данных, используя своё собственное удостоверение (управляемое удостоверение или учетные данные в формате connection string).

Это важно

Построитель API данных проверяет входящие токены пользователя для аутентификации API, но подключается к базе данных, используя свои учетные данные (управляемое удостоверение или проверка подлинности SQL). DAB по умолчанию не выполняет обмен токенами On-Behalf-Of (OBO) для доступа к базе данных как вызывающий пользователь. Чтобы включить OBO, чтобы база данных выполняла проверку подлинности в качестве фактического вызывающего пользователя, см. раздел "Настройка проверки подлинности OBO".

Необходимые условия

Подписка Azure с клиентом Идентификатора Microsoft Entra
CLI для построителя API данных (руководство по установке)
Существующая dab-config.json, содержащая по крайней мере одну сущность
(Необязательно) База данных Azure SQL для сценариев с управляемой идентичностью

Краткий справочник

Setting	Ценность
Поставщик	`EntraID` (или `AzureAD` для совместимости)
Требуется для проверки	`aud`, , `issexp`допустимая подпись
Требуется для авторизации	`roles` утверждение (только при использовании пользовательских ролей)
Формат издателя	`https://login.microsoftonline.com/<tenant-id>/v2.0`
Формат аудитории	`api://<app-id>` или URI пользовательского идентификатора приложения
Роль по умолчанию	`Authenticated`
Пользовательский заголовок роли	`X-MS-API-ROLE`
Тип утверждения роли	`roles` (фиксированный, не настраиваемый)

Замечание

Если в качестве поставщика используется EntraID или AzureAD, DAB обеспечивает дополнительную проверку издателя ключей подписи, относящейся к токенам Microsoft Entra. Эта проверка обеспечивает более высокий уровень безопасности по сравнению с универсальным Custom поставщиком.

Шаг 1. Регистрация приложения в Microsoft Entra ID

Создайте регистрацию приложения, представляющую ваш API для Data API builder. Клиентские приложения запрашивают токены с аудиторией, соответствующей данной регистрации.

Войдите в Центр администрирования Microsoft Entra.
Перейдите к Identity>Applications>App registrations.
Выберите Новая регистрация.
Введите имя (например, Data API Builder API).
Выберите подходящие типы поддерживаемых учетных записей для вашего сценария:
- Один клиент: только пользователи в организации
- Multitenant: Пользователи в любом каталоге Microsoft Entra
Оставьте URI перенаправления пустым (эта регистрация предназначена для API, а не клиента).
Выберите Зарегистрировать.

На странице обзора приложения запишите следующие значения:

Ценность	Расположение	Используется для
Идентификатор приложения (клиента)	Страница обзора	Создание URI для аудитории
Идентификатор каталога (клиента)	Страница обзора	Создание URL-адреса издателя

Настройка URI идентификатора приложения

В регистрации приложения перейдите к разделу "Предоставление API".
Выберите Добавить рядом с URI идентификатора приложения.
Примите значение по умолчанию (api://<app-id>) или введите URI.
Нажмите Сохранить.

Подсказка

URI идентификатора приложения становится значением audience в конфигурации DAB. Используйте согласованный формат в разных средах.

Добавить область

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

В регистрации приложения перейдите к разделу "Предоставление API".
В разделе "Области", определенные этим API, выберите "Добавить область".
Введите:
- Имя области: Endpoint.Access
- Кто может предоставить согласие?: администраторы и пользователи
- Отображаемое имя согласия администратора: Execute requests against Data API builder
- Описание согласия администратора: Allows client app to send requests to Data API builder endpoint.
- Отображаемое имя согласия пользователя: Execute requests against Data API builder
- Описание согласия пользователя: Allows client app to send requests to Data API builder endpoint.
- Состояние: включено
Выберите Добавить область.

Замечание

Полное значение области — api://<app-id>/Endpoint.Access. Клиентские приложения используют это значение для запроса токенов.

Добавление ролей приложения (необязательно)

Если вы хотите использовать пользовательские роли за пределами Anonymous и Authenticated:

Перейдите к ролям приложений.
Выберите "Создать роль приложения".
Введите:
- Отображаемое имя: Reader
- Разрешенные типы элементов: пользователи или группы или оба
- Значение: reader (это значение отображается в утверждении токена roles )
- Описание: Read-only access to data
Нажмите кнопку "Применить".
Повторите для других ролей (например, writer, admin).

Установите версию токена манифеста

По умолчанию манифест регистрации приложения задает accessTokenAcceptedVersion, что приводит к созданию токенов версии 1.0 null. Токены v1 используют другой формат издателя (https://sts.windows.net/<tenant-id>/), чем издатель v2.0, настроенный в DAB, что приводит к сбою валидации токена.

В регистрации приложения перейдите к манифесту.
Найдите accessTokenAcceptedVersion и измените значение 2на .
Нажмите Сохранить.

Это важно

Если accessTokenAcceptedVersion является null или 1, утверждение iss в токене не соответствует URL-адресу издателя версии 2.0, настроенному в DAB, и все запросы завершаются ошибкой 401 Unauthorized.

Назначить пользователей на роли в приложении

Создание ролей приложений не предоставляет их пользователям автоматически. Необходимо назначить пользователей или группы через корпоративное приложение.

В центре администрирования Microsoft Entra перейдите к Identity>Applications>Enterprise apps.
Найдите и выберите приложение (например, Data API Builder API). Корпоративное приложение было создано автоматически при регистрации приложения.
Перейдите к пользователям и группам.
Выберите Добавить пользователя или группу.
В разделе Пользователи выберите учетную запись пользователя, чтобы назначить, и нажмите Выбрать.
В разделе "Выбор роли" выберите роль, назначаемую (например, Reader). Если роль не отображается, подождите несколько минут до завершения репликации Microsoft Entra.
Выберите Назначить.
Повторите для каждой роли, которую вы хотите назначить.

Замечание

Без назначения ролей roles утверждение в маркере пользователя пусто, и запросы, использующие настраиваемую роль X-MS-API-ROLE, отклоняются с 403 Forbidden.

Шаг 2. Настройка построителя API данных

Настройте DAB для проверки токенов, выданных арендатором Entra для аудитории API.

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider EntraID

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider EntraID

REM Set the expected audience (Application ID URI)
dab configure ^
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

REM Set the expected issuer (your tenant)
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

Итоговая конфигурация

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
        }
      }
    }
  }
}

Шаг 3. Настройка разрешений сущности

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

Предоставление доступа пользователям, прошедшим проверку подлинности

Bash
Командная строка

dab update Book \
  --permissions "Authenticated:read"

dab update Book ^
  --permissions "Authenticated:read"

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

Bash
Командная строка

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

dab update Book ^
  --permissions "reader:read" ^
  --permissions "writer:create,read,update"

Итоговая конфигурация

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Шаг 4. Настройка подключения к базе данных

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

Замечание

Подключение к базе данных использует удостоверение службы DAB (управляемое удостоверение или учетные данные SQL), а не удостоверение вызывающего пользователя. DAB не передает токены пользователя в базу данных.

Вариант A. Управляемое удостоверение (рекомендуется для Azure)

Системно назначенная управляемая идентичность

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

Управляемая идентификация, назначаемая пользователем

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

Вариант B: проверка подлинности SQL (разработка)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

Это важно

Никогда не коммитить строки подключения с паролями в систему управления версиями. Используйте переменные среды или Azure Key Vault.

Вариант C: локальная разработка с помощью `az login`

Для локальной разработки для Azure SQL используйте учетные данные Azure CLI:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

Перед запуском DAB выполните вход:

az login

Шаг 5. Проверка конфигурации

Авторизация Azure CLI в качестве клиентского приложения

Прежде чем Azure CLI сможет получить токены для API, необходимо добавить его как авторизованное клиентское приложение.

В регистрации приложения перейдите к разделу "Предоставление API".
В разделе Авторизованные клиентские приложения выберите Добавить клиентское приложение.
Введите идентификатор клиента Azure CLI: 00001111-aaaa-2222-bbbb-3333cccc4444.
Выберите область api://<app-id>/Endpoint.Access.
Выберите Добавить приложение.

Получите токен с помощью Azure CLI

Войдите в Azure CLI и задайте клиент, в котором существует регистрация приложения:

az login
az account set --tenant <your-tenant-id>

Запросите токен, ограниченный для вашего API.

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

Замечание

Если вы получили ошибку согласия AADSTS65001, убедитесь, что вы добавили идентификатор клиента Azure CLI (00001111-aaaa-2222-bbbb-3333cccc4444) в качестве авторизованного клиентского приложения на предыдущем шаге.

Маркер можно проверить на jwt.ms, чтобы проверить утверждения aud, iss и roles.

Запуск DAB и отправка запроса

Запуск построителя API данных:
```
dab start
```

вызовите API с токеном:

curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

Чтобы использовать пользовательскую роль, включите заголовок X-MS-API-ROLE:
```
curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: reader"
```

Замечание

Роль, указанная в X-MS-API-ROLE утверждении маркера roles , должна существовать. Если роль не содержится в маркере, запрос отклоняется.

Поведение выбора ролей

Построитель API данных определяет роль запроса с помощью этой логики:

Токен присутствует?	Заголовок X-MS-API-ROLE?	Какова роль данного токена?	Результат
Нет	Нет	—	`Anonymous`
Да (допустимо)	Нет	—	`Authenticated`
Да (допустимо)	Да	Нет	Отклонено (403 Запрещено)
Да (допустимо)	Да	Да	Значение заголовка
Да (недопустимо)	—	—	Отклонено (401 Несанкционированное)

Troubleshooting

Симптом	Возможная причина	Решение
`401 Unauthorized`	Срок действия токена истек или он искажен.	Получите новый токен; проверьте токен на jwt.ms
`401 Unauthorized`	Несоответствие аудитории	Проверьте, что `jwt.audience` соответствует утверждению `aud` токена
`401 Unauthorized`	Несоответствие издателя	Убедитесь, что `jwt.issuer` точно соответствует утверждению токена `iss`
`403 Forbidden`	Роль не в токене	Убедитесь, что пользователь назначен на роль приложения в системе Entra
`403 Forbidden`	Нет разрешений для роли	Добавление роли в массив сущности `permissions`

Полный пример конфигурации

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2026-04-01

Настройка аутентификации Microsoft Entra ID

Руководства для поставщиков аутентификации

Поток аутентификации

Необходимые условия

Краткий справочник

Шаг 1. Регистрация приложения в Microsoft Entra ID

Настройка URI идентификатора приложения

Добавить область

Добавление ролей приложения (необязательно)

Установите версию токена манифеста

Назначить пользователей на роли в приложении

Шаг 2. Настройка построителя API данных

CLI

Итоговая конфигурация

Шаг 3. Настройка разрешений сущности

Предоставление доступа пользователям, прошедшим проверку подлинности

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

Итоговая конфигурация

Шаг 4. Настройка подключения к базе данных

Вариант A. Управляемое удостоверение (рекомендуется для Azure)

Системно назначенная управляемая идентичность

Управляемая идентификация, назначаемая пользователем

Вариант B: проверка подлинности SQL (разработка)

Вариант C: локальная разработка с помощью az login

Шаг 5. Проверка конфигурации

Авторизация Azure CLI в качестве клиентского приложения

Получите токен с помощью Azure CLI

Запуск DAB и отправка запроса

Поведение выбора ролей

Troubleshooting

Полный пример конфигурации

Связанный контент

Кері байланыс

Қосымша ресурстар

Вариант C: локальная разработка с помощью `az login`