Настройка пользовательской проверки подлинности JWT (Okta, Auth0)

Построитель Data API поддерживает сторонних поставщиков удостоверений через настраиваемого поставщика аутентификации с помощью проверки JSON веб-токена (JWT). Используйте этот подход, если в организации используется поставщик удостоверений, совместимый с Okta, Auth0 или другой поставщик удостоверений, совместимый с OAuth 2.0/OpenID Connect.

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

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

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

Phase	Что происходит
Проверка подлинности пользователя	Пользователь входит через поставщика удостоверений (Okta, Auth0 и т. д.)
Приобретение токена	Клиентское приложение получает токен доступа от поставщика удостоверений
Вызов API	Клиент отправляет токен в DAB в заголовке `Authorization`
Проверка	DAB проверяет JWT (издатель, аудитория, подпись)
Авторизация	DAB извлекает роли и оценивает разрешения

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

Учетная запись у вашего поставщика удостоверений (Okta, Auth0 и т. д.)
Приложение, зарегистрированное в провайдере идентификации
CLI для построителя API данных (руководство по установке)
Существующая dab-config.json, содержащая по крайней мере одну сущность

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

Setting	Ценность
Поставщик	`Custom`
Требуется для проверки	`iss`, , `audexp`допустимая подпись
Требуется для авторизации	`roles` утверждение, содержащее выбранную роль
Заголовок токена	`Authorization: Bearer <token>`
Тип утверждения роли	`roles` (фиксированный, не настраиваемый)
Заголовок выбора ролей	`X-MS-API-ROLE`

Шаг 1. Настройка поставщика удостоверений

Точные шаги зависят от поставщика. Ниже приведены необходимые ключевые значения:

Значения для сбора

Ценность	Расположение	Используется для
URL-адрес издателя	Документация поставщика или конечная точка метаданных OAuth	DAB `jwt.issuer` (используется в качестве центра JWT)
Публика	Идентификатор клиента приложения или пользовательский идентификатор API	DAB `jwt.audience`

Замечание

DAB использует настроенный jwt.issuer в качестве JWT Authority. Ключи подписывания обнаруживаются автоматически с помощью стандартных метаданных OpenID Connect (обычно <issuer>/.well-known/openid-configuration).

Пример Okta

Войдите в консоль администрирования Okta.
Перейдите к приложениям>.
Создайте или выберите приложение.
Обратите внимание на идентификатор клиента (используйте в качестве аудитории).
Обычно вашим эмитентом является https://<your-domain>.okta.com.

Пример Auth0

Войдите на панель мониторинга Auth0.
Перейдите к Приложениям>API.
Создайте или выберите API.
Обратите внимание на идентификатор (используйте как критерий для аудитории).
Ваш эмитент https://<your-tenant>.auth0.com/.

Это важно

Конструктор API данных использует фиксированный тип roles требования для авторизации на основе ролей. Это значение нельзя настроить. Если поставщик удостоверений излучает роли в другом утверждении (например, groups или permissions), необходимо настроить поставщика, чтобы также излучалось утверждение roles, или использовать действие после входа для копирования значений в утверждение roles.

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

Установите поставщик проверки подлинности на Custom и настройте параметры JWT.

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

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

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

REM Set the expected audience
dab configure ^
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

REM Set the expected issuer
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

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

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

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

Определите разрешения для ролей, которые назначает ваш поставщик удостоверений.

CLI

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

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

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

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

REM Allow users with 'admin' role full access
dab update Book ^
  --permissions "admin:*"

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

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Шаг 4. Настройка ролей в поставщике удостоверений

DAB ожидает роли в запросе roles. Настройте поставщика удостоверений, чтобы включить это утверждение.

Okta: добавление групп в качестве ролей

В консоли администрирования Okta перейдите вAPI>.
Выберите сервер авторизации.
Перейдите на вкладку "Утверждения ".
Добавьте утверждение:
- Имя: roles
- Включить в тип маркера: маркер доступа
- Тип значения: группы
- Фильтр: выберите группы для включения

Auth0: добавление ролей с помощью действия

На панели мониторинга Auth0 перейдите вбиблиотеку>.
Создайте новое действие (триггер post login).
Добавьте код для включения ролей:

exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};

Разверните действие и добавьте его в поток входа.

Подсказка

Подробные инструкции по настройке утверждений JWT с помощью Okta см. в разделе "Настройка токенов, возвращаемых из Okta".

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

Запуск построителя API данных:
```
dab start
```
Получите токен от поставщика удостоверений. Используйте пакет SDK поставщика или средство, например Postman.
Осмотрите токен на jwt.io для верификации.
- Утверждение aud соответствует предназначенной аудитории
- Утверждение iss соответствует настроенному эмитенту
- Утверждение roles содержит ожидаемые значения

Вызов 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: admin"
```

Сведения о проверке JWT

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

Проверьте	Описание
Подпись	Проверено с помощью ключей подписывания, обнаруженных через настроенный `jwt.issuer` центр авторизации (метаданные OpenID Connect или набор веб-ключей JSON (JWKS))
Эмитент	Должна точно соответствовать `jwt.issuer` конфигурации
Публика	Должна точно соответствовать `jwt.audience` конфигурации
Истечение срока действия	Срок действия токена не должен истекать (`exp` утверждение)
Не раньше	Токен должен быть допустимым (`nbf` утверждение, если он присутствует)

Troubleshooting

Симптом	Возможная причина	Решение
`401 Unauthorized`	Несоответствие издателя	`iss` Проверьте точное соответствие утверждения (включая косую черту)
`401 Unauthorized`	Несоответствие аудитории	Проверьте, совпадает ли утверждение `aud` с вашим настроенным значением
`401 Unauthorized`	Срок действия маркера истек	Получение нового токена
`401 Unauthorized`	Метаданные недоступны	Убедитесь, что DAB достигнет `<issuer>/.well-known/openid-configuration`
`403 Forbidden`	Роль не в токене	Добавьте роль в конфигурацию поставщика удостоверений
`403 Forbidden`	Запрос не `roles` найден	Настройте поставщика удостоверений `roles` для включения утверждения
`403 Forbidden`	Неправильное имя утверждения	DAB использует тип утверждения `roles` (фиксированный, не конфигурируемый)

Это важно

В настоящее время DAB использует тип утверждения roles для всех проверок ролей. Это значение жестко закодировано и не может быть изменено на groups, permissionsили другие имена утверждений. Настройте поставщика удостоверений для выдачи ролей в утверждении с именем roles.

Распространенные форматы эмитентов

Поставщик	Формат издателя
Okta	`https://<domain>.okta.com` или `https://<domain>.okta.com/oauth2/default`
Auth0	`https://<tenant>.auth0.com/` (обратите внимание на косую черту)
Azure AD B2C	`https://<tenant>.b2clogin.com/<tenant-id>/v2.0/`
Keycloak	`https://<host>/realms/<realm>`

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

Конфигурация Okta

{
  "$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": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Конфигурация Auth0

{
  "$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": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

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

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

Last updated on 2026-04-01

Настройка пользовательской проверки подлинности JWT (Okta, Auth0)

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

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

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

Шаг 1. Настройка поставщика удостоверений

Значения для сбора

Пример Okta

Пример Auth0

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

CLI

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

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

CLI

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

Шаг 4. Настройка ролей в поставщике удостоверений

Okta: добавление групп в качестве ролей

Auth0: добавление ролей с помощью действия

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

Сведения о проверке JWT

Troubleshooting

Распространенные форматы эмитентов

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

Конфигурация Okta

Конфигурация Auth0

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

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

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