Referência de pontos de extremidade: Microsoft Entra ID API HTTP do SDK de Autenticação (sidecar)

Este documento fornece referência completa para os pontos de extremidade HTTP expostos pelo SDK de Autenticação Microsoft Entra ID (sidecar).

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

O portador continua sendo o esquema de autenticação padrão para pontos de extremidade autenticados. O /Validate ponto de extremidade também aceita o PoP esquema para credenciais SHR (Solicitação HTTP Assinada) somente por aplicativo. Outros pontos de extremidade autenticados exigem portador, a menos que seja explicitamente marcado 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, incluindo locatário, audiência, emissor e escopos quando habilitados. Para solicitações pop, o sidecar valida a assinatura SHR e seu token de acesso inserido em relação ao mesmo locatário, audiência, emissor e configuração de chave de assinatura.

/Validate

Valida um token de portador de entrada ou credencial SHR PoP somente de aplicativo e retorna o token validado e suas declarações.

Solicitação

Solicitação do portador:

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

Solicitação pop:

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

Para PoP e original-methodoriginal-uri são necessários. Eles devem conter o método e o URI absoluto da solicitação original pela qual a credencial SHR foi assinada. O sidecar usa esses valores para validar a associação de solicitação; a /Validate solicitação em si não é a solicitação de recurso assinada.

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

O protocol valor é Bearer para uma solicitação de portador e PoP para uma solicitação PoP. Para PoP, token contém o token de acesso validado inserido na solicitação HTTP assinada. As declarações retornadas dependem da versão do token de acesso e da configuração do locatário.

Exemplos de erro

As credenciais de autorização ausentes são rejeitadas antes da execução do ponto de extremidade:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

Um token de portador inválido retorna um desafio de portador:

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

Uma solicitação PoP com falha inclui o desafio a seguir. Como /Validate aceita ambos os esquemas de autenticação, a resposta também pode conter o desafio portador.

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

/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 próprio SDK de autenticação de Microsoft Entra ID (sidecar) 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