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

Lorsque vous accordez des autorisations d’API à une application cliente dans l’ID Microsoft Entra, les autorisations sont enregistrées en tant qu’objets accessibles, mis à jour ou supprimés comme toutes les autres données. L’utilisation de Microsoft Graph pour créer directement des octrois d’autorisations est une alternative programmatique au consentement interactif et peut être utile pour les scénarios d’automatisation, la gestion en bloc ou d’autres opérations personnalisées dans votre organisation.

Dans cet article, vous allez apprendre à accorder et révoquer des rôles d’application pour une application à l’aide de Microsoft Graph. Les rôles d’application, également appelés autorisations d’application, ou autorisations d’accès direct, permettent à une application d’appeler une API avec sa propre identité. En savoir plus sur les autorisations d’application.

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 ressources et privilèges suivants :

  • Un locataire Microsoft Entra valide.
  • Vous exécutez les requêtes de cet article dans un contexte délégué. Vous devez effectuer les étapes suivantes :
    • Connectez-vous à un client API tel que l’Explorateur Graph en tant qu’utilisateur avec des 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 par le biais de 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 au nom de l’utilisateur connecté. Vous n’avez pas besoin de donner votre consentement au nom de votre organisation.
    • 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 le Centre d’administration Microsoft Entra, développez le menu >Identité, développez Applications>, puis sélectionnez 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

Les applications qui ont reçu l’autorisation AppRoleAssignment.ReadWrite.All ne doivent être accessibles qu’aux utilisateurs appropriés.

Étape 1 : Obtenir les appRoles du principal du service de ressources

Avant de pouvoir accorder des rôles d’application, vous devez d’abord identifier le principal de service de ressources qui expose les rôles d’application que vous souhaitez accorder. Les rôles d’application sont définis dans l’objet appRoles d’un principal de service. Dans cet article, vous utilisez le principal de service Microsoft Graph dans votre locataire en tant que 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=displayName eq 'Microsoft Graph'&$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, vous 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-71e8047b557a et 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

Pour vérifier les principaux avec des attributions de rôles au principal du service de ressources, exécutez 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

Conclusion

Vous avez appris à gérer les octrois de rôles d’application pour un principal de service. Cette méthode d’octroi d’autorisations à l’aide de Microsoft Graph est un consentement interactif alternatif et doit être utilisée avec prudence.

Dans cet article, vous allez apprendre à accorder et révoquer des autorisations déléguées pour une application à l’aide de Microsoft Graph. Les autorisations déléguées, également appelées étendues, ou autorisations OAuth2, permettent à une application d’appeler une API pour le compte d’un utilisateur connecté. En savoir plus sur les 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 ressources et privilèges suivants :

  • Un locataire Microsoft Entra valide.
  • Vous exécutez les requêtes de cet article en tant qu’utilisateur. Vous devez effectuer les étapes suivantes :
    • Connectez-vous à un client API tel que l’Explorateur Graph en tant qu’utilisateur avec le rôle Administrateur d’applications cloud Microsoft Entra, qui est le rôle de privilège minimum 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 par le biais de 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, DelegatedPermissionGrant.ReadWrite.All au nom de l’utilisateur connecté. Vous n’avez pas besoin de donner votre consentement au nom de votre organisation.
    • 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 le Centre d’administration Microsoft Entra, développez le menu >Identité, développez Applications>, puis sélectionnez 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

Les applications qui ont reçu l’autorisation DelegatedPermissionGrant.ReadWrite.All ne doivent être accessibles que par les utilisateurs appropriés.

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

Avant de pouvoir accorder des autorisations déléguées, vous devez d’abord identifier le principal du service de ressources qui expose les autorisations déléguées que vous souhaitez accorder. Les autorisations déléguées sont définies dans l’objet oauth2PermissionScopes d’un principal de service. Dans cet article, vous utilisez le principal de service Microsoft Graph dans votre locataire en tant que principal du service de ressources.

Demande

La requête suivante 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=displayName eq 'Microsoft Graph'&$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, vous accordez à votre application, au nom d’un utilisateur, une autorisation déléguée qui est exposée par Microsoft Graph, 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"
}

Bien que la demande précédente accorde le consentement au nom d’un seul utilisateur, vous pouvez choisir d’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 accorder le 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

Pour vérifier les autorisations déléguées attribuées au principal de service au nom de l’utilisateur, vous exécutez 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"
        }
    ]
}

É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 demande 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, exécutez une requête DELETE sur l’objet oauth2PermissionGrant.

Demande

La requête suivante révoque tous les octrois d’autorisations et conserve uniquement l’octroi d’autorisation User.Read.All . Les autorisations sont supprimées et le consentement précédemment accordé est révoqué.

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

La requête suivante 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

Conclusion

Vous avez accordé des autorisations déléguées (ou des étendues) à un principal de service. Cette méthode d’octroi d’autorisations à l’aide de Microsoft Graph est une alternative au consentement interactif et doit être utilisée avec prudence.