Referência de pontos de extremidade: SDK do Microsoft Entra para a API HTTP agentID

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

Especificação da API

Especificação do 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.AgentID.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 ID do Microsoft Entra 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 path

• 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 path

• serviceName – Nome da API downstream configurado.

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

Encaminhamento do corpo da solicitação

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 AgentID em si não impõe limites de taxa. Os limites efetivos são provenientes de:

1. Limitação do serviço de token do Microsoft Entra ID (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.

Consulte Também

• Referência de configuração
• Identidades do agente
• Cenários: validar cabeçalho de autorização
• Cenários: obter o cabeçalho de autorização
• Cenários: Chamar a API Downstream