Настройка проверки подлинности службы приложений (EasyAuth)

Служба приложений Azure обеспечивает встроенную проверку подлинности (часто называемую EasyAuth), которая обрабатывает вход пользователей перед запросами к приложению. Конструктор API данных может считывать сведения об удостоверениях, которые App Service внедряет, обеспечивая аутентификацию без непосредственного управления токенами.

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

Когда Data API Builder выполняется за Azure App Service с включенной проверкой подлинности, Azure App Service обрабатывает поток OAuth и передает сведения об удостоверении через заголовки HTTP:

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

• подписка Azure
• Служба приложений Azure или функции Azure (инфраструктура службы приложений)
• CLI для построителя API данных (руководство по установке)
• Существующая dab-config.json, содержащая по крайней мере одну сущность

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

Шаг 1. Включение проверки подлинности службы приложений

Настройка проверки подлинности в Службе приложений Azure:

1. На портале Azure перейдите в службу приложений.

2. Выберите Настройки>Проверка подлинности.

3. Выберите Добавить поставщик удостоверений.

4. Выберите корпорацию Майкрософт (или другой поддерживаемый поставщик).

5. Настройте параметры:

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

6. Нажмите кнопку "Добавить".

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

Установите поставщика аутентификации на AppService

CLI

dab configure \
  --runtime.host.authentication.provider AppService

dab configure ^
  --runtime.host.authentication.provider AppService

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

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  }
}

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

Определите разрешения для ролей. Построитель API данных оценивает роли через ClaimsPrincipal.IsInRole(), путем проверки утверждений, извлеченных из заголовка X-MS-CLIENT-PRINCIPAL. Включите утверждения роли в массив claims с соответствующим типом роли.

Пример конфигурации

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow editors to create and update
dab update Book \
  --permissions "editor:create,read,update"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM Allow editors to create and update
dab update Book ^
  --permissions "editor:create,read,update"

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

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Шаг 4. Тестирование локально с помощью X-MS-CLIENT-PRINCIPAL

Проверку подлинности службы приложений можно проверить локально, указав X-MS-CLIENT-PRINCIPAL заголовок вручную. Этот подход имитирует то, что EasyAuth перенаправит в ваше приложение и позволяет тестировать поведение, основанное на ролях и утверждениях, без необходимости развертывания в Azure.

Создание субъекта-клиента

Заголовок X-MS-CLIENT-PRINCIPAL содержит объект JSON в кодировке Base64. Построитель API данных анализирует следующие свойства:

{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "Alice Smith" },
    { "typ": "email", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" },
    { "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "abc-123-def" }
  ]
}

Кодирование субъекта

Закодируйте JSON в формат Base64. Вы можете использовать любое средство:

PowerShell.

$json = @'
{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}
'@
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))

Бить:

echo '{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}' | base64

Отправка запроса с заголовком

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-CLIENT-PRINCIPAL: eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoidXNlci0xMjM0NSIsInVzZXJEZXRhaWxzIjoiYWxpY2VAY29udG9zby5jb20iLCJ1c2VyUm9sZXMiOlsiYXV0aGVudGljYXRlZCIsImVkaXRvciJdfQ==" \
  -H "X-MS-API-ROLE: editor"

Структура X-MS-CLIENT-PRINCIPAL

Построитель API данных анализирует следующие свойства из субъекта-клиента:

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

С помощью поставщика AppService можно использовать утверждения в политиках базы данных. Эта возможность обеспечивает безопасность на уровне строк на основе удостоверения пользователя.

Пример. Фильтрация по идентификатору объекта пользователя

В этом примере используется утверждение oid (идентификатор объекта), которое Microsoft Entra ID включает в токены:

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Доступные ссылки на утверждения

Ссылки на утверждения используют точную строку типа утверждения из массива claims :

Например, если ваш основной код содержит { "typ": "email", "val": "alice@contoso.com" }, используйте @claims.email в вашей политике. Тип утверждения должен совпадать точно.

Анонимные запросы

Если служба приложений разрешает неаутентифицированные запросы или при локальном тестировании без заголовка X-MS-CLIENT-PRINCIPAL, промежуточное программное обеспечение для проверки подлинности API данных автоматически задает заголовок X-MS-API-ROLE как anonymous. Затем запросы оцениваются с помощью роли anonymous.

# No principal header = anonymous role (X-MS-API-ROLE set automatically)
curl -X GET "http://localhost:5000/api/Book"

Для анонимного anonymous доступа к работе сущность должна иметь разрешения для роли:

{
  "permissions": [
    {
      "role": "anonymous",
      "actions": ["read"]
    }
  ]
}

Troubleshooting

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

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    },
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

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

• Обзор авторизации
• Безопасность на уровне строк с контекстом сеанса
• Настройте аутентификацию Microsoft Entra ID
• Настройка проверки подлинности симулятора для тестирования