Partager via


Accorder ou révoquer des autorisations d’API par programmation

L’octroi d’autorisations d’API à une application cliente dans Microsoft Entra ID enregistre l’autorisation accordée en tant qu’objets que vous lisez, mettez à jour ou supprimez, comme toutes les autres données. Vous pouvez utiliser Microsoft Graph pour accorder ou révoquer des autorisations d’API pour une application. Cette méthode évite le consentement de l’administrateur interactif et est utile pour l’automatisation ou la gestion en bloc.

Les autorisations d’application, également appelées rôles d’application ou autorisations d’accès direct, permettent à une application d’appeler une API à l’aide de sa propre identité. Suivez ces étapes pour accorder ou révoquer des rôles d’application.

Attention

Soyez prudent ! Les autorisations accordées par programme ne sont pas sujettes à révision ou confirmation et prennent effet immédiatement.

Configuration requise

Pour suivre ces instructions, vous avez besoin des éléments suivants :

  • Locataire Microsoft Entra.
  • Pour exécuter les requêtes de cet article dans un contexte délégué. Procédez comme suit :
    • Connectez-vous à un client API comme Graph Explorer en tant qu’utilisateur disposant de privilèges pour créer des applications dans le locataire. Les privilèges permettant de créer des octrois d’autorisations peuvent être limités ou contrôlés dans votre locataire via des stratégies de consentement d’application configurées par l’administrateur.
    • Dans l’application à laquelle vous êtes connecté, consentez aux autorisations déléguées Application.Read.All et AppRoleAssignment.ReadWrite.All pour l’utilisateur connecté. Vous n’avez pas besoin de donner votre consentement au nom de votre organization.
  • Obtenez l’ID d’objet du principal de service client auquel vous accordez des rôles d’application. Dans cet article, le principal du service client est identifié par l’ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. Dans la centre d’administration Microsoft Entra, développez Identity>Applications> Applications >d’entrepriseApplications d’application pour rechercher le principal du service client. Sélectionnez-la et dans la page Vue d’ensemble , copiez la valeur ID d’objet.

Attention

Seuls les utilisateurs appropriés doivent accéder aux applications disposant de l’autorisation AppRoleAssignment.ReadWrite.All .

Étape 1 : Obtenir les rôles d’application du principal du service de ressources

Tout d’abord, recherchez les rôles d’application exposés par le principal du service de ressources. Les rôles d’application sont définis dans l’objet appRoles du principal de service. Cet article utilise le principal de service Microsoft Graph dans votre locataire comme principal du service de ressources.

Demande

La requête suivante récupère les rôles d’application définis par le principal de service Microsoft Graph dans le locataire.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id,displayName,appId,appRoles

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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"
                }
            ]
        }
    ]
}

Étape 2 : Accorder un rôle d’application à un principal de service client

Dans cette étape, accordez à votre application un rôle d’application exposé par Microsoft Graph, ce qui entraîne une attribution de rôle d’application. À l’étape 1, l’ID d’objet de Microsoft Graph est 7ea9e944-71ce-443d-811c-71e8047b557aet le rôle User.Read.All d’application est identifié par l’ID df021288-bdef-4463-88db-98f22de89214.

Demande

La requête suivante accorde à votre application cliente (le principal de l’ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94) un rôle d’application d’ID df021288-bdef-4463-88db-98f22de89214 exposé par un principal de service de ressources de l’ID 7ea9e944-71ce-443d-811c-71e8047b557a.

Remarque

Si vous utilisez le Kit de développement logiciel (SDK) Python, importez les bibliothèques suivantes :

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"
}

Réponse

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"
}

Confirmer l’attribution de rôle d’application

Vérifiez les principaux avec des attributions de rôles au principal du service de ressources en exécutant la requête suivante.

Demande

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

Réponse

L’objet response inclut une collection d’attributions de rôles d’application à votre principal de service de ressources et inclut l’attribution de rôle d’application que vous avez créée dans la requête précédente.

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"
        }
    ]
}

Étape 3 : Révoquer une attribution de rôle d’application à partir d’un principal de service client

Demande

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

Réponse

HTTP/1.1 204 No Content

Les autorisations déléguées, également appelées rôles d’application ou autorisations OAuth2, permettent à une application d’appeler une API pour le compte d’un utilisateur connecté. Suivez ces étapes pour accorder ou révoquer des autorisations déléguées.

Attention

Soyez prudent ! Les autorisations accordées par programme ne sont pas sujettes à révision ou confirmation. Ils prennent effet immédiatement.

Configuration requise

Pour suivre ces instructions, vous avez besoin des éléments suivants :

  • Locataire Microsoft Entra valide.
  • Pour exécuter les requêtes de cet article en tant qu’utilisateur. Procédez comme suit :
    • Connectez-vous à un client d’API comme Graph Explorer en tant qu’utilisateur avec le rôle d’administrateur d’application cloud Microsoft Entra. Ce rôle est le rôle le moins privilégié pour la création d’applications et l’octroi du consentement aux autorisations déléguées dans le locataire. Les privilèges permettant de créer des octrois d’autorisations peuvent être limités ou contrôlés dans votre locataire via des stratégies de consentement d’application configurées par l’administrateur.
    • Dans l’application à laquelle vous êtes connecté, consentez aux autorisations déléguées Application.Read.All et DelegatedPermissionGrant.ReadWrite.All pour l’utilisateur connecté. Vous n’avez pas besoin de donner votre consentement au nom de votre organization.
    • Obtenez l’ID d’objet du principal de service client auquel vous accordez des autorisations déléguées pour le compte d’un utilisateur. Dans cet article, le principal du service client est identifié par l’ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. Dans la centre d’administration Microsoft Entra, développez Identity>Applications> Applications >d’entrepriseApplications d’application pour rechercher le principal du service client. Sélectionnez-la et dans la page Vue d’ensemble , copiez la valeur ID d’objet.

Attention

Seuls les utilisateurs appropriés doivent accéder aux applications avec l’autorisation DelegatedPermissionGrant.ReadWrite.All .

Étape 1 : Obtenir les autorisations déléguées du principal du service de ressources

Tout d’abord, recherchez les autorisations déléguées exposées par le principal du service de ressources. Les autorisations déléguées sont définies dans l’objet oauth2PermissionScopes du principal de service. Cet article utilise le principal de service Microsoft Graph dans votre locataire comme principal du service de ressources.

Demande

Cette demande récupère les autorisations déléguées définies par le principal de service Microsoft Graph dans le locataire.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id,displayName,appId,oauth2PermissionScopes

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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"
                }                
            ]
        }
    ]
}

Étape 2 : Accorder une autorisation déléguée au principal de service client pour le compte d’un utilisateur

Demande

Dans cette étape, accordez à votre application une autorisation déléguée qui est exposée par Microsoft Graph pour le compte d’un utilisateur, ce qui entraîne une autorisation déléguée.

  • À l’étape 1, l’ID d’objet de Microsoft Graph dans le locataire est 7ea9e944-71ce-443d-811c-71e8047b557a
  • Les autorisations User.Read.All déléguées et Group.Read.All sont identifiées par les ID a154be20-db9c-4678-8ab7-66f6cc099a59 globaux uniques et 5f8c59db-677d-491f-a6b8-5f174b11ec1d respectivement.
  • Le principal est un utilisateur identifié par l’ID 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.
  • Le principal du service client est identifié par l’ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. Il s’agit de l’ID d’objet du principal de service et non de son 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"
}

La demande précédente accorde le consentement au nom d’un seul utilisateur, mais vous pouvez également accorder le consentement au nom de tous les utilisateurs du locataire. Le corps de la demande est similaire au corps de la demande précédent, sauf avec les modifications suivantes :

  • ConsentType est AllPrincipals, ce qui indique que vous consentez au nom de tous les utilisateurs du locataire.
  • La propriété principalId n’est pas fournie ou peut être null.

Voici un exemple de corps de demande pour l’octroi du consentement au nom de tous les utilisateurs :

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"
}

Réponse

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"
}

Si vous avez accordé le consentement pour tous les utilisateurs du locataire, le consentType dans l’objet response est AllPrincipals, et principalId est null.

Confirmer l’octroi d’autorisation

Vérifiez les principaux disposant d’autorisations déléguées au principal du service de ressources en exécutant la requête suivante.

Demande

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'

Réponse

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"
        }
    ]
}

Mettre à jour l’octroi d’autorisation

Pour ajouter des autorisations supplémentaires ou supprimer des autorisations pour le client sur le principal du service de ressources pour l’utilisateur, mettez à jour l’objet oauth2PermissionGrant comme indiqué dans la requête suivante. La requête retourne une 204 No Content réponse.

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

{
    "scope": "openid profile offline_access DelegatedPermissionGrant.ReadWrite.All AccessReview.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All"
}

Étape 3 : Révoquer les autorisations déléguées accordées à un principal de service pour le compte d’un utilisateur [facultatif]

Si un principal de service a reçu plusieurs octrois d’autorisations déléguées pour le compte d’un utilisateur, vous pouvez choisir de révoquer des octrois spécifiques ou tous les octrois. Utilisez cette méthode pour supprimer et révoquer le consentement pour les autorisations déléguées que vous avez attribuées au principal du service client.

  • Pour révoquer un ou plusieurs octrois, exécutez une requête PATCH sur l’objet oauth2PermissionGrant et spécifiez uniquement les autorisations déléguées à conserver dans le paramètre scope .
  • Pour révoquer tous les octrois, envoyez une demande DELETE à l’objet oauth2PermissionGrant.

Demande

Cette demande révoque tous les octrois d’autorisations, à l’exception de l’octroi d’autorisation User.Read.All . Il supprime les autorisations et révoque le consentement accordé précédemment.

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

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

Réponse

HTTP/1.1 204 No Content

Demande

Cette demande révoque toutes les autorisations accordées à un principal de service pour le compte d’un utilisateur.

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

Réponse

HTTP/1.1 204 No Content