Freigeben über


Programmgesteuertes Erteilen oder Widerrufen von API-Berechtigungen

Wenn Sie einer Client-App api-Berechtigungen in Microsoft Entra ID erteilen, werden die Berechtigungserteilungen als Objekte aufgezeichnet, auf die wie alle anderen Daten zugegriffen, aktualisiert oder gelöscht werden kann. Die Verwendung von Microsoft Graph zum direkten Erstellen von Berechtigungserteilungen ist eine programmgesteuerte Alternative zur interaktiven Zustimmung und kann für Automatisierungsszenarien, Massenverwaltung oder andere benutzerdefinierte Vorgänge in Ihrer Organisation nützlich sein.

In diesem Artikel erfahren Sie, wie Sie App-Rollen für eine App mithilfe von Microsoft Graph gewähren und widerrufen. App-Rollen, auch als Anwendungsberechtigungen oder Direktzugriffsberechtigungen bezeichnet, ermöglichen es einer App, eine API mit ihrer eigenen Identität aufzurufen. Erfahren Sie mehr über Anwendungsberechtigungen.

Achtung

Gehen Sie hierbei vorsichtig vor. Berechtigungen, die programmgesteuert gewährt werden, unterliegen nicht der Überprüfung oder Bestätigung. Sie treten sofort in Kraft.

Voraussetzungen

Zum Ausführen dieser Anweisungen benötigen Sie die folgenden Ressourcen und Berechtigungen:

  • Ein gültiger Microsoft Entra-Mandant.
  • Sie führen die Anforderungen in diesem Artikel in einem delegierten Kontext aus. Sie müssen die folgenden Schritte ausführen:
    • Melden Sie sich bei einem API-Client wie Graph-Explorer als Benutzer mit Berechtigungen zum Erstellen von Anwendungen im Mandanten an. Die Berechtigungen zum Erstellen von Berechtigungserteilungen können in Ihrem Mandanten durch vom Administrator konfigurierte App-Zustimmungsrichtlinien eingeschränkt oder gesteuert werden.
    • Stimmen Sie in der App, bei der Sie angemeldet sind, den delegierten Berechtigungen Application.Read.All und AppRoleAssignment.ReadWrite.All im Namen des angemeldeten Benutzers zu. Sie müssen nicht im Namen Ihrer Organisation zustimmen.
    • Rufen Sie die Objekt-ID des Clientdienstprinzipals ab, dem Sie App-Rollen gewähren. In diesem Artikel wird der Clientdienstprinzipal durch die ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94identifiziert. Erweitern Sie im Microsoft Entra Admin Center das Menü >Identität, erweitern Sie Anwendungen> und wählen Sie Unternehmensanwendungen>App-Anwendungen aus, um den Clientdienstprinzipal zu suchen. Wählen Sie ihn aus, und kopieren Sie auf der Seite Übersicht den Wert der Objekt-ID.

Achtung

Apps, denen die Berechtigung AppRoleAssignment.ReadWrite.All gewährt wurde, sollte nur von entsprechenden Benutzern aufgerufen werden.

Schritt 1: Abrufen der appRoles des Ressourcendienstprinzipals

Bevor Sie App-Rollen erteilen können, müssen Sie zuerst den Ressourcendienstprinzipal identifizieren, der die App-Rollen verfügbar macht, die Sie gewähren möchten. App-Rollen werden im appRoles-Objekt eines Dienstprinzipals definiert. In diesem Artikel verwenden Sie den Microsoft Graph-Dienstprinzipal in Ihrem Mandanten als Ressourcendienstprinzipal.

Anforderung

Die folgende Anforderung ruft die App-Rollen ab, die vom Microsoft Graph-Dienstprinzipal im Mandanten definiert sind.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,appRoles

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,appRoles)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "appRoles": [
                {
                    "allowedMemberTypes": [
                        "Application"
                    ],
                    "description": "Allows the app to read user profiles without a signed in user.",
                    "displayName": "Read all users' full profiles",
                    "id": "df021288-bdef-4463-88db-98f22de89214",
                    "isEnabled": true,
                    "origin": "Application",
                    "value": "User.Read.All"
                }
            ]
        }
    ]
}

Schritt 2: Gewähren einer App-Rolle für einen Clientdienstprinzipal

In diesem Schritt gewähren Sie Ihrer App eine App-Rolle, die von Microsoft Graph verfügbar gemacht wird, was zu einer App-Rollenzuweisung führt. In Schritt 1 lautet 7ea9e944-71ce-443d-811c-71e8047b557a die Objekt-ID von Microsoft Graph, und die App-Rolle User.Read.All wird durch die ID df021288-bdef-4463-88db-98f22de89214identifiziert.

Anforderung

Die folgende Anforderung gewährt Ihrer Client-App (dem Prinzipal der ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94) eine App-Rolle der ID df021288-bdef-4463-88db-98f22de89214 , die von einem Ressourcendienstprinzipal der ID 7ea9e944-71ce-443d-811c-71e8047b557averfügbar gemacht wird.

Hinweis

Wenn Sie das Python SDK verwenden, importieren Sie die folgenden Bibliotheken:

from msgraph.generated.models.app_role_assignment import AppRoleAssignment
from msgraph.generated.models.service_principal import ServicePrincipal
POST https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo
Content-Type: application/json

{
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214"
}

Antwort

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo/$entity",
    "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
    "deletedDateTime": null,
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
    "createdDateTime": "2022-05-18T15:37:21.8215423Z",
    "principalDisplayName": "My application",
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "principalType": "ServicePrincipal",
    "resourceDisplayName": "Microsoft Graph",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
}

Bestätigen der App-Rollenzuweisung

Um die Prinzipale mit Rollenzuweisungen an den Ressourcendienstprinzipal zu überprüfen, führen Sie die folgende Anforderung aus.

Anforderung

GET https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo

Antwort

Das Antwortobjekt enthält eine Sammlung von App-Rollenzuweisungen für Ihren Ressourcendienstprinzipal und die App-Rollenzuweisung, die Sie in der vorherigen Anforderung erstellt haben.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo",
    "value": [
        {
            "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
            "deletedDateTime": null,
            "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
            "createdDateTime": "2022-05-18T15:37:21.8997216Z",
            "principalDisplayName": "My application",
            "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "principalType": "ServicePrincipal",
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
        }
    ]
}

Schritt 3: Widerrufen einer App-Rollenzuweisung für einen Clientdienstprinzipal

Anforderung

DELETE https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo/47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M

Antwort

HTTP/1.1 204 No Content

Zusammenfassung

Sie haben gelernt, wie Sie App-Rollenzuweisungen für einen Dienstprinzipal verwalten. Diese Methode zum Erteilen von Berechtigungen mithilfe von Microsoft Graph ist eine alternative interaktive Zustimmung und sollte mit Vorsicht verwendet werden.

In diesem Artikel erfahren Sie, wie Sie delegierte Berechtigungen für eine App mithilfe von Microsoft Graph gewähren und widerrufen. Delegierte Berechtigungen, auch als Bereiche oder OAuth2-Berechtigungen bezeichnet, ermöglichen es einer App, eine API im Namen eines angemeldeten Benutzers aufzurufen. Erfahren Sie mehr über delegierte Berechtigungen.

Achtung

Gehen Sie hierbei vorsichtig vor. Berechtigungen, die programmgesteuert gewährt werden, unterliegen nicht der Überprüfung oder Bestätigung. Sie treten sofort in Kraft.

Voraussetzungen

Zum Ausführen dieser Anweisungen benötigen Sie die folgenden Ressourcen und Berechtigungen:

  • Ein gültiger Microsoft Entra-Mandant.
  • Sie führen die Anforderungen in diesem Artikel als Benutzer aus. Sie müssen die folgenden Schritte ausführen:
    • Melden Sie sich bei einem API-Client wie Graph-Explorer als Benutzer mit der Microsoft Entra-Rolle Cloudanwendungsadministrator an. Dies ist die Rolle mit den geringsten Berechtigungen zum Erstellen von Anwendungen und Erteilen der Zustimmung zu delegierten Berechtigungen im Mandanten. Die Berechtigungen zum Erstellen von Berechtigungserteilungen können in Ihrem Mandanten durch vom Administrator konfigurierte App-Zustimmungsrichtlinien eingeschränkt oder gesteuert werden.
    • Stimmen Sie in der App, bei der Sie angemeldet sind, den delegierten Berechtigungen Application.Read.All, DelegatedPermissionGrant.ReadWrite.All im Namen des angemeldeten Benutzers zu. Sie müssen nicht im Namen Ihrer Organisation zustimmen.
    • Rufen Sie die Objekt-ID des Clientdienstprinzipals ab, dem Sie delegierte Berechtigungen im Namen eines Benutzers erteilen. In diesem Artikel wird der Clientdienstprinzipal durch die ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94identifiziert. Erweitern Sie im Microsoft Entra Admin Center das Menü >Identität, erweitern Sie Anwendungen> und wählen Sie Unternehmensanwendungen>App-Anwendungen aus, um den Clientdienstprinzipal zu suchen. Wählen Sie ihn aus, und kopieren Sie auf der Seite Übersicht den Wert der Objekt-ID.

Achtung

Apps, denen die Berechtigung DelegatedPermissionGrant.ReadWrite.All gewährt wurde, sollte nur von geeigneten Benutzern aufgerufen werden.

Schritt 1: Abrufen der delegierten Berechtigungen des Ressourcendienstprinzipals

Bevor Sie delegierte Berechtigungen erteilen können, müssen Sie zunächst den Ressourcendienstprinzipal identifizieren, der die delegierten Berechtigungen verfügbar macht, die Sie gewähren möchten. Delegierte Berechtigungen werden im oauth2PermissionScopes-Objekt eines Dienstprinzipals definiert. In diesem Artikel verwenden Sie den Microsoft Graph-Dienstprinzipal in Ihrem Mandanten als Ressourcendienstprinzipal.

Anforderung

Die folgende Anforderung ruft die delegierten Berechtigungen ab, die vom Microsoft Graph-Dienstprinzipal im Mandanten definiert sind.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,oauth2PermissionScopes)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "oauth2PermissionScopes": [
                {
                    "adminConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.",
                    "adminConsentDisplayName": "Read all users' full profiles",
                    "id": "a154be20-db9c-4678-8ab7-66f6cc099a59",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on your behalf.",
                    "userConsentDisplayName": "Read all users' full profiles",
                    "value": "User.Read.All"
                },
                {
                    "adminConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user.  Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access. ",
                    "adminConsentDisplayName": "Read all groups",
                    "id": "5f8c59db-677d-491f-a6b8-5f174b11ec1d",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on your behalf.  Also allows the app to read calendar, conversations, files, and other group content for all groups you can access.  ",
                    "userConsentDisplayName": "Read all groups",
                    "value": "Group.Read.All"
                }                
            ]
        }
    ]
}

Schritt 2: Erteilen einer delegierten Berechtigung für den Clientdienstprinzipal im Namen eines Benutzers

Anforderung

In diesem Schritt erteilen Sie Ihrer App im Namen eines Benutzers eine delegierte Berechtigung, die von Microsoft Graph verfügbar gemacht wird, was zu einer delegierten Berechtigungserteilung führt.

  • Ab Schritt 1 lautet die Objekt-ID von Microsoft Graph im Mandanten. 7ea9e944-71ce-443d-811c-71e8047b557a
  • Die delegierten Berechtigungen User.Read.All und Group.Read.All werden durch die global eindeutigen IDs a154be20-db9c-4678-8ab7-66f6cc099a59 bzw 5f8c59db-677d-491f-a6b8-5f174b11ec1d . identifiziert.
  • Der Prinzipal ist ein Benutzer, der durch die ID 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5identifiziert wird.
  • Der Clientdienstprinzipal wird durch die ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94identifiziert. Dies ist die Objekt-ID des Dienstprinzipals und nicht seine appId.
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "scope": "User.Read.All Group.Read.All"
}

Während die vorherige Anforderung die Zustimmung im Namen eines einzelnen Benutzers erteilt, können Sie die Zustimmung im Namen aller Benutzer im Mandanten erteilen. Der Anforderungstext ähnelt dem vorherigen Anforderungstext, mit Ausnahme der folgenden Änderungen:

  • ConsentType ist AllPrincipals, was angibt, dass Sie im Namen aller Benutzer im Mandanten zustimmen.
  • Die principalId-Eigenschaft wird nicht angegeben oder kann sein null.

Ein Beispiel für den Anforderungstext zum Erteilen der Zustimmung im Namen aller Benutzer lautet wie folgt:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "AllPrincipals",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Antwort

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants/$entity",
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Wenn Sie die Zustimmung für alle Benutzer im Mandanten erteilt haben, wäre AllPrincipalsder consentType im Antwortobjekt , und die principalId wäre null.

Bestätigen der Berechtigungserteilung

Um die dem Dienstprinzipal im Namen des Benutzers zugewiesenen delegierten Berechtigungen zu überprüfen, führen Sie die folgende Anforderung aus.

Anforderung

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and principalId eq '3fbd929d-8c56-4462-851e-0eb9a7b3a2a5' and consentType eq 'Principal'

Antwort

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants",
    "value": [
        {
            "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "consentType": "Principal",
            "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
            "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "scope": "User.Read.All Group.Read.All"
        }
    ]
}

Schritt 3: Widerrufen delegierter Berechtigungen, die einem Dienstprinzipal im Namen eines Benutzers erteilt wurden [Optional]

Wenn einem Dienstprinzipal mehrere delegierte Berechtigungserteilungen im Namen eines Benutzers gewährt wurden, können Sie entweder bestimmte Oder alle Zuweisungen widerrufen. Verwenden Sie diese Methode, um die Zustimmung für die delegierten Berechtigungen zu entfernen und zu widerrufen, die Sie dem Clientdienstprinzipal zugewiesen haben.

  • Um eine oder einige Zuweisungen zu widerrufen, führen Sie eine PATCH-Anforderung für das oauth2PermissionGrant-Objekt aus, und geben Sie nur die delegierten Berechtigungen an, die im Scope-Parameter beibehalten werden sollen.
  • Um alle Berechtigungen aufzuheben, führen Sie eine DELETE-Anforderung für das oauth2PermissionGrant-Objekt aus.

Anforderung

Die folgende Anforderung widerruft alle Berechtigungserteilungen und behält nur die User.Read.All Berechtigungsgewährung bei. Die Berechtigungen werden entfernt, und die zuvor erteilte Zustimmung wird widerrufen.

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl
Content-Type: application/json

{
    "scope": "User.Read.All"
}

Antwort

HTTP/1.1 204 No Content

Anforderung

Die folgende Anforderung widerruft alle Berechtigungserteilungen für einen Dienstprinzipal im Namen eines Benutzers.

DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl

Antwort

HTTP/1.1 204 No Content

Zusammenfassung

Sie haben einem Dienstprinzipal delegierte Berechtigungen (oder Bereiche) erteilt. Diese Methode zum Erteilen von Berechtigungen mithilfe von Microsoft Graph ist eine Alternative zur interaktiven Zustimmung und sollte mit Vorsicht verwendet werden.