Steuern Sie den Zugriff auf Agenten mit App-Rollen

App-Rollen definieren, wer auf einen Agent zugreifen kann und was sie tun können. Verwenden Sie sie, um Agentvorgänge auf genehmigte Benutzer, Gruppen oder Clientanwendungen einzuschränken.

In diesem Artikel definieren Sie eine Rolle für eingehenden Zugriff, weisen sie einem Aufrufer zu und erzwingen sie in der Agent-API. Wo Sie die Rolle definieren, hängt davon ab, ob der Agent einen Einzelinstanz-Blueprint oder eine Flotte verwendet.

Voraussetzungen

  • Ein Blueprint und sein Agent-API-Dienstprinzipal.
  • Ein autorisierter Microsoft Graph-Verwaltungsclient für die Rollenkonfiguration. Bei der delegierten Einzelinstanzverwaltung muss der angemeldete Benutzer über die Agentidentität verfügen oder über die Rolle " Agent-ID-Administrator " verfügen. Informationen zu den entsprechenden API-Berechtigungen finden Sie unter servicePrincipal aktualisieren.
  • Anwendungsadministrator oder Cloudanwendungsadministrator zum Verwalten von Benutzer- und Gruppen-App-Rollenzuweisungen.
  • AppRoleAssignment.ReadWrite.All und die entsprechende Leseberechtigung für programmgesteuerte Zuordnungen.

Für die Cloud-Reise mit einer einzelnen Instanz ist der Dienstprinzipal der API die Agentidentität und kein Blueprint-Prinzipal. Verwenden Sie die Objekt-ID wie <agent-api-service-principal-object-id> in den Anfragen in diesem Artikel. Ein Einzelinstanz-Blueprint weist keinen Blueprintprinzipal auf. Verwenden Sie für den erweiterten Flottenworkflow stattdessen den Blueprint-Prinzipal der Flotte; seine Zuordnungen gelten für die gesamte Flotte.

App-Rollen definieren

Wählen Sie den Definitionsspeicherort für den Instanzmodus aus:

Instanzmodus Definieren Sie die eingehende Rolle für Rolle zuweisen
Einzelinstanz Die Blueprintanwendung und der Agent-ID-Dienstprinzipal, wobei dieselbe Rollen-GUID und derselbe Wert verwendet werden. Der Agent-ID-Service Principal.
Fleet Die blueprint-Anwendung. Der Blueprint-Prinzipal, der die Flotten-API darstellt.

Verwenden Sie eine Rolle, wenn jeder über dieselbe Zugriffsebene verfügt. Verwenden Sie Agent.User z. B. für Standardaufgaben und fügen Sie nur hinzu Agent.Admin , wenn Sie Administrative Aufgaben verfügbar machen. Halten Sie Rollenwerte stabil, da Ihre Autorisierungsrichtlinien sie überprüfen.

Deklarieren Sie die Rolle im Blueprint

Definieren Sie Agent.User in der Sammlung der Blueprintanwendung appRoles . Füllen Sie für einen Einzelinstanz-Agent auch den nächsten Abschnitt aus, um dieselbe Rolle auf seiner Agent-ID verfügbar zu machen.

Lesen Sie zuerst die vorhandene Blaupause appRoles. Die folgende Anforderung ist für einen Blueprint ohne vorhandene Rollen vorgesehen. Schließen Sie für eine vorhandene Sammlung die vorhandenen Rollendefinitionen ein, die Sie aufbewahren möchten; durch das Aktualisieren von appRoles wird die Sammlung ersetzt. Lassen Sie das schreibgeschützte origin Feld aus Anfragen aus.

Ersetzen Sie <agent-user-role-id> durch eine neue GUID, und speichern Sie sie für den Zuweisungsschritt:

PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>

{
  "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
  "appRoles": [
    {
      "id": "<agent-user-role-id>",
      "allowedMemberTypes": ["User"],
      "description": "Use standard agent features",
      "displayName": "Agent user",
      "isEnabled": true,
      "value": "Agent.User"
    }
  ]
}

Benutzerzugriff für Einzelinstanzen

Veröffentlichen Sie für einen Einzelinstanz-Agenten die gleiche Benutzerrolle direkt in der appRoles-Sammlung der Agent-ID. Verwenden Sie dieselbe GUID und denselben Wert wie in der Blueprintdeklaration, nicht eine zweite Rollen-GUID. Die Nur-Blueprint-Deklaration stellt die Rolle für die Zuweisung für die Agent-ID nicht zur Verfügung. Die Nur-Dienstprinzipal-Definition vervollständigt die in diesem Verfahren verwendete Blueprintkonfiguration nicht.

Lesen Sie zuerst die vorhandenen Rollen der Agent-ID, und behalten Sie ihre Definitionen im Update bei. Senden Sie für eine Agent-ID ohne vorhandene Rollen Folgendes:

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

{
  "appRoles": [
    {
      "id": "<agent-user-role-id>",
      "allowedMemberTypes": ["User"],
      "description": "Use standard agent features",
      "displayName": "Agent user",
      "isEnabled": true,
      "value": "Agent.User"
    }
  ]
}

Dies ist die Rollenkonfiguration für zwei separate Objekte, nicht die Berechtigungsvererbung oder eine nachgeschaltete API-Erteilung. Erstellen Sie keinen Blueprint Principal für einen Agent mit nur einer Instanz.

Die Dienstprinzipaldefinition unterstützt User für Benutzer und Gruppen. Fügen Sie Application dieser Anforderung nicht hinzu: Rollen, die Clientanwendungen zugewiesen werden können, müssen für ein Anwendungsobjekt definiert werden. Diese Einzelinstanzprozedur umfasst eingehenden Benutzerzugriff, nicht Aufrufer, die nur Anwendungen sind. Siehe die appRole-Ressourcenreferenz.

Flottenzugang

Für eine Flotte verwenden Sie die Blueprint-Deklaration ohne die Aktualisierung des Dienstprinzipals für Einzelinstanzen. Schließen Sie User in allowedMemberTypes für Benutzer oder Gruppen und Application für Clientanwendungen ein. Informationen zum Verfahren auf Anwendungsebene finden Sie unter Hinzufügen von App-Rollen zu einer Anwendung. Verwenden Sie den Blueprint-Prinzipal, nicht eine untergeordnete Agent-ID, als Ressource für eingehende Zuordnungen.

Überprüfen Sie die Rolle für den Ressourcenprinzipal

Rufen Sie vor dem Anfordern oder Zuweisen einer Rolle den Blueprint mit GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=appRoles und den Agent-API-Prinzipal mit GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>?$select=appRoles erneut ab. Verwenden Sie einen autorisierten Verwaltungsclient, nicht das Laufzeittoken des Agents.

Vergewissern Sie sich, dass das appRoles des Prinzipals das exakte id und value der Rolle enthält, dass isEnabledtrue ist und dass allowedMemberTypes den vorgesehenen Typ des Zuweisungsempfängers enthält.

Wenn bei einer Zuordnung Permission being assigned was not found on application zurückgegeben wird, überprüfen Sie die Rollendefinition für den Ressourcenprinzipal und die resourceId und appRoleId der Zuordnung. Vervollständigen Sie bei einem Einzelinstanz-Agent die obige direkte Definition, wenn Sie die Rolle nur für den Blueprint definiert haben. Erstellen Sie keinen Blueprintprinzipal, ersetzen Sie ihn nicht durch eine andere Ressource, oder entfernen Sie nicht die Rollenüberprüfung der API. Fahren Sie erst fort, nachdem der vorgesehene Prinzipal die Rolle verfügbar macht.

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 die App-Rolle einem Benutzer im Agent-API-Service Principal 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>"
}

Verwenden Sie die GUID, die beim Definieren von <app-role-id> als Agent.User gespeichert wurde. Erstellen Sie für eine Gruppe die Zuweisung über die App-Rollenzuweisungen der Gruppe. Erstellen Sie für eine Flottenrolle, die Application zulässt, die Zuweisung einer Clientanwendung über den Dienstprinzipal dieses Clients. Verwenden Sie in jedem Fall die Objekt-ID des Agent-API-Dienstprinzipals als resourceId.

Erzwingen von App-Rollen in der Agent-API

Wenn ein zugewiesener Benutzer oder eine Zugewiesene Anwendung ein Zugriffstoken für die Agent-API abruft, enthält Microsoft Entra ID die zugewiesenen App-Rollenwerte im Anspruch des roles Tokens. Die Agent-API überprüft diesen Claim, bevor sie den angeforderten Vorgang zulässt.

Fügen Sie nach dem Konfigurieren der Authentifizierungs- und Tokenüberprüfung eine Autorisierungsrichtlinie hinzu, die die App-Rolle erfordert:

Führen Sie in Program.cs die Richtlinienregistrierung vor builder.Build() in builder.Services.AddAuthorization zusammen. Platzieren Sie die Endpunktzuordnung nach der Authentifizierungs- und Autorisierungs-Middleware und vor app.Run(); die beiden Teile dieses Fragments sind nicht in einer vollständigen Anwendung nebeneinander.

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "AgentUser",
        policy => policy.RequireRole("Agent.User"));
});

app.MapPost("/tasks", () => Results.Accepted())
    .RequireAuthorization("AgentUser");

AddAuthorizationregistriert die ASP.NET Core Autorisierungsdienste. RequireRole überprüft die authentifizierte Identität auf die Agent.User-Rolle. Microsoft.Identity.Web erkennt Microsoft Entra-App-Rollen im roles-Anspruch des Zugriffstokens.

Rufen Sie UseAuthentication vor UseAuthorization der Middlewarepipeline auf, wie im Authentifizierungsartikel gezeigt. Fordern Sie nach dem Ändern einer Zuweisung ein neues Zugriffstoken an. Überprüfen Sie bei der Problembehandlung die Zuweisung für den Agent-API-Dienstprinzipal und das roles-Claim des Tokens.

Mit einem neuen Token für die Agent-API und der zugewiesenen Agent.User Rolle gibt das Beispiel POST /tasks zurück 202 Accepted. Ohne ein Token erwarten Sie 401; ein andernfalls gültiges Token ohne diese Rolle wird abgelehnt, wenn der Mandant 403 sie ausgibt. Wenn eine Zuweisung erforderlich ist, kann Microsoft Entra ID die Anmelde- oder Tokenausstellung ablehnen, bevor die Anforderung Ihre API erreicht.