Steuern des Benutzerzugriffs auf Agenten mit dem Auth SDK Sidecar

App-Rollen definieren, wer auf einen Agent zugreifen kann und was sie tun können. Definieren und weisen Sie eine Rolle für den eingehenden Zugriff zu, und erzwingen Sie sie, indem Sie den vom Sidecar zurückgegebenen roles Claim überprüfen. Die Benutzerzugriffshilfsprogramme in diesem Artikel erfordern die Agent.User Rolle und einen delegierten Benutzerscope.

Verwenden Sie für die Cloud Journey einer einzelnen Softwareinstanz die Objekt-ID der Agentidentität in Form von <agent-api-service-principal-object-id> in den Anforderungen in diesem Artikel. Ein Blueprint für Einzelinstanzen weist keinen Blueprintprinzipal auf. Verwenden Sie für die Advanced Fleet Journey stattdessen den Blueprint-Prinzipal der Flotte; seine Zuordnungen gelten für die gesamte Flotte.

Voraussetzungen

App-Rollen definieren

Verwenden Sie dieselbe Rollendefinitionsprozedur wie der ASP.NET Core-Agent:

  • Einzelinstanz: Deklarieren Sie auf dem Blueprint, und veröffentlichen Sie dann dieselbe GUID und denselben Wert direkt für den Agent ID-Dienstprinzipal, wobei auf festgelegt ist. Verlassen Sie sich nicht auf eine ausschließlich im Blueprint definierte Deklaration.
  • Flotte: Definieren Sie die Rolle für die Blueprintanwendung, und verwenden Sie den Blueprintprinzipal für Zuweisungen.

Überprüfen Sie die Rolle für den Ressourcenprinzipal , bevor Sie fortfahren. Speichern Sie die GUID für <app-role-id> unten. Rollenwerte müssen stabil bleiben, da der Agent sie in den vom Sidecar zurückgegebenen Claims überprüft.

Anfordern einer App-Rollenzuweisung

Legen Sie appRoleAssignmentRequired für den Agent-API-Dienstprinzipal fest. Wenn die Eigenschaft lautettrue, gibt Microsoft Entra ID ein Zugriffstoken für die Agent-API nur für zugewiesene Benutzer und Anwendungen aus.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "appRoleAssignmentRequired": true
}

Weitere Informationen finden Sie in der Microsoft Graph Update-API-Referenz.

App-Rolle zuweisen

Weisen Sie einem Benutzer für den Agent-API-Dienstprinzipal die App-Rolle zu:

POST https://graph.microsoft.com/v1.0/users/<user-object-id>/appRoleAssignments
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "principalId": "<user-object-id>",
  "resourceId": "<agent-api-service-principal-object-id>",
  "appRoleId": "<app-role-id>"
}

Erstellen Sie für eine Gruppe die Zuweisung über die App-Rollenzuweisungen der Gruppe. Verwenden Sie die Objekt-ID des Agent-API-Dienstprinzipals als resourceId. Diese Hilfsfunktionen autorisieren angemeldete Benutzer; sie autorisieren keine Anrufer, die sich ausschließlich als Anwendung authentifizieren.

Erzwingen von App-Rollen mit dem Sidecar

Nachdem das Sidecar das eingehende Token überprüft hat, enthält seine Antwort die Claims des Tokens. Überprüfen Sie den roles Claim vor der Verarbeitung der Anforderung.

Die folgenden Benutzerzugriffs-Hilfsprogramme erfordern das oid-Protokoll, nicht leere tid- und access_agent-Ansprüche, scp im durch Leerzeichen getrennten roles-Anspruch und den erforderlichen Wert im Bearer-Array. Verwenden Sie Agent.User als erforderliche Rolle für dieses Beispiel. Diese Helfer autorisieren keine Nur-App-Anrufer oder das dedizierte Benutzerkonto eines Agents.

Rufen Sie den /Validate-Endpunkt des Sidecars auf und überprüfen Sie die erforderliche Rolle, bevor Sie jede Anfrage verarbeiten:

import requests

SIDECAR_URL = "http://localhost:5000"

def validate_and_check_role(inbound_auth_header: str, required_role: str) -> dict:
    """Validate an inbound token and verify the caller has the required app role."""
    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()
    claims = result.get("claims", {})
    if (
        result.get("protocol", "").lower() != "bearer"
        or not claims.get("oid")
        or not claims.get("tid")
        or "access_agent" not in claims.get("scp", "").split()
    ):
        raise PermissionError("The caller isn't an authorized user of the agent API.")

    roles = claims.get("roles", [])

    if required_role not in roles:
        raise PermissionError(
            f"The caller doesn't have the required '{required_role}' role."
        )

    return claims

Rufen Sie das Hilfsprogramm auf, bevor Sie jede Anfrage verarbeiten:

claims = validate_and_check_role(
    inbound_auth_header=request.headers.get("Authorization"),
    required_role="Agent.User",
)
# Use claims["oid"] and claims["tid"] as the stable caller identity.

Geben Sie 403 Forbidden zurück, wenn die Rollenüberprüfung fehlschlägt. Geben Sie 401 Unauthorized nur zurück, wenn das Token selbst fehlt oder ungültig ist. Fordern Sie nach dem Ändern einer Zuweisung ein neues Zugriffstoken an. Überprüfen Sie bei der Problembehandlung die Zuordnung für den Agent-API-Dienstprinzipal, und überprüfen Sie den roles Anspruch in der Antwort von /Validate.

Nächster Schritt

Anfordern der Zustimmung für delegierte Berechtigungen