Informazioni di riferimento sugli endpoint: Microsoft Entra SDK per l'API HTTP AgentID

Questo documento fornisce informazioni di riferimento complete per gli endpoint HTTP esposti da Microsoft Entra SDK per AgentID.

Specifica API

Specifica OpenAPI: disponibile in /openapi/v1.json (ambiente di sviluppo) e nel repository: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.AgentID.json

Usarlo per:

• Generare codice client
• Convalidare le richieste
• Individuare gli endpoint disponibili

Panoramica dell'endpoint

Authentication

Tutti gli endpoint di acquisizione e convalida dei token richiedono un token di connessione nell'intestazione Authorization , a meno che non siano contrassegnati in modo esplicito come non autenticati:

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

I token vengono convalidati in base alle impostazioni dell'ID Entra microsoft configurate (tenant, gruppo di destinatari, autorità emittente, ambiti se abilitati).

/Validate

Convalida il token di connessione in ingresso e ne restituisce le attestazioni.

Richiesta

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

Risposta riuscita (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"
  }
}

Esempi di errore

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

Acquisisce un token di accesso per l'API downstream configurata e lo restituisce come valore di intestazione di autorizzazione. Se viene fornito un token di connessione utente in ingresso, viene usato OBO (delegato); in caso contrario, si applicano i modelli di contesto dell'app (se abilitati).

Parametro Path

• serviceName : nome dell'API downstream nella configurazione

Parametri della query

Sostituzioni standard

Identità agente

Norme:

• AgentUsername o AgentUserId richiedere AgentIdentity (agente utente).
• AgentUsername e AgentUserId si escludono a vicenda.
• AgentIdentity alone = agente autonomo.
• AgentIdentity + token in ingresso utente = agente delegato.

Esempi

Richiesta di base:

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

Risposta

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

Risposta PoP/SHR:

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

/AuthorizationHeaderUnauthenticated/{serviceName}

È previsto lo stesso comportamento e gli stessi parametri, /AuthorizationHeader/{serviceName} ma non è previsto alcun token utente in ingresso. Usato per l'acquisizione di identità solo app o autonome/agente senza un contesto utente. Evita il sovraccarico di convalida di un token utente.

Richiesta

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Risposta

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

/DownstreamApi/{serviceName}

Acquisisce un token di accesso ed esegue una richiesta HTTP all'API downstream. Restituisce codice di stato, intestazioni e corpo dalla risposta downstream. Supporta i modelli di identità dell'utente OBO, solo app o agente.

Parametro Path

• serviceName : nome dell'API downstream configurato.

Parametri di query aggiuntivi (oltre ai /AuthorizationHeader parametri)

Inoltro del corpo della richiesta

Il corpo viene passato attraverso non modificato:

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

Risposta

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

Errori mirror /AuthorizationHeader e codici di stato di errore dell'API downstream.

/DownstreamApiUnauthenticated/{serviceName}

Uguale a /DownstreamApi/{serviceName} ma non viene convalidato alcun token utente in ingresso. Usare per le operazioni dell'agente autonomo o solo app.

/healthz

Endpoint probe di integrità di base.

Risposta

Integro (200):

HTTP/1.1 200 OK

Non integro (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Restituisce la specifica OpenAPI 3.0 (solo ambiente di sviluppo). Usare per:

• Generare codice client
• Convalidare le richieste
• Individuare gli endpoint

Modelli di errore comuni

Richiesta non valida (400)

Nome del servizio mancante:

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

Esempio di errore 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": "..." } }

Informazioni di riferimento complete sull'override

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

Esempi di override

Eseguire l'override degli ambiti:

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

Limitazione della velocità

Microsoft Entra SDK per AgentID non impone limiti di velocità. I limiti effettivi provengono da:

1. Limitazione del servizio token ID Microsoft Entra (non dovrebbe verificarsi come token della cache dell'SDK)
2. Limiti dell'API downstream
3. Efficienza della cache dei token (riduce il volume di acquisizione)

Migliori pratiche

1. Preferisce la configurazione rispetto alle sostituzioni ad hoc.
2. Mantenere i nomi dei servizi statici e dichiarativi.
3. Implementare criteri di ripetizione dei tentativi per gli errori temporanei (HTTP 500/503).
4. Convalidare i parametri dell'agente prima di chiamare.
5. ID di correlazione dei log per la traccia tra i servizi.
6. Monitorare la latenza di acquisizione dei token e le percentuali di errore.
7. Usare i probe di integrità nelle piattaforme di orchestrazione.

Vedere anche

• Informazioni di riferimento sulla configurazione
• Identità agente
• Scenari: Convalidare l'intestazione dell'autorizzazione
• Scenari: ottenere l'intestazione dell'autorizzazione
• Scenari: Chiamare l'API Downstream