Защита агента Amazon Bedrock с помощью Microsoft Entra ID для агентов

В этом руководстве показано, как защитить агента Amazon Bedrock с помощью пакета SDK Microsoft Entra ID Auth (sidecar) для аутентификации при обращении к нижестоящим API. Контейнер сайдкар работает как отдельный контейнер и обрабатывает управление учетными данными и обмен токенами с Microsoft Entra ID. Агент запрашивает заголовок авторизации у вспомогательного модуля, а вспомогательный модуль обрабатывает обмен по протоколу OAuth 2.0 с Microsoft Entra ID.

Предпосылки

Прежде чем начать, убедитесь, что у вас есть:

Клиент Microsoft Entra.
Подписка Azure.
Docker Desktop (macOS/Windows) или Подсистема Docker с Compose версии 2 (Linux).
PowerShell 7+.
Azure CLI.
AWS CLI версии 2.
Учетная запись AWS с активированным доступом к модели Bedrock для Anthropic Claude 3 Haiku (или другой выбранной вами модели). Включите доступ в консоли AWS Bedrock в разделе "Доступ к модели>Управление доступом к модели".
Global Administrator роль для начальной настройки Microsoft Entra. Используйте управление привилегированными пользователями (PIM) для активации этой роли по запросу.

Клонирование примера репозитория

Клонируйте репозиторий и перейдите в пример каталога AWS:

git clone https://github.com/microsoft/entra-agentid-samples.git
cd entra-agentid-samples/sidecar/aws

Архитектура

SDK аутентификации Microsoft Entra ID (sidecar) находится между вашим агентом и Microsoft Entra ID. Агент никогда не взаимодействует с Microsoft Entra ID напрямую и никогда не управляет учетными данными. Он запрашивает у сайдкара заголовок Authorization, чтобы вызвать downstream API. Amazon Bedrock обрабатывает вывод значений LLM отдельно, не беспокоясь об удостоверении личности.

Пример выполняет три контейнера в сети моста Docker:

llm-agent-aws: приложение Flask с интерфейсом чата и агентом ReAct от LangGraph, который вызывает Amazon Bedrock (Claude) для рассуждения. Предоставляется через порт 3001.
agent-id-sidecar-aws: Официальный контейнер SDK аутентификации Microsoft Entra ID (sidecar). Получает и кэширует токены. Нет порта узла, доступного только из сети Docker.
weather-api-aws: Внешний API, который проверяет агентский JWT (подпись, издатель, срок действия, аудиторию) по каждому запросу и возвращает данные о погоде.

Запрос проходит через следующие действия:

Вы вводите запрос в пользовательском интерфейсе http://localhost:3001чата.
Приложение Flask отправляет запрос в AWS Bedrock (Claude) через агент ReAct LangGraph.
Когда Клод решает, что ему нужны данные о погоде, он вызывает get_weather инструмент.
Средство запрашивает у sidecar Authorization-заголовок посредством вызова GET /AuthorizationHeader?AgentIdentity={agentId}.
Сайдкар проходит аутентификацию в Microsoft Entra ID с помощью OAuth 2.0 (учетные данные клиента или обмен от имени пользователя (OBO)).
Microsoft Entra ID возвращает запрошенный маркер (TR) на боковую панель.
Агент вызывает API погоды с Authorization: Bearer TR.
API погоды проверяет TR и возвращает ответ погоды JSON.

Понимание потока токенов

В обмене удостоверениями участвуют три токена:

Маркер	Выдано	Когда	Как
Tc	Авторизованный пользователь	Только поток OBO	MSAL.js в браузере
T1	Приложение схемы	Оба потока	Sidecar (учетные данные клиента)
TR	Агент (нижестоящий API)	Оба потока	Только "Sidecar-app-only" (автономный) или обмен "OBO"

В автономном потоке сайдкар использует учетные данные клиента для получения T1, а затем обменивает его на TR, предназначенный для нижележащего API. В OBO-потоке сайдкар также получает Tc (токен пользователя) и выполняет обмен по протоколу OBO, чтобы получить TR, который действует от имени вошедшего пользователя.

В этой настройке для вашего хоста доступен только пользовательский интерфейс чата (порт 3001). Сайдкар и API погоды доступны только в сети Docker, которая устанавливает четкую границу безопасности.

Выберите режим выполнения и поток идентификаций

Пример поддерживает два режима выполнения и два потока удостоверений, которые можно объединить:

	Автономный (только для приложений)	OBO (от имени пользователя)
Direct (без LLM)	Быстрый демонстрационный маршрут. Токен извлекается, и API погоды вызывается непосредственно.	То же, но используется аутентифицированная конечная точка sidecar с токеном пользователя.
Bedrock + LangChain	Агент LangGraph ReAct решает, когда вызывать `get_weather`.	То же самое, но агент передает маркер пользователя при запуске средства.

Используйте режим Direct для полной проверки сквозного процесса токенов без необходимости доступа к AWS Bedrock. Переключитесь в режим Bedrock для полного взаимодействия с агентом.

Выбор уровня проверки подлинности AWS

Пример поддерживает три способа проверки подлинности в Amazon Bedrock. Выберите уровень, соответствующий вашей среде:

Временные учетные данные STS: Идеально для локальной разработки с использованием AWS SSO. Задайте AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYи AWS_SESSION_TOKEN в .env файле. Срок действия этих учетных данных истекает примерно через час.
Ключ Bedrock API: Лучше всего подходит для демонстраций и семинаров. Задайте AWS_BEARER_TOKEN_BEDROCK в .env файле. Он применяется только в Bedrock с настраиваемым временем существования.
oidC federation: Лучше всего подходит для рабочих развертываний на Служба приложений Azure. Использует AWS_ROLE_ARN и AWS_WEB_IDENTITY_TOKEN_FILE, заданные платформой. Нет секретов, хранящихся в любом месте.

Подсказка

Сведения о развертывании в рабочей среде см. в руководстве по развертыванию Служба приложений Azure. Здесь приведены пошаговые инструкции по настройке OIDC-федерации между Azure и AWS без сохранения секретов.

Выбор модели Bedrock

Пример по умолчанию задается как us.anthropic.claude-3-haiku-20240307-v1:0, так как это самая дешёвая модель Anthropic в Bedrock и она поддерживает вызовы инструментов. Префикс us. указывает профиль кросс-регионального вывода, который осуществляет маршрутизацию между регионами США для повышения доступности.

Другие поддерживаемые модели:

Идентификатор модели	Затраты на 1K входных токенов	Notes
`us.anthropic.claude-3-haiku-20240307-v1:0`	$0,00025	Default. Быстрый, наиболее дешевый, поддерживает вызов инструментов.
`us.anthropic.claude-3-5-haiku-20241022-v1:0`	$0,0008	Более новые, умные, все еще доступные.
`us.anthropic.claude-3-5-sonnet-20241022-v2:0`	$0,003	Лучшее соотношение качества и стоимости.

Переопределите значение по умолчанию, установив BEDROCK_MODEL_ID в вашем файле .env. Необходимо включить каждую модель в консоли AWS Bedrock>Модельный доступ, прежде чем ее можно будет вызвать.

Создание объектов Microsoft Entra (при первой настройке)

Если у вас уже есть .env файл из предыдущего запуска с BLUEPRINT_APP_ID заполненным, перейдите к разделу "Настройка переменных среды".

Выполните следующие команды один раз для каждого клиента, чтобы создать приложение Blueprint, идентификатор агента и приложение SPA, используемое для входа в систему OBO.

Создайте приложение схемы и идентификатор агента для автономного потока, выполнив рабочий процесс PowerShell в разделе "Создание схемы удостоверения агента " и "Создание удостоверений агента". В конце концов у вас есть:
- TENANT_ID: ваш клиент Microsoft Entra.
- BLUEPRINT_APP_ID: регистрация приложения Blueprint.
- BLUEPRINT_CLIENT_SECRET: секрет клиента для Blueprint.
- AGENT_CLIENT_ID: идентификатор агента, созданный на основе схемы.
(Необязательно) Создайте приложение SPA и настройте OBO. Этот шаг требуется только в том случае, если требуется использовать поток удостоверений OBO:

Выполните следующие скрипты, чтобы создать регистрацию SPA-приложения и настроить разрешения OBO в Blueprint. Скрипты регистрируют URI перенаправления SPA и предоставляют необходимые делегированные разрешения.

Bash:
```
bash ../../scripts/setup-obo-client-app.sh
bash ../../scripts/setup-obo-blueprint.sh
```
PowerShell:
```
pwsh ../../scripts/setup-obo-client-app.ps1
pwsh ../../scripts/setup-obo-blueprint.ps1 `
    -TenantId        '<TENANT_ID>' `
    -BlueprintAppId  '<BLUEPRINT_APP_ID>' `
    -AgentAppId      '<AGENT_CLIENT_ID>' `
    -ClientSpaAppId  '<CLIENT_SPA_APP_ID>'
```

URI перенаправления SPA для этого примера — http://localhost:3001 порт 3001, а не 3003. Убедитесь, что этот универсальный код ресурса (URI) зарегистрирован.

Настройка переменных среды

Сайдкар поддерживает несколько типов удостоверений через параметр AzureAd__ClientCredentials__0__SourceType в docker-compose.yml:

ClientSecret: только локальная разработка. Пример включает этот тип.
SignedAssertionFromManagedIdentity: развернуто на Azure. Нет секретов, рекомендуется для производственной среды.
KeyVault: Сертификат из Azure Key Vault.
StoreWithThumbprint: сертификат из локального хранилища компьютеров.

Создайте локальный .env файл конфигурации из включенного шаблона. Этот файл хранит учетные данные клиента, приложения и AWS:

Bash:

cp .env.example .env

PowerShell:

Copy-Item .env.example .env

Задайте следующие переменные в .env файле:
- TENANT_ID: идентификатор клиента Microsoft Entra.
- BLUEPRINT_APP_ID: регистрация приложения Blueprint. Сайдкар аутентифицируется как это приложение.
- BLUEPRINT_CLIENT_SECRET: секрет клиента Blueprint (только для локальной разработки).
- AGENT_CLIENT_ID: идентификатор агента. Отображается в качестве AgentIdentity параметра запроса.
- CLIENT_SPA_APP_ID: идентификатор приложения SPA, используемый MSAL.js для входа через браузер (только OBO).
- AWS_REGION: регион AWS для Bedrock, например us-east-2.
- BEDROCK_MODEL_ID: идентификатор модели. По умолчанию: us.anthropic.claude-3-haiku-20240307-v1:0.
- VALIDATE_TOKEN_SIGNATURE: по умолчанию true. Установите false для пропуска проверки подписи JWKS в API погоды (только для отладки).
Добавьте ваши учетные данные AWS в соответствии с выбранным вами уровнем:
- Уровень A (STS): Задать AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYи AWS_SESSION_TOKEN.
- Уровень B (ключ API): Задать AWS_BEARER_TOKEN_BEDROCK.
- Уровень C (OIDC): Настроено с помощью параметров приложения платформы, а не в .env.

Подсказка

Если у вас уже есть .env из предыдущего сеанса, необходимо обновить учетные данные AWS (срок действия маркеров STS истекает примерно через час). Перейдите непосредственно к запуску стека.

Запустите стек

Убедитесь, что на компьютере запущен docker Desktop (или подсистема Docker).
Создайте образы контейнеров и запустите все три службы (агент, боковая машина и API погоды) в отключенном режиме:
```
docker compose up --build -d
```
Убедитесь, что все контейнеры успешно запущены, запрашивая конечную точку состояния. Ответ сообщает, может ли агент достичь AWS Bedrock:

Bash:
```
curl http://localhost:3001/api/status
```
PowerShell:
```
Invoke-RestMethod http://localhost:3001/api/status
```
Отображается ответ, указывающий bedrock_available: true (или false если вы используете режим Direct без учетных данных AWS).

Это важно

При обновлении .env (например, чтобы обновить учетные данные STS с истекшим сроком действия), docker compose restart не перезагружает переменные среды. Вместо этого используйте docker compose up -d --force-recreate llm-agent-aws.

Отправка запроса через пользовательский интерфейс чата

Откройте http://localhost:3001 в браузере.
Используйте панель заголовков для настройки демонстрации:
- Режим выполнения:Direct (пропустите LLM) или Bedrock (агент LangChain ReAct в Claude).
- Процесс удостоверения:Autonomous (токен только для приложений) или OBO (действует для пользователя, вошедшего в систему).
Если выбрать OBO, нажмите кнопку "Войти" , чтобы пройти проверку подлинности с помощью всплывающего окна MSAL.js.
Введите запрос , например "Погода в Далласе?" и нажмите кнопку "Отправить".
Наблюдайте за панелью трассировки удостоверений справа для пошаговой разбивки каждого обмена токенами и вызова API. На панели показаны карточки JWT с цветом для каждого токена (Tc, T1, TR) с декодируемыми утверждениями.

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

Если что-то не работает должным образом, проверьте следующую таблицу для распространенных проблем и исправлений:

Симптом	Вероятно, причина	Исправить
`/api/status` показывает `bedrock_available: false`	Учетные данные AWS отсутствуют или истекли, или доступ к модели не предоставлен.	Проверьте `docker logs llm-agent-aws`. Обновите учетные данные STS с помощью `aws sso login`. Включите модель в консоли Bedrock.
`ExpiredTokenException` из Бедрока	Срок действия токена сеанса уровня A STS истек.	Вставьте новые учетные данные в `.env`, а затем запустите `docker compose up -d --force-recreate llm-agent-aws`.
`AccessDeniedException` на `InvokeModel`	Субъект IAM не имеет `bedrock:InvokeModel` разрешения или доступ к модели не активирован.	Предоставьте `bedrock:InvokeModel` разрешения на модели и профили вывода ARN.
`ValidationException: invalid model identifier`	Регион не размещает модель или вы использовали только идентификатор модели вместо профиля вывода `us.`.	Используйте идентификатор профиля вывода с префиксом `us.` (например, `us.anthropic.claude-3-haiku-20240307-v1:0`).
Возвращается API погоды `401 Unauthorized`	Сбой проверки соответствия токена арендатору, просроченного секрета или проверки подписи.	Убедитесь, что `TENANT_ID` соответствует клиенту Blueprint. Проверьте журналы сайдкара.
LLM отвечает без вызова средства	Запрос не был четко сформирован или модель не поддерживает вызов инструментов.	Используйте Claude 3 Haiku или более поздней версии. Фраза "Какая погода в <городе>?".
Всплывающее окно входа OBO заблокировано	Блокировщик всплывающего окна браузера.	Разрешить всплывающие окна для `localhost:3001`.
`4xx` с бокового автомобиля во время OBO	`CLIENT_SPA_APP_ID` отсутствует или URI перенаправления для SPA не соответствует.	Повторное выполнение `setup-obo-client-app`. Убедитесь, что `http://localhost:3001` находится в URI перенаправления SPA.

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

docker logs llm-agent-aws          # Agent app: Bedrock calls, tool invocations
docker logs agent-id-sidecar-aws   # Sidecar: token acquisition, credential errors
docker logs weather-api-aws        # Weather API: JWT validation, request handling

Очистите ресурсы

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