Referens för slutpunkter: http-API:et Microsoft Entra ID Auth SDK (sidovagn)

Det här dokumentet innehåller fullständig referens för DE HTTP-slutpunkter som exponeras av Microsoft Entra ID Auth SDK (sidovagn).

API-specifikation

OpenAPI-specifikation: Finns på /openapi/v1.json (utvecklingsmiljö) och på lagringsplatsen: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Använd den för att:

  • Generera klientkod
  • Verifiera begäranden
  • Identifiera tillgängliga slutpunkter

Översikt över slutpunkt

Endpoint Metoder Avsikt Autentisering krävs
/Validate GET Verifiera en inkommande ägartoken eller poP-signerad HTTP-begäran och returnera anspråk Yes
/AuthorizationHeader/{serviceName} GET Verifiera inkommande token (om det finns) och hämta ett auktoriseringshuvud för ett underordnat API Yes
/AuthorizationHeaderUnauthenticated/{serviceName} GET Hämta ett auktoriseringshuvud (app- eller agentidentitet) utan inkommande användartoken Yes
/DownstreamApi/{serviceName} GET, POST, PUT, PATCH, DELETE Verifiera inkommande token (om det finns) och anropa nedströms-API:et med automatiskt tokenförvärv Yes
/DownstreamApiUnauthenticated/{serviceName} GET, POST, PUT, PATCH, DELETE Anropa underordnat API (endast app- eller agentidentitet) Yes
/healthz GET Hälsoavsökning (liveness/readiness) Nej
/openapi/v1.json GET OpenAPI 3.0-dokument Nej (endast dev)

Authentication

Bearer förblir standardautentiseringsschemat för autentiserade slutpunkter. Slutpunkten /Validate accepterar PoP också schemat för autentiseringsuppgifter för endast signerad HTTP-begäran (SHR). Andra autentiserade slutpunkter kräver bearer om inte uttryckligen markerad som oautentiserad:

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

Token verifieras mot konfigurerade Microsoft Entra ID inställningar, inklusive klientorganisation, målgrupp, utfärdare och omfång när de är aktiverade. För PoP-begäranden validerar sidovagnen SHR-signaturen och dess inbäddade åtkomsttoken mot samma klientorganisation, målgrupp, utfärdare och signeringsnyckelkonfiguration.

/Validate

Validerar en inkommande ägartoken eller SHR PoP-autentiseringsuppgifter för endast appar och returnerar den verifierade token och dess anspråk.

Begäran

Ägarförfrågan:

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

PoP-begäran:

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

För PoP original-method och original-uri krävs. De måste innehålla metoden och den absoluta URI:n för den ursprungliga begäran som SHR-autentiseringsuppgifterna signerades över. Sidovagnen använder dessa värden för att validera bindning av begäranden. själva /Validate begäran är inte den signerade resursbegäran.

Lyckat svar (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"
  }
}

Värdet protocol är Bearer för en bearer-begäran och PoP för en PoP-begäran. För PoP token innehåller den verifierade åtkomsttoken inbäddad i den signerade HTTP-begäran. De returnerade anspråken beror på åtkomsttokenversionen och klientkonfigurationen.

Important

Inkommande PoP-validering stöder åtkomsttoken för endast klientautentiseringsuppgifter. Det stöder inte delegerade eller användartoken, OBO- eller aktörstokenflöden, mTLS PoP eller PFT/CDT-over-PoP. AzureAd__Scopes tillämpas inte på poP-begäranden endast för appar eftersom dessa token inte innehåller något scp anspråk. Ditt program måste auktorisera den returnerade appidentiteten med hjälp av dess roller, programbehörigheter eller andra betrodda anspråk.

Felexempel

Saknade autentiseringsuppgifter för auktorisering avvisas innan slutpunkten körs:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

En ogiltig ägartoken returnerar en bearer-utmaning:

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

En misslyckad PoP-begäran innehåller följande utmaning. Eftersom /Validate accepterar båda autentiseringsschemana kan svaret även innehålla bearer-utmaningen.

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

/AuthorizationHeader/{serviceName}

Hämtar en åtkomsttoken för det konfigurerade underordnade API:et och returnerar den som ett auktoriseringshuvudvärde. Om en användarbäraretoken tillhandahålls inkommande används OBO (delegerad). annars gäller appkontextmönster (om de är aktiverade).

Sökvägsparameter

  • serviceName – Namnet på det underordnade API:et i konfigurationen

Frågeparametrar

Standard åsidosättningar

Parameter Typ Description Example
optionsOverride.Scopes string[] Åsidosätta konfigurerade omfång (repeterbara) ?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read
optionsOverride.RequestAppToken booleskt Tvinga endast apptoken (hoppa över OBO) ?optionsOverride.RequestAppToken=true
optionsOverride.AcquireTokenOptions.Tenant snöre Åsidosätta klientorganisations-ID ?optionsOverride.AcquireTokenOptions.Tenant=tenant-guid
optionsOverride.AcquireTokenOptions.PopPublicKey snöre Aktivera PoP/SHR (offentlig base64-nyckel) ?optionsOverride.AcquireTokenOptions.PopPublicKey=base64key
optionsOverride.AcquireTokenOptions.PopClaims snöre Ytterligare PoP-anspråk (JSON) ?optionsOverride.AcquireTokenOptions.PopClaims={"nonce":"abc"}

Agentidentitet

Parameter Typ Description Example
AgentIdentity snöre Agentapps-ID (klient) ?AgentIdentity=11111111-2222-3333-4444-555555555555
AgentUsername snöre Användarens huvudnamn (delegerad agent) ?AgentIdentity=<id>&AgentUsername=user@contoso.com
AgentUserId snöre Användarobjekt-ID (delegerad agent) ?AgentIdentity=<id>&AgentUserId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Reglemente:

  • AgentUsername eller AgentUserId kräv AgentIdentity (användaragent).
  • AgentUsername och AgentUserId är ömsesidigt uteslutande.
  • AgentIdentity alone = autonom agent.
  • AgentIdentity + användarens inkommande token = delegerad agent.

Examples

Grundläggande begäran:

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

Svar

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

PoP/SHR-svar:

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

/AuthorizationHeaderUnauthenticated/{serviceName}

Samma beteende och parametrar som /AuthorizationHeader/{serviceName} men ingen inkommande användartoken förväntas. Används endast för app- eller autonomt/agentidentitetsförvärv utan användarkontext. Undviker kostnaden för att verifiera en användartoken.

Begäran

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Svar

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

/DownstreamApi/{serviceName}

Hämtar en åtkomsttoken och utför en HTTP-begäran till det underordnade API:et. Returnerar statuskod, rubriker och brödtext från nedströmssvaret. Stöder identitetsmönster för användar-OBO, endast app eller agent.

Sökvägsparameter

  • serviceName – Konfigurerat underordnat API-namn.

Ytterligare frågeparametrar (utöver /AuthorizationHeader parametrar)

Parameter Typ Description Example
optionsOverride.HttpMethod snöre Åsidosätt HTTP-metod ?optionsOverride.HttpMethod=POST
optionsOverride.RelativePath snöre Lägg till relativ sökväg till konfigurerad BaseUrl ?optionsOverride.RelativePath=me/messages
optionsOverride.CustomHeader.<Name> snöre Lägg till anpassade sidhuvuden ?optionsOverride.CustomHeader.X-Custom=value

Vidarebefordran av begärandetext

Brödtexten skickas oförändrad:

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

Svar

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

Fel speglar /AuthorizationHeader plus api-felstatuskoder under underordnad api.

/DownstreamApiUnauthenticated/{serviceName}

Samma som /DownstreamApi/{serviceName} men ingen inkommande användartoken verifieras. Används endast för app- eller autonoma agentåtgärder.

/healthz

Grundläggande slutpunkt för hälsoavsökning.

Svar

Felfri (200):

HTTP/1.1 200 OK

Inte felfri (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Returnerar OpenAPI 3.0-specifikation (endast utvecklingsmiljö). Använd för att:

  • Generera klientkod
  • Verifiera begäranden
  • Identifiera slutpunkter

Vanliga felmönster

Felaktig begäran (400)

Tjänstnamn saknas:

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

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

Fullständig åsidosättningsreferens

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

Exempel på åsidosättning

Åsidosätt omfång:

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

Begränsning av hastighet

Själva Microsoft Entra ID Auth SDK (sidovagn) tillämpar inte hastighetsgränser. Gällande gränser kommer från:

  1. Microsoft Entra ID begränsning av tokentjänsten (bör inte ske som SDK-cachetoken)
  2. Api-gränser för underordnade
  3. Tokencacheeffektivitet (minskar anskaffningsvolymen)

Metodtips

  1. Föredrar konfiguration framför ad hoc-åsidosättningar.
  2. Behåll tjänstnamn statiska och deklarativa.
  3. Implementera återförsöksprinciper för tillfälliga fel (HTTP 500/503).
  4. Verifiera agentparametrar innan du anropar.
  5. Logga korrelations-ID:er för spårning mellan tjänster.
  6. Övervaka svarstid och felfrekvens för tokenförvärv.
  7. Använd hälsoavsökningar på orkestreringsplattformar.