Referenční informace ke koncovým bodům: rozhraní HTTP API Microsoft Entra ID Auth SDK (sajdkárna)

Tento dokument obsahuje kompletní referenční informace o koncových bodech HTTP vystavených sadou MICROSOFT ENTRA ID Auth SDK (sidecar).

Specifikace rozhraní API

specifikaceOpenAPI: K dispozici na adrese /openapi/v1.json (vývojové prostředí) a v úložišti: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Použijte ji k následujícím akcím:

Generování klientského kódu
Ověření požadavků
Zjištění dostupných koncových bodů

Přehled koncového bodu

Endpoint	Metody	Účel	Požadováno ověření
`/Validate`	získej	Ověření příchozího nosné tokenu a vrácení deklarací identity	Ano
`/AuthorizationHeader/{serviceName}`	získej	Ověření příchozího tokenu (pokud je k dispozici) a získání autorizační hlavičky pro podřízené rozhraní API	Ano
`/AuthorizationHeaderUnauthenticated/{serviceName}`	získej	Získání autorizační hlavičky (identita aplikace nebo agenta) bez příchozího tokenu uživatele	Ano
`/DownstreamApi/{serviceName}`	GET, POST, PUT, PATCH, DELETE	Ověření příchozího tokenu (pokud je k dispozici) a volání podřízené rozhraní API s automatickým získáním tokenu	Ano
`/DownstreamApiUnauthenticated/{serviceName}`	GET, POST, PUT, PATCH, DELETE	Volání podřízené rozhraní API (pouze identita aplikace nebo agenta)	Ano
`/healthz`	získej	Sonda stavu (živá/připravenost)	Ne
`/openapi/v1.json`	získej	Dokument OpenAPI 3.0	Ne (jenom vývoj)

Autentizace

Všechny koncové body získání a ověření tokenu vyžadují nosný token v Authorization hlavičce, pokud explicitně neoznačíte neověřené:

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

Tokeny se ověřují proti nakonfigurovaným nastavením Microsoft Entra ID (tenant, cílová skupina, vystavitel, obory, pokud jsou povolené).

`/Validate`

Ověří příchozí nosný token a vrátí jeho deklarace identity.

Žádost

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

Úspěšná odpověď (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"
  }
}

Příklady chyb

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

Získá přístupový token pro nakonfigurované podřízené rozhraní API a vrátí ho jako hodnotu autorizační hlavičky. Pokud je nosný token uživatele poskytnutý jako příchozí, použije se OBO (delegovaný). v opačném případě se použijí vzory kontextu aplikace (pokud jsou povolené).

Parametr cesty

serviceName – Název podřízeného rozhraní API v konfiguraci

Parametry dotazu

Standardní přepsání

Parameter	Typ	Description	Example
`optionsOverride.Scopes`	řetězec[]	Přepsání nakonfigurovaných oborů (opakovatelné)	`?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read`
`optionsOverride.RequestAppToken`	Boolean	Vynucení tokenu jen pro aplikaci (přeskočení OBO)	`?optionsOverride.RequestAppToken=true`
`optionsOverride.AcquireTokenOptions.Tenant`	řetězec	Přepsání ID tenanta	`?optionsOverride.AcquireTokenOptions.Tenant=tenant-guid`
`optionsOverride.AcquireTokenOptions.PopPublicKey`	řetězec	Povolení poP/SHR (veřejný klíč base64)	`?optionsOverride.AcquireTokenOptions.PopPublicKey=base64key`
`optionsOverride.AcquireTokenOptions.PopClaims`	řetězec	Další deklarace identity PoP (JSON)	`?optionsOverride.AcquireTokenOptions.PopClaims={"nonce":"abc"}`

Identita agenta

Parameter	Typ	Description	Example
`AgentIdentity`	řetězec	ID aplikace agenta (klienta)	`?AgentIdentity=11111111-2222-3333-4444-555555555555`
`AgentUsername`	řetězec	Hlavní název uživatele (delegovaný agent)	`?AgentIdentity=<id>&AgentUsername=user@contoso.com`
`AgentUserId`	řetězec	ID objektu uživatele (delegovaný agent)	`?AgentIdentity=<id>&AgentUserId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`

Pravidla:

AgentUsername nebo AgentUserId vyžadovat AgentIdentity (uživatelský agent).
AgentUsername a AgentUserId vzájemně se vylučují.
AgentIdentity sám = autonomní agent.
AgentIdentity + příchozí token uživatele = delegovaný agent.

Examples

Základní požadavek:

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

Odezva

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

Odpověď PoP/SHR:

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

`/AuthorizationHeaderUnauthenticated/{serviceName}`

Stejné chování a parametry jako /AuthorizationHeader/{serviceName} u příchozího tokenu uživatele se očekává. Používá se pouze pro získání identity jen pro aplikace nebo autonomního agenta bez kontextu uživatele. Vyhne se režii při ověřování tokenu uživatele.

Žádost

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Odezva

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

`/DownstreamApi/{serviceName}`

Získá přístupový token a provede požadavek HTTP na podřízené rozhraní API. Vrátí stavový kód, hlavičky a text z podřízené odpovědi. Podporuje vzory identity uživatele OBO, jen pro aplikace nebo agenta.

Parametr cesty

serviceName – Nakonfigurovaný název podřízeného rozhraní API.

Další parametry dotazu (kromě `/AuthorizationHeader` parametrů)

Parameter	Typ	Description	Example
`optionsOverride.HttpMethod`	řetězec	Přepsání metody HTTP	`?optionsOverride.HttpMethod=POST`
`optionsOverride.RelativePath`	řetězec	Připojení relativní cesty ke konfiguraci BaseUrl	`?optionsOverride.RelativePath=me/messages`
`optionsOverride.CustomHeader.<Name>`	řetězec	Přidání vlastních hlaviček	`?optionsOverride.CustomHeader.X-Custom=value`

Přesměrování textu požadavku

Tělo se předává beze změny:

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

Odezva

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

Zrcadlení /AuthorizationHeader chyb a stavové kódy chyb podřízených rozhraní API

`/DownstreamApiUnauthenticated/{serviceName}`

Stejné jako /DownstreamApi/{serviceName} token příchozího uživatele se neověřuje. Používá se pouze pro operace pouze s aplikacemi nebo autonomními agenty.

/healthz

Základní koncový bod sondy stavu

Odezva

Zdravé (200):

HTTP/1.1 200 OK

Není v pořádku (503):

HTTP/1.1 503 Service Unavailable

`/openapi/v1.json`

Vrátí specifikaci OpenAPI 3.0 (pouze vývojové prostředí). Použít k:

Generování klientského kódu
Ověření požadavků
Zjišťování koncových bodů

Běžné vzory chyb

Chybný požadavek (400)

Chybějící název služby:

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

Příklad chyby 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": "..." } }

Kompletní referenční informace k přepsání

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

Příklady přepsání

Přepsání oborů:

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

Omezování rychlosti

Samotná sada Microsoft Entra ID Auth SDK (sajdkárna) neukládá omezení rychlosti. Platná omezení pocházejí z:

Microsoft Entra ID omezování služby tokenů (nemělo by k tomu dojít, protože token mezipaměti sady SDK)
Omezení podřízených rozhraní API
Efektivita mezipaměti tokenů (snižuje objem získání)

Osvědčené postupy

Upřednostněte konfiguraci před jednorázovými přepsáními.
Udržujte názvy služeb statické a deklarativní.
Implementujte zásady opakování pro přechodná selhání (HTTP 500/503).
Před voláním ověřte parametry agenta.
ID korelace protokolu pro trasování napříč službami
Monitorujte latenci získávání tokenů a chybovost.
Používejte sondy stavu na platformách orchestrace.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-19

Referenční informace ke koncovým bodům: rozhraní HTTP API Microsoft Entra ID Auth SDK (sajdkárna)

Specifikace rozhraní API

Přehled koncového bodu

Autentizace

/Validate

Žádost

Úspěšná odpověď (200)

Příklady chyb

/AuthorizationHeader/{serviceName}

Parametr cesty

Parametry dotazu

Standardní přepsání

Identita agenta

Examples

Odezva

/AuthorizationHeaderUnauthenticated/{serviceName}

Žádost

Odezva

/DownstreamApi/{serviceName}

Parametr cesty

Další parametry dotazu (kromě /AuthorizationHeader parametrů)

Přesměrování textu požadavku

Odezva

/DownstreamApiUnauthenticated/{serviceName}

/healthz

Odezva

/openapi/v1.json

Běžné vzory chyb

Chybný požadavek (400)

Příklad chyby MSAL

Kompletní referenční informace k přepsání

Příklady přepsání

Omezování rychlosti

Osvědčené postupy

Související obsah

Váš názor

Další materiály

`/Validate`

`/AuthorizationHeader/{serviceName}`

`/AuthorizationHeaderUnauthenticated/{serviceName}`

`/DownstreamApi/{serviceName}`

Další parametry dotazu (kromě `/AuthorizationHeader` parametrů)

`/DownstreamApiUnauthenticated/{serviceName}`

`/openapi/v1.json`