Logo
AWS Bedrock AgentCore MCP agenci AI

AWS Bedrock AgentCore Gateway MCP 401: token OAuth, claim audience i credential provider

Napraw błąd 401/403 na AgentCore Gateway przy wywołaniach narzędzi MCP: sprawdź claim audience w tokenie wejściowym, sam token oraz wychodzący credential provider OAuth2.

Jerzy Kopaczewski ·
Twój agent nie może dosięgnąć swoich narzędzi: wywołania przez Amazon Bedrock AgentCore Gateway do serwera MCP wracają z 401 Unauthorized (czasem 403). Prawie zawsze to niezgodność uwierzytelniania, a nie zepsute narzędzie. Ten runbook rozdziela dwie strony, które mogą zawieść: token wejściowy przedstawiany przez wywołującego oraz dane uwierzytelniające, których Gateway używa, by dotrzeć do celu.

Ten runbook dotyczy błędów uwierzytelniania AgentCore Gateway przy wywołaniach narzędzi MCP. Szerszy obraz nadzoru znajdziesz w artykule AWS Loom i nadzór nad agentami AI. W sprawie projektu tożsamości agentów i least privilege umów konsultację.

Objawy

Wywołanie narzędzia zawodzi na Gateway, zanim docelowy serwer MCP wykona jakąkolwiek pracę.

# Brak tokenu lub nieprawidłowy token wejściowy
HTTP 401 Unauthorized

# Niektórzy klienci widzą 403 zamiast 401 dla tej samej klasy błędu
HTTP 403 Forbidden

# W logach agenta / klienta MCP
Failed to list tools: server returned 401

Widoczny wpływ:

  • Agent nie widzi żadnych narzędzi albo każde wywołanie narzędzia zawodzi natychmiast
  • Błąd jest natychmiastowy (uwierzytelnianie odrzuca, zanim ruszy logika narzędzia), a nie timeout
  • Działa z ręcznie wygenerowanym tokenem w teście, ale zawodzi z wdrożonego agenta, albo odwrotnie

Przyczyna

AgentCore Gateway działa zgodnie ze standardem MCP i odrzuca każde żądanie bez ważnego tokenu. Są dwa odrębne skoki uwierzytelniania i winowajcą może być każdy z nich:

  1. Wejściowy (wywołujący do Gateway). Gateway waliduje token JWT przedstawiony przez wywołującego. Najczęstszy błąd to sytuacja, w której claim aud (audience) lub client_id w tokenie nie pasuje do wpisu audience skonfigurowanego w autoryzatorze wejściowym Gateway. Brakujący, wygasły lub token o złym wystawcy zawodzi tak samo.
  2. Wychodzący (Gateway do celu przez credential provider). Dla celu, który sam jest chroniony przez OAuth, Gateway używa credential provider OAuth2 z AgentCore Identity, który potrzebuje ważnego client_id i client_secret wydanych przez dostawcę tożsamości (IdP) celu. Źle skonfigurowany lub nieuprawniony credential provider blokuje dalsze wywołanie.

Dwa fakty warte poznania przed debugowaniem:

  • AgentCore Gateway obsługuje tylko http_streaming, nie SSE. Klient MCP domyślnie używający transportu SSE może objawić to jako błąd połączenia lub uwierzytelniania.
  • Niektórzy klienci dostają 403 zamiast 401 dla nieuprawnionych żądań, więc obsłuż oba.

Naprawa

Krok 1: Potwierdź, że Gateway jest osiągalny i odrzuca na uwierzytelnianiu

401 bez tokenu dowodzi, że Gateway działa i wymusza uwierzytelnianie (to zachowanie oczekiwane, nie awaria).

# Bez tokenu: oczekiwane 401 (lub 403). To potwierdza wymuszanie auth, nie awarię.
curl -s -o /dev/null -w "%{http_code}\n" https://your-gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp

Krok 2: Sprawdź claimy tokenu wejściowego

Zdekoduj token JWT, który wysyła wywołujący, i sprawdź claimy aud oraz iss względem tego, czego oczekuje Gateway.

# Zdekoduj payload JWT (bez weryfikacji, tylko odczyt claimów)
echo "$ACCESS_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool

Claim aud (lub client_id) musi dokładnie pasować do jednego z wpisów audience skonfigurowanych w autoryzatorze wejściowym Gateway. Niezgodność tutaj to najczęstsza przyczyna błędu 401.

Krok 3: Zweryfikuj konfigurację autoryzatora wejściowego Gateway

# Odczytaj konfigurację autoryzatora bramy
aws bedrock-agentcore-control get-gateway \
  --gateway-identifier your-gateway-id \
  --region us-west-2 \
  --query 'authorizerConfiguration'

Potwierdź, że dozwolony audience i adres discovery wskazują na tego samego dostawcę tożsamości, który wystawił token z kroku 2. Jeśli używasz Amazon Cognito, pamiętaj, że nie obsługuje on Dynamic Client Registration, więc klientom MCP polegającym na DCR trzeba przekazać dane klienta ręcznie.

Krok 4: Sprawdź wychodzący credential provider (tylko gdy cel jest chroniony przez OAuth)

Jeśli token wejściowy jest poprawny, ale dalsze wywołanie do celu nadal zawodzi, podejrzanym jest wychodzący credential provider.

# Wypisz credential providery i potwierdź, że istnieje ten, którego używa cel
aws bedrock-agentcore-control list-oauth2-credential-providers \
  --region us-west-2

Potwierdź, że provider ma ważny client_id i client_secret wydane przez dostawcę tożsamości docelowego serwera MCP, oraz że tryb delegacji (machine-to-machine lub on-behalf-of) odpowiada temu, jak agent wywołuje narzędzie.

Krok 5: Potwierdź, że klient używa http_streaming, a nie SSE

Jeśli uwierzytelnianie jest poprawne, ale klient MCP nadal nie może się połączyć, sprawdź jego transport. AgentCore Gateway obsługuje tylko http_streaming. Skieruj klienta na endpoint /mcp przez strumieniowe HTTP, a nie SSE.

Weryfikacja

Z poprawnie zakresowanym tokenem wypisanie narzędzi przez Gateway powinno zakończyć się sukcesem.

# Wywołaj endpoint MCP z ważnym tokenem: oczekiwane 200 i lista narzędzi
curl -s https://your-gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  -w "\nHTTP %{http_code}\n"

Oczekiwane: HTTP 200 i treść JSON z listą zarejestrowanych narzędzi, bez 401 ani 403.

Powiązane