Informazioni di riferimento sugli endpoint: API HTTP Microsoft Entra ID Auth SDK (sidecar)

Questo documento fornisce informazioni di riferimento complete per gli endpoint HTTP esposti dal Microsoft Entra ID Auth SDK (sidecar).

Specifica dell'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.Sidecar.json

Usarlo per:

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

Panoramica dell'endpoint

Authentication

Bearer rimane lo schema di autenticazione predefinito per gli endpoint autenticati. L'endpoint /Validate accetta anche lo PoP schema per le credenziali della richiesta HTTP firmata (SHR) solo app. Altri endpoint autenticati richiedono Bearer a meno che non sia contrassegnato in modo esplicito come non autenticato:

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

I token vengono convalidati in base alle impostazioni di Microsoft Entra ID configurate, tra cui tenant, gruppo di destinatari, autorità emittente e ambiti quando abilitati. Per le richieste PoP, il sidecar convalida la firma SHR e il token di accesso incorporato sullo stesso tenant, gruppo di destinatari, autorità emittente e configurazione della chiave di firma.

/Validate

Convalida un token di connessione in ingresso o credenziali poP SHR solo app e restituisce il token convalidato e le relative attestazioni.

Richiesta

Richiesta di connessione:

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

Richiesta poP:

GET /Validate HTTP/1.1
Authorization: PoP <signed-http-request>
original-method: GET
original-uri: https://api.contoso.com/data

Per PoP original-method e original-uri sono obbligatori. Devono contenere il metodo e l'URI assoluto della richiesta originale su cui è stata firmata la credenziale SHR. Il sidecar usa questi valori per convalidare l'associazione di richieste; la /Validate richiesta stessa non è la richiesta di risorsa firmata.

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

Il protocol valore è Bearer per una richiesta Bearer e PoP per una richiesta PoP. Per PoP, token contiene il token di accesso convalidato incorporato nella richiesta HTTP firmata. Le attestazioni restituite dipendono dalla versione del token di accesso e dalla configurazione del tenant.

Esempi di errore

Le credenziali di autorizzazione mancanti vengono rifiutate prima dell'esecuzione dell'endpoint:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

Un token di connessione non valido restituisce una richiesta di connessione:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

Una richiesta PoP non riuscita include la richiesta seguente. Poiché /Validate accetta entrambi gli schemi di autenticazione, la risposta può contenere anche la richiesta di connessione.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: PoP error="invalid_token"

/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 di 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 del tasso

Il Microsoft Entra ID Auth SDK (sidecar) stesso non impone limiti di velocità. I limiti effettivi provengono da:

1. Microsoft Entra ID la limitazione del servizio token (non deve essere eseguita come token della cache dell'SDK)
2. Limiti dell'API downstream
3. Efficienza della cache dei token (riduce il volume di acquisizione)

Procedure consigliate

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.

Contenuti correlati

• Informazioni di riferimento sulla configurazione
• Identità agente
• Convalida dell'intestazione di autorizzazione
• Chiamare l'API Downstream