Endpunktreferenz: Microsoft Entra SDK für AgentID-HTTP-API

Dieses Dokument enthält vollständige Referenz zu den HTTP-Endpunkten, die vom Microsoft Entra SDK für AgentID verfügbar gemacht werden.

API-Spezifikation

OpenAPI-Spezifikation: Verfügbar bei /openapi/v1.json (Entwicklungsumgebung) und im Repository: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.AgentID.json

Verwenden Sie es zu folgenden Zwecken:

• Generieren von Clientcode
• Überprüfen von Anforderungen
• Ermitteln verfügbarer Endpunkte

Endpunktübersicht

Authentifizierung

Für alle Tokenakquisitions- und Validierungsendpunkte ist ein Bearertoken im Authorization Header erforderlich, es sei denn, explizit als nicht authentifiziert gekennzeichnet:

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

Token werden anhand konfigurierter Microsoft Entra-ID-Einstellungen überprüft (Mandant, Zielgruppe, Aussteller, Bereiche, falls aktiviert).

/Validate

Überprüft das eingehende Bearertoken und gibt seine Ansprüche zurück.

Anfrage

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

Erfolgreiche Antwort (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"
  }
}

Fehlerbeispiele

// 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}

Ruft ein Zugriffstoken für die konfigurierte downstream-API ab und gibt es als Autorisierungsheaderwert zurück. Wenn ein Benutzer bearertoken eingehend bereitgestellt wird, wird OBO (delegiert) verwendet; andernfalls gelten App-Kontextmuster (sofern aktiviert).

Path-Parameter

• serviceName – Name der downstream-API in der Konfiguration

Abfrageparameter

Standardüberschreibungen

Agentidentität

Regeln:

• AgentUsername oder AgentUserId erfordern AgentIdentity (Benutzer-Agent).
• AgentUsername und AgentUserId schließen sich gegenseitig aus.
• AgentIdentity allein = autonomer Agent.
• AgentIdentity + Benutzereingangstoken = delegierter Agent.

Examples

Grundlegende Anforderung:

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...

Antwort

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

PoP/SHR-Antwort:

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

/AuthorizationHeaderUnauthenticated/{serviceName}

Dasselbe Verhalten und dieselben Parameter wie /AuthorizationHeader/{serviceName} ein eingehendes Benutzertoken wird erwartet. Wird ohne Benutzerkontext für app-only oder autonome/Agent-Identitätsakquisition verwendet. Verhindert den Aufwand für die Überprüfung eines Benutzertokens.

Anfrage

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Antwort

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

/DownstreamApi/{serviceName}

Erwirbt ein Zugriffstoken und führt eine HTTP-Anforderung an die downstream-API aus. Gibt Statuscode, Header und Textkörper aus der nachgeschalteten Antwort zurück. Unterstützt Benutzer-OBO-, Nur-App- oder Agent-Identitätsmuster.

Path-Parameter

• serviceName – Konfigurierter nachgeschalteter API-Name.

Zusätzliche Abfrageparameter (zusätzlich zu /AuthorizationHeader Parametern)

Anforderungstextweiterleitung

Der Text wird unverändert durchlaufen:

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" } 
}

Antwort

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

Fehlerspiegelung /AuthorizationHeader und nachgeschaltete API-Fehlerstatuscodes.

/DownstreamApiUnauthenticated/{serviceName}

Identisch mit /DownstreamApi/{serviceName} dem, aber kein eingehendes Benutzertoken wird überprüft. Wird für Nur-App- oder autonome Agent-Vorgänge verwendet.

/healthz

Endpunkt für grundlegende Integritätssonden.

Antwort

Gesund (200):

HTTP/1.1 200 OK

Ungesund (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Gibt die OpenAPI 3.0-Spezifikation zurück (nur Entwicklungsumgebung). Verwendung:

• Generieren von Clientcode
• Überprüfen von Anforderungen
• Ermitteln von Endpunkten

Häufige Fehlermuster

Ungültige Anforderung (400)

Fehlender Dienstname:

// 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" }

MSAL-Fehlerbeispiel

{ "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": "..." } }

Vollständige Außerkraftsetzungsreferenz

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

Beispiele für Außerkraftsetzung

Außerkraftsetzen von Bereichen:

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

Ratenbegrenzung

Das Microsoft Entra SDK für AgentID selbst erzwingt keine Ratenbeschränkungen. Effektive Grenzwerte stammen von:

1. Einschränkung des Microsoft Entra-ID-Tokendiensts (sollte nicht als SDK-Cachetoken geschehen)
2. Downstream-API-Grenzwerte
3. Effizienz des Tokencaches (reduziert das Kaufvolumen)

Bewährte Methoden

1. Bevorzugen Sie die Konfiguration gegenüber Ad-hoc-Außerkraftsetzungen.
2. Halten Sie Dienstnamen statisch und deklarativ.
3. Implementieren Sie Wiederholungsrichtlinien für vorübergehende Fehler (HTTP 500/503).
4. Überprüfen Sie die Agentparameter vor dem Aufrufen.
5. Protokollkorrelations-IDs für die Ablaufverfolgung über Dienste hinweg.
6. Überwachen der Tokenerwerbslatenz und Fehlerraten.
7. Verwenden Sie Integritätssonden in Orchestrierungsplattformen.

Siehe auch

• Konfigurationsreferenz
• Agentidentitäten
• Szenarien: Überprüfen des Autorisierungsheaders
• Szenarien: Abrufen des Autorisierungsheaders
• Szenarien: Aufrufen der downstream-API