Dokumentacja punktów końcowych: Microsoft Entra SDK for AgentID HTTP API

Ten dokument zawiera pełne informacje dotyczące punktów końcowych HTTP udostępnianych przez zestaw Microsoft Entra SDK dla identyfikatora AgentID.

Specyfikacja interfejsu API

Specyfikacja interfejsu OpenAPI: dostępna w lokalizacji /openapi/v1.json (środowisko programistyczne) i w repozytorium: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.AgentID.json

Jego zastosowania to:

• Generowanie kodu klienta
• Weryfikowanie żądań
• Odnajdywanie dostępnych punktów końcowych

Omówienie punktu końcowego

Authentication

Wszystkie punkty końcowe pozyskiwania i walidacji tokenu wymagają tokenu elementu nośnego w nagłówku Authorization , chyba że jawnie oznaczone jako nieuwierzytelnione:

GET /AuthorizationHeader/Graph
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Tokeny są weryfikowane względem skonfigurowanych ustawień identyfikatora entra firmy Microsoft (dzierżawa, odbiorcy, wystawca, zakresy, jeśli są włączone).

/Validate

Weryfikuje token elementu nośnego dla ruchu przychodzącego i zwraca jego oświadczenia.

Żądanie

GET /Validate HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Pomyślna odpowiedź (200)

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "claims": {
    "aud": "api://your-api-id",
    "iss": "https://sts.windows.net/tenant-id/",
    "iat": 1234567890,
    "nbf": 1234567890,
    "exp": 1234571490,
    "acr": "1",
    "appid": "client-id",
    "appidacr": "1",
    "idp": "https://sts.windows.net/tenant-id/",
    "oid": "user-object-id",
    "tid": "tenant-id",
    "scp": "access_as_user",
    "sub": "subject",
    "ver": "1.0"
  }
}

Przykłady błędów

// 400 Bad Request - No token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "No token found"
}

// 401 Unauthorized - Invalid token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Unauthorized",
  "status": 401
}

/AuthorizationHeader/{serviceName}

Uzyskuje token dostępu dla skonfigurowanego podrzędnego interfejsu API i zwraca go jako wartość nagłówka autoryzacji. Jeśli token elementu nośnego użytkownika jest dostarczany dla ruchu przychodzącego, jest używany protokół OBO (delegowany); w przeciwnym razie mają zastosowanie wzorce kontekstowe aplikacji (jeśli włączono).

Parametr ścieżki

• serviceName — Nazwa podrzędnego interfejsu API w konfiguracji

Parametry zapytań

Przesłonięcia standardowe

Tożsamość agenta

Zasady:

• AgentUsername lub AgentUserId wymagaj AgentIdentity (agent użytkownika).
• AgentUsername i AgentUserId wzajemnie się wykluczają.
• AgentIdentity alone = autonomiczny agent.
• AgentIdentity + token przychodzący użytkownika = agent delegowany.

Przykłady

Żądanie podstawowe:

GET /AuthorizationHeader/Graph HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Odpowiedź

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Odpowiedź poP/SHR:

{
  "authorizationHeader": "PoP eyJ0eXAiOiJhdCtqd3QiLCJhbGc..."
}

/AuthorizationHeaderUnauthenticated/{serviceName}

Takie samo zachowanie i parametry, jak /AuthorizationHeader/{serviceName} i żadne tokeny użytkownika przychodzącego nie są oczekiwane. Służy do uzyskiwania tożsamości tylko aplikacji lub autonomicznej/agenta bez kontekstu użytkownika. Pozwala uniknąć narzutów związanych z walidacją tokenu użytkownika.

Żądanie

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Odpowiedź

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

/DownstreamApi/{serviceName}

Uzyskuje token dostępu i wykonuje żądanie HTTP do podrzędnego interfejsu API. Zwraca kod stanu, nagłówki i treść z odpowiedzi podrzędnej. Obsługuje wzorce tożsamości użytkowników OBO, tylko dla aplikacji lub agenta.

Parametr ścieżki

• serviceName — Skonfigurowano nazwę podrzędnego interfejsu API.

Dodatkowe parametry zapytania (oprócz /AuthorizationHeader parametrów)

Przekazywanie treści żądania

Treść jest przekazywana bez zmian:

POST /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

{ 
  "subject": "Hello", 
   "body": { "contentType": "Text", "content": "Hello world" } 
}

Odpowiedź

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "content": "{\"@odata.context\":\"...\",\"displayName\":\"...\"}"
}

Błędy dublowania /AuthorizationHeader oraz kody stanu błędów podrzędnego interfejsu API.

/DownstreamApiUnauthenticated/{serviceName}

Taki sam jak /DownstreamApi/{serviceName} , ale nie jest weryfikowany żaden token użytkownika przychodzącego. Służy do obsługi operacji agenta autonomicznego lub tylko dla aplikacji.

/healthz

Podstawowy punkt końcowy sondy kondycji.

Odpowiedź

W dobrej kondycji (200):

HTTP/1.1 200 OK

Zła kondycja (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Zwraca specyfikację interfejsu OpenAPI 3.0 (tylko środowisko programistyczne). Użyj polecenia , aby:

• Generowanie kodu klienta
• Weryfikowanie żądań
• Odnajdywanie punktów końcowych

Typowe wzorce błędów

Nieprawidłowe żądanie (400)

Brak nazwy usługi:

// 400 Bad Request - Missing service name
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "Service name is required" }

// 400 Bad Request - Invalid agent combination
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "AgentUsername and AgentUserId are mutually exclusive" }

// 401 Unauthorized - Invalid token
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Unauthorized", "status": 401 }

// 403 Forbidden - Missing scope
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden", "status": 403, "detail": "The scope 'access_as_user' is required" }

// 404 Not Found - Service not configured
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "Downstream API 'UnknownService' not configured" }

// 500 Internal Server Error - Token acquisition failure
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "Failed to acquire token for downstream API" }

Przykład błędu biblioteki MSAL

{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "MSAL.NetCore.invalid_grant: AADSTS50076: Due to a configuration change ...", "extensions": { "errorCode": "invalid_grant", "correlationId": "..." } }

Kompletna dokumentacja zastąpienia

optionsOverride.Scopes=<scope>     # Repeatable
optionsOverride.RequestAppToken=<true|false>
optionsOverride.BaseUrl=<url>
optionsOverride.RelativePath=<path>
optionsOverride.HttpMethod=<method>
optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>
optionsOverride.AcquireTokenOptions.AuthenticationScheme=<scheme>
optionsOverride.AcquireTokenOptions.CorrelationId=<guid>
optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>
optionsOverride.AcquireTokenOptions.PopClaims=<json>
optionsOverride.CustomHeader.<Name>=<value>

AgentIdentity=<agent-client-id>
AgentUsername=<user-upn>            # Requires AgentIdentity
AgentUserId=<user-object-id>        # Requires AgentIdentity

Przykłady przesłonięcia

Zastąpić zakresy:

GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Ograniczanie szybkości

Zestaw Microsoft Entra SDK dla identyfikatora AgentID nie nakłada limitów szybkości. Obowiązujące limity pochodzą z:

1. Ograniczanie przepływności usługi tokenu identyfikatora entra firmy Microsoft (nie powinno się zdarzyć, ponieważ token pamięci podręcznej zestawu SDK)
2. Limity interfejsu API podrzędnego
3. Wydajność pamięci podręcznej tokenu (zmniejsza wolumin pozyskiwania)

Najlepsze praktyki

1. Preferuj konfigurację za pośrednictwem przesłonięć ad hoc.
2. Zachowaj nazwy usług statyczne i deklaratywne.
3. Zaimplementuj zasady ponawiania prób dla błędów przejściowych (HTTP 500/503).
4. Przed wywołaniem sprawdź poprawność parametrów agenta.
5. Identyfikatory korelacji dzienników na potrzeby śledzenia między usługami.
6. Monitorowanie opóźnień pozyskiwania tokenu i współczynników błędów.
7. Użyj sond kondycji na platformach aranżacji.

Zobacz też

• Dokumentacja konfiguracji
• Tożsamości agenta
• Scenariusze: weryfikowanie nagłówka autoryzacji
• Scenariusze: uzyskiwanie nagłówka autoryzacji
• Scenariusze: wywoływanie interfejsu API podrzędnego