Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Un client upstream autentica l'utente e invia un token di accesso all'agente. L'agente passa tale token al sidecar per la convalida prima che usi le attestazioni dell'utente o esegua uno scambio OBO (On-Behalf-Of).
Il sidecar non fornisce l'interfaccia utente di accesso. Usare MSAL nel client Web, desktop o mobile upstream.
Prerequisites
- Completamento della configurazione di Auth SDK sidecar, inclusa la registrazione e le credenziali dell'agente.
- Un client upstream che autentica un utente e richiede un token per l'ambito esposto dell'agente.
- Completamento della configurazione dell'autorizzazione delegata e della concessione dell'accesso al client upstream. Questi passaggi di registrazione e di consenso di Microsoft Graph si applicano anche al sidecar; non usare il codice ASP.NET Core di tale articolo.
Configurare il pubblico
Registrare un ambito esposto dall'API dell'agente. Il client upstream richiede l'ambito in modo che il token di accesso risultante sia destinato all'agente.
Non inviare un token rilasciato per Microsoft Graph o un'altra risorsa all'API dell'agente.
Configurare il sidecar per convalidare l'audience e l'ambito delegato dell'API dell'agente:
Impostare AzureAd:ClientId sull'ID client registrato durante la configurazione, non su un ID oggetto della directory. Impostare AzureAd:Scopes su access_agent. Il client upstream richiede api://<agent-client-id>/access_agent.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "<tenant-id>",
"ClientId": "<agent-client-id>",
"Scopes": "access_agent"
}
}
Usare la stessa sezione AzureAd per configurare la credenziale blueprint. Per la configurazione completa di contenitori e credenziali, vedere Configurare il sidecar di Auth SDK.
Convalidare il token
Inoltrare l'intestazione di autorizzazione in ingresso completa al sidecar:
GET /Validate
Authorization: ******
La risposta include il protocollo, il token e le claims convalidati. Usare le attestazioni per identificare l'utente e applicare i criteri di autorizzazione dell'agente.
Non considerare attendibili i claim decodificati dal client o dall'agente prima della convalida.
Invoca il sidecar
Convalida l'intestazione di autorizzazione in ingresso con il sidecar prima di usare le attestazioni restituite. Richiedere protocol che sia Bearer, claim oid e tid non vuoti e access_agent nel claim scp con valori separati da spazi. Identificare il chiamante tramite la combinazione di tid e oid. Rifiutare la richiesta se un controllo ha esito negativo e applicare i criteri di autorizzazione dell'agente prima di elaborarlo.
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.
Mantenere SIDECAR_URL sul loopback nello spazio dei nomi della rete condivisa. Sostituire il segnaposto authorization-header con l'header completo Authorization ricevuto dall'agente. Se si usa un ambito diverso da access_agent, aggiornare sia la configurazione sidecar che il controllo dell'ambito dell'helper.
La risposta contiene anche il token convalidato, ma l'esempio non lo deserializza. Non restituire o registrare il token. Se il sidecar rifiuta il token, rifiutare la richiesta dell'agente invece di decodificare il token in locale o continuare senza un utente autenticato.
Restituisce 401 Unauthorized un token mancante o non valido e 403 Forbidden quando un chiamante autenticato non dispone dell'ambito o dell'accesso richiesto. Non continuare con l'API downstream dopo il rifiuto.
L'esempio rifiuta anche le credenziali convalidate dal sidecar con un altro protocollo, ad esempio un token proof-of-possession per sola app. Usare l'ID tenant convalidato e l'ID oggetto come chiave utente stabile. Applicare i criteri di autorizzazione dell'agente prima di elaborare la richiesta.
Passaggi successivi
- Controllare quali utenti possono accedere all'agente.
- Richiedere il consenso per le autorizzazioni delegate.
- Chiamare un'API personalizzata come utente.