Referencia de puntos de conexión: MICROSOFT Entra SDK para la API HTTP agentID

En este documento se proporciona una referencia completa para los puntos de conexión HTTP expuestos por el SDK de Microsoft Entra para AgentID.

Especificación de API

Especificación de 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.AgentID.json

Utilícelo para:

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

Información general del punto de conexión

Autenticación

Todos los puntos de conexión de validación y adquisición de tokens requieren un token de portador en el Authorization encabezado a menos que se marque explícitamente sin autenticar:

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

Los tokens se validan con la configuración de id. de Microsoft Entra configurada (inquilino, audiencia, emisor, ámbitos si está habilitado).

/Validate

Valida el token de portador de entrada y devuelve sus notificaciones.

Solicitud

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

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

Ejemplos de errores

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

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 Microsoft Entra para AgentID no impone límites de velocidad. Los límites efectivos proceden de:

1. Limitación del servicio de token de Id. de Microsoft Entra (no debe ocurrir 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.

Véase también

• Referencia de configuración
• Identidades del agente
• Escenarios: Validar encabezado de autorización
• Escenarios: Obtener encabezado de autorización
• Escenarios: Llamada a la API de bajada