Referencia de puntos de conexión: MICROSOFT ENTRA ID API HTTP del SDK de autenticación (sidecar)

En este documento se proporciona una referencia completa para los puntos de conexión HTTP expuestos por el SDK de autenticación de Microsoft Entra ID (sidecar).

Especificación de API

especificación OpenAPI: disponible en /openapi/v1.json (entorno de desarrollo) y en el repositorio: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Utilícelo para:

• Generación de código de cliente
• Validar solicitudes
• Detección de puntos de conexión disponibles

Introducción al punto de conexión

Autenticación

El portador sigue siendo el esquema de autenticación predeterminado para los puntos de conexión autenticados. El /Validate punto de conexión también acepta el PoP esquema para las credenciales de solicitud HTTP firmadas (SHR) de solo aplicación. Otros puntos de conexión autenticados requieren portador, a menos que se marque explícitamente como no autenticado:

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

Los tokens se validan con la configuración de Microsoft Entra ID configurada, como inquilino, audiencia, emisor y ámbitos cuando están habilitados. En el caso de las solicitudes poP, sidecar valida la firma SHR y su token de acceso incrustado en el mismo inquilino, audiencia, emisor y configuración de clave de firma.

/Validate

Valida un token de portador entrante o una credencial SHR PoP de solo aplicación y devuelve el token validado y sus notificaciones.

Solicitud

Solicitud de portador:

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

Solicitud poP:

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

Para poP original-method y original-uri son necesarios. Deben contener el método y el URI absoluto de la solicitud original en la que se firmó la credencial de SHR. El sidecar usa estos valores para validar el enlace de solicitud; la /Validate propia solicitud no es la solicitud de recurso firmada.

Respuesta correcta (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"
  }
}

El protocol valor es Bearer para una solicitud de portador y PoP para una solicitud poP. Para poP, token contiene el token de acceso validado incrustado en la solicitud HTTP firmada. Las notificaciones devueltas dependen de la configuración del inquilino y la versión del token de acceso.

Ejemplos de error

Las credenciales de autorización que faltan se rechazan antes de que se ejecute el punto de conexión:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

Un token de portador no válido devuelve un desafío de portador:

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

Una solicitud poP con error incluye el siguiente desafío. Dado que /Validate acepta ambos esquemas de autenticación, la respuesta también puede contener el desafío de portador.

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

/AuthorizationHeader/{serviceName}

Adquiere un token de acceso para la API de bajada configurada y lo devuelve como un valor de encabezado de autorización. Si se proporciona un token de portador de usuario entrante, se usa OBO (delegado); De lo contrario, se aplican patrones de contexto de aplicación (si está habilitado).

Parámetro path

• serviceName : nombre de la API de bajada en la configuración

Parámetros de consulta

Invalidaciones estándar

Identidad del agente

Reglas:

• AgentUsername o AgentUserId requerir AgentIdentity (agente de usuario).
• AgentUsername y AgentUserId son mutuamente excluyentes.
• AgentIdentity alone = agente autónomo.
• AgentIdentity + token de entrada de usuario = agente delegado.

Examples

Solicitud básica:

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

Respuesta

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

Respuesta poP/SHR:

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

/AuthorizationHeaderUnauthenticated/{serviceName}

Se espera el mismo comportamiento y parámetros que /AuthorizationHeader/{serviceName} , pero no se espera ningún token de usuario entrante. Se usa para la adquisición de identidades solo para aplicaciones o agentes o autónomos sin un contexto de usuario. Evita la sobrecarga de validar un token de usuario.

Solicitud

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Respuesta

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

/DownstreamApi/{serviceName}

Adquiere un token de acceso y realiza una solicitud HTTP a la API de bajada. Devuelve el código de estado, los encabezados y el cuerpo de la respuesta de bajada. Admite patrones de identidad de usuario OBO, solo aplicación o agente.

Parámetro path

• serviceName : se ha configurado el nombre de la API de bajada.

Parámetros de consulta adicionales (además de /AuthorizationHeader parámetros)

Reenvío del cuerpo de la solicitud

El cuerpo se pasa sin cambios:

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

Respuesta

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

Reflejo de errores /AuthorizationHeader más códigos de estado de error de API de bajada.

/DownstreamApiUnauthenticated/{serviceName}

Igual que /DownstreamApi/{serviceName} pero no se valida ningún token de usuario entrante. Use para las operaciones solo de aplicación o agente autónomo.

/healthz

Punto de conexión de sondeo de estado básico.

Respuesta

Correcto (200):

HTTP/1.1 200 OK

Incorrecto (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Devuelve la especificación OpenAPI 3.0 (solo entorno de desarrollo). Use para:

• Generación de código de cliente
• Validar solicitudes
• Detección de puntos de conexión

Patrones de error comunes

Solicitud incorrecta (400)

Falta el nombre del servicio:

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

Ejemplo de error de 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": "..." } }

Referencia de invalidación completa

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

Ejemplos de invalidación

Invalidar ámbitos:

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

Limitación de velocidad

El SDK de autenticación (sidecar) de Microsoft Entra ID no impone límites de velocidad. Los límites efectivos proceden de:

1. Microsoft Entra ID limitación del servicio de token (no debe producirse como token de caché del SDK)
2. Límites de API de bajada
3. Eficacia de la caché de tokens (reduce el volumen de adquisición)

procedimientos recomendados

1. Prefiere la configuración en invalidaciones ad hoc.
2. Mantenga los nombres de servicio estáticos y declarativos.
3. Implemente directivas de reintento para errores transitorios (HTTP 500/503).
4. Valide los parámetros del agente antes de llamar a .
5. Identificadores de correlación de registro para el seguimiento entre servicios.
6. Supervise la latencia de adquisición de tokens y las tasas de error.
7. Use sondeos de estado en plataformas de orquestación.

Contenido relacionado

• Referencia de configuración
• Identidades del agente
• Validar encabezado de autorización
• Llamar a la API descendente