Naslaginformatie over eindpunten: Microsoft Entra ID HTTP-API (Auth SDK) (sidecar)

Dit document bevat volledige naslaginformatie over de HTTP-eindpunten die worden weergegeven door de Microsoft Entra ID Auth SDK (sidecar).

API-specificatie

OpenAPI-specificatie: Beschikbaar op /openapi/v1.json (ontwikkelomgeving) en in de opslagplaats: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Gebruik deze voor het volgende:

• Clientcode genereren
• Aanvragen valideren
• Beschikbare eindpunten detecteren

Overzicht van eindpunten

Authenticatie

Bearer blijft het standaardverificatieschema voor geverifieerde eindpunten. Het /Validate eindpunt accepteert ook het PoP schema voor SHR-referenties (alleen ondertekende HTTP-aanvraag). Voor andere geverifieerde eindpunten is Bearer vereist, tenzij expliciet is gemarkeerd als niet-geverifieerd:

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

Tokens worden gevalideerd op basis van geconfigureerde Microsoft Entra ID-instellingen, waaronder tenant, doelgroep, verlener en bereiken wanneer deze zijn ingeschakeld. Voor PoP-aanvragen valideert de sidecar de SHR-handtekening en het ingesloten toegangstoken voor dezelfde tenant, doelgroep, verlener en ondertekeningssleutelconfiguratie.

/Validate

Hiermee valideert u een binnenkomende Bearer-token of alleen-app-SHR PoP-referentie en retourneert u het gevalideerde token en de bijbehorende claims.

Aanvraag

Bearer-aanvraag:

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

PoP-aanvraag:

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

Voor PoP original-method en original-uri zijn vereist. Ze moeten de methode en absolute URI van de oorspronkelijke aanvraag bevatten waarvoor de SHR-referentie is ondertekend. De sidecar gebruikt deze waarden om aanvraagbinding te valideren; de /Validate aanvraag zelf is niet de ondertekende resourceaanvraag.

Geslaagde reactie (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"
  }
}

De protocol waarde is Bearer voor een Bearer-aanvraag en PoP voor een PoP-aanvraag. Voor PoP token bevat het gevalideerde toegangstoken dat is ingesloten in de ondertekende HTTP-aanvraag. De geretourneerde claims zijn afhankelijk van de versie van het toegangstoken en de tenantconfiguratie.

Voorbeelden van fouten

Ontbrekende autorisatiereferenties worden geweigerd voordat het eindpunt wordt uitgevoerd:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

Een ongeldig Bearer-token retourneert een Bearer-uitdaging:

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

Een mislukte PoP-aanvraag omvat de volgende uitdaging. Omdat /Validate beide verificatieschema's worden geaccepteerd, kan het antwoord ook de Bearer-uitdaging bevatten.

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

/AuthorizationHeader/{serviceName}

Hiermee verkrijgt u een toegangstoken voor de geconfigureerde downstream-API en wordt het geretourneerd als een waarde voor de autorisatieheader. Als een bearer-token van een gebruiker binnenkomend is opgegeven, wordt OBO (gedelegeerd) gebruikt; anders zijn app-contextpatronen van toepassing (indien ingeschakeld).

Padparameter

• serviceName – Naam van de downstream-API in configuratie

Parameters voor zoekopdrachten

Standaardoverschrijvingen

Agentidentiteit

Reglement:

• AgentUsername of AgentUserId vereisen AgentIdentity (gebruikersagent).
• AgentUsername en AgentUserId sluiten elkaar wederzijds uit.
• AgentIdentity alleen = autonome agent.
• AgentIdentity + inkomend token van gebruiker = gedelegeerde agent.

Voorbeelden

Basisaanvraag:

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

Reactie

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

PoP-/SHR-antwoord:

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

/AuthorizationHeaderUnauthenticated/{serviceName}

Hetzelfde gedrag en dezelfde parameters als /AuthorizationHeader/{serviceName} maar geen binnenkomende gebruikerstoken wordt verwacht. Wordt gebruikt voor het verkrijgen van apps of autonome/agentidentiteit zonder gebruikerscontext. Vermijdt de overhead van het valideren van een gebruikerstoken.

Aanvraag

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Reactie

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

/DownstreamApi/{serviceName}

Hiermee verkrijgt u een toegangstoken en voert u een HTTP-aanvraag uit naar de downstream-API. Retourneert statuscode, headers en hoofdtekst van het downstreamantwoord. Ondersteunt gebruikers-OBO-, app-only- of agentidentiteitspatronen.

Padparameter

• serviceName – Geconfigureerde downstream-API-naam.

Aanvullende queryparameters (naast /AuthorizationHeader parameters)

Doorsturen van hoofdtekst aanvragen

De hoofdtekst wordt ongewijzigd doorgegeven:

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

Reactie

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

Fouten spiegelen /AuthorizationHeader plus downstream-API-foutcodes.

/DownstreamApiUnauthenticated/{serviceName}

Hetzelfde als /DownstreamApi/{serviceName} maar geen binnenkomende gebruikerstoken wordt gevalideerd. Gebruiken voor bewerkingen van apps of autonome agentbewerkingen.

/healthz

Basiseindpunt voor statustest.

Reactie

In orde (200):

HTTP/1.1 200 OK

Beschadigd (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Retourneert openAPI 3.0-specificatie (alleen ontwikkelomgeving). Gebruik dit om:

• Clientcode genereren
• Aanvragen valideren
• Eindpunten detecteren

Veelvoorkomende foutpatronen

Ongeldige aanvraag (400)

Ontbrekende servicenaam:

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

VOORBEELD VAN MSAL-fout

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

Volledige onderdrukkingsreferentie

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

Voorbeelden van onderdrukking

Bereiken overschrijven:

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

Snelheidsbeperking

De Microsoft Entra ID Auth SDK (sidecar) zelf legt geen frequentielimieten op. Effectieve limieten zijn afkomstig van:

1. Microsoft Entra ID tokenservice beperken (mag niet gebeuren omdat het token voor sdk-caches)
2. Downstream-API-limieten
3. Efficiëntie van tokencache (vermindert het aanschafvolume)

Beste praktijken

1. Geef de voorkeur aan configuratie boven ad-hoc onderdrukkingen.
2. Houd servicenamen statisch en declaratief.
3. Implementeer beleid voor nieuwe pogingen voor tijdelijke fouten (HTTP 500/503).
4. Valideer agentparameters voordat u aanroept.
5. Logboekcorrelatie-id's voor tracering tussen services.
6. Controleer de latentie en foutpercentages van tokens.
7. Gebruik statustests in indelingsplatforms.

Verwante inhoud

• Configuratiereferentie
• Agentidentiteiten
• Autorisatieheader valideren
• Downstream-API aanroepen