Referência de pontos de extremidade: Microsoft Entra SDK para API HTTP da ID do Agente

Este documento fornece referência completa para os pontos de extremidade HTTP expostos pelo SDK do Microsoft Entra para AgentID.

Especificação da API

especificação OpenAPI: disponível em /openapi/v1.json (ambiente de desenvolvimento) e no repositório: https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.Sidecar.json

Use-o para:

• Gerar código do cliente
• Validar solicitações
• Descobrir pontos de extremidade disponíveis

Visão geral do ponto de extremidade

Authentication

Todos os pontos de extremidade de aquisição e validação de token exigem um token de portador no cabeçalho, a Authorization menos que seja marcado explicitamente como não autenticado:

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

Os tokens são validados em relação às configurações de Microsoft Entra ID definidas (locatário, audiência, emissor, escopos, se habilitados).

/Validate

Valida o token de portador de entrada e retorna suas declarações.

Solicitação

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

Resposta bem-sucedida (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"
  }
}

Exemplos de erro

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

Adquire um token de acesso para a API downstream configurada e retorna-o como um valor de cabeçalho de autorização. Se um token de portador de usuário for fornecido na entrada, o OBO (delegado) será usado; caso contrário, os padrões de contexto do aplicativo se aplicam (se habilitados).

Parâmetro de caminho

• serviceName – Nome da API downstream na configuração

Parâmetros de consulta

Substituições padrão

Identidade do agente

Réguas:

• AgentUsername ou AgentUserId requer AgentIdentity (agente do usuário).
• AgentUsername e AgentUserId são mutuamente exclusivos.
• AgentIdentity alone = agente autônomo.
• AgentIdentity + token de entrada do usuário = agente delegado.

Exemplos

Solicitação 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...

Resposta

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

Resposta de PoP/SHR:

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

/AuthorizationHeaderUnauthenticated/{serviceName}

O mesmo comportamento e parâmetros, /AuthorizationHeader/{serviceName} mas nenhum token de usuário de entrada é esperado. Usado para aquisição de identidade somente de aplicativo ou autônomo/agente sem um contexto de usuário. Evita a sobrecarga de validar um token de usuário.

Solicitação

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

Resposta

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

/DownstreamApi/{serviceName}

Adquire um token de acesso e executa uma solicitação HTTP para a API downstream. Retorna código de status, cabeçalhos e corpo da resposta downstream. Dá suporte a padrões de identidade do usuário OBO, somente aplicativo ou agente.

Parâmetro de caminho

• serviceName – Nome da API downstream configurado.

Parâmetros de consulta adicionais (além /AuthorizationHeader dos parâmetros)

Solicitar encaminhamento do corpo

O corpo é passado por inalterado:

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

Resposta

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

Erros espelham /AuthorizationHeader mais códigos de status de erro da API downstream.

/DownstreamApiUnauthenticated/{serviceName}

O mesmo que /DownstreamApi/{serviceName} mas nenhum token de usuário de entrada é validado. Use para operações de agente autônomo ou somente aplicativo.

/healthz

Ponto de extremidade básico da investigação de integridade.

Resposta

Íntegro (200):

HTTP/1.1 200 OK

Não íntegro (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

Retorna a especificação OpenAPI 3.0 (somente ambiente de desenvolvimento). Use para:

• Gerar código do cliente
• Validar solicitações
• Descobrir pontos de extremidade

Padrões de erro comuns

Solicitação incorreta (400)

Nome do serviço ausente:

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

Exemplo de erro 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": "..." } }

Referência de substituição 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

Exemplos de substituição

Substituir escopos:

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

Limitação de taxa

O SDK do Microsoft Entra para iD do agente em si não impõe limites de taxa. Os limites efetivos são provenientes de:

1. Microsoft Entra ID limitação do serviço de token (não deve acontecer como o token de cache do SDK)
2. Limites de API downstream
3. Eficiência do cache de token (reduz o volume de aquisição)

Práticas recomendadas

1. Prefira a configuração em vez de substituições ad hoc.
2. Mantenha os nomes de serviço estáticos e declarativos.
3. Implemente políticas de repetição para falhas transitórias (HTTP 500/503).
4. Valide os parâmetros do agente antes de chamar.
5. IDs de correlação de log para rastreamento entre serviços.
6. Monitore a latência de aquisição de token e as taxas de erro.
7. Use investigações de integridade em plataformas de orquestração.

Conteúdo relacionado

• Referência de configuração
• Identidades do agente
• Validar cabeçalho de autorização
• Chamar Downstream API