Autenticar usuários com o sidecar do SDK de Autenticação

Um cliente upstream autentica o usuário e envia um token de acesso para o agente. O agente passa esse token para o sidecar para validação antes de usar as claims do usuário ou realizar uma troca On-Behalf-Of (OBO).

O sidecar não fornece a interface do usuário para login. Use o MSAL no cliente Web upstream, de desktop ou móvel.

Prerequisites

Configurar o público-alvo

Registre um escopo exposto pela API do agente. O cliente upstream solicita esse escopo para que o token de acesso resultante seja destinado ao agente.

Não envie um token emitido para Microsoft Graph ou outro recurso para a API do agente.

Configure o sidecar para validar o público-alvo da API do agente e o escopo delegado:

Defina AzureAd:ClientId como a ID do cliente registrada durante a instalação, não uma ID de objeto de diretório. Defina AzureAd:Scopes como access_agent. O cliente upstream solicita api://<agent-client-id>/access_agent.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<agent-client-id>",
    "Scopes": "access_agent"
  }
}

Use a mesma seção AzureAd para configurar a credencial de blueprint. Para a configuração completa do contêiner e da credencial, consulte Configurar o sidecar do SDK de Autenticação.

Validar o token

Encaminhe o cabeçalho de autorização de entrada completo para o sidecar:

GET /Validate
Authorization: ******

A resposta inclui o protocolo, o token e as claims validados. Use as claims para identificar o usuário e impor a política de autorização do agente.

Não confie em declarações decodificadas pelo cliente ou pelo agente antes da validação.

Invocar o sidecar

Valide o cabeçalho de autorização de entrada com o sidecar antes de usar seus claims retornados. Exija que protocol seja Bearer, que as declarações oid e tid não sejam vazias e que access_agent esteja na declaração scp separada por espaços. Identifique o chamador pela combinação de tid e oid. Rejeite a solicitação se alguma verificação falhar e aplique a política de autorização do agente antes de processá-la.

import requests

SIDECAR_URL = "http://localhost:5000"

def validate_caller(inbound_auth_header: str) -> dict:
    """Validate an inbound access token with the sidecar and return the token claims."""
    response = requests.get(
        f"{SIDECAR_URL}/Validate",
        headers={"Authorization": inbound_auth_header},
        timeout=5,
    )

    if response.status_code in (401, 403):
        raise PermissionError("The sidecar rejected the caller's access token.")

    response.raise_for_status()
    result = response.json()

    if result.get("protocol", "").lower() != "bearer":
        raise PermissionError("The validated token used an unexpected protocol.")

    claims = result.get("claims", {})
    object_id = claims.get("oid")
    tenant_id = claims.get("tid")

    if not object_id or not tenant_id:
        raise PermissionError("The validated token doesn't identify a user and tenant.")

    if "access_agent" not in claims.get("scp", "").split():
        raise PermissionError("The caller doesn't have the required delegated scope.")

    return claims


# Call before processing each request:
claims = validate_caller(request.headers.get("Authorization"))
# Use claims["oid"] and claims["tid"] as the stable caller identity.
# Apply the agent's authorization policy before processing the request.

Mantenha SIDECAR_URL em loopback no namespace de rede compartilhada. Substitua o espaço reservado authorization-header pelo cabeçalho completo Authorization recebido pelo agente. Se você usar um escopo diferente access_agent, atualize a configuração do sidecar e a verificação de escopo do auxiliar.

A resposta também contém o token validado, mas o exemplo não o desserializa. Não retorne nem registre o token. Se o sidecar rejeitar o token, rejeite a solicitação do agente em vez de decodificar o token localmente ou continuar sem um usuário autenticado.

Retornar 401 Unauthorized para um token ausente ou inválido e 403 Forbidden quando um chamador autenticado não tiver o escopo ou acesso necessário. Não continue para a API downstream após qualquer rejeição.

O exemplo também rejeita as credenciais que o sidecar validou com outro protocolo, como um token de prova de posse somente para aplicativo. Use o identificador do locatário validado e o identificador do objeto como a chave de usuário estável. Aplique a política de autorização do agente antes de processar a solicitação.

Próximas Etapas 

  1. Controlar quais usuários podem acessar o agente.
  2. Solicite consentimento para permissões delegadas.
  3. Chame uma API personalizada em nome do usuário.