Passer en revue l’accès invité aux groupes à l’aide des API de révisions d’accès

  • Article

L’API révisions d’accès dans Microsoft Graph permet aux organisations d’auditer et d’attester de l’accès que les identités (également appelées principaux) sont affectées aux ressources dans le organization. Avec B2B Collaboration, vous pouvez utiliser des groupes Microsoft 365 pour gérer efficacement l’accès des invités à des ressources telles que des fichiers, des notes, des calendriers et même des conversations Teams. Et à l’aide de l’API de révisions d’accès, les organisations peuvent régulièrement attester des principaux qui ont accès à ces groupes et, par extension, d’autres ressources dans le organization.

Dans ce tutoriel, vous apprenez à effectuer les opérations suivantes :

  • Créez une révision d’accès périodique des groupes Microsoft 365 avec des invités.
  • Examiner les décisions appliquées aux révisions d’accès.

Configuration requise

Pour suivre ce didacticiel, vous avez besoin des ressources et privilèges suivants :

  • Un locataire Microsoft Entra opérationnel avec une licence Microsoft Entra ID P2 ou Gouvernance Microsoft Entra ID activée.
  • Un invité de test et un groupe Microsoft 365 de test dans votre locataire. L’invité doit être membre du groupe Microsoft 365.
  • Connectez-vous à un client API tel que Graph Explorer d’appeler Microsoft Graph avec un compte qui a au moins le rôle Administrateur de gouvernance des identités.
  • Accordez-vous les autorisations déléguées suivantes : AccessReview.ReadWrite.All.

Étape 1 : Créer une révision d’accès pour tous les groupes Microsoft 365 avec des invités

La série de révision d’accès suivante utilise les paramètres suivants :

  • Il s’agit d’une révision d’accès périodique et examinée tous les trimestres.
  • Les propriétaires du groupe sont les décideurs.
  • L’étendue de la révision est limitée aux seuls groupes Microsoft 365 avec des invités.
  • Il définit un utilisateur comme réviseur de secours qui peut examiner l’accès au cas où aucun propriétaire n’est attribué au groupe.
  • autoApplyDecisionsEnabled a la valeur true. Dans ce cas, les décisions sont appliquées automatiquement une fois que le réviseur a terminé la révision d’accès ou que la durée de la révision d’accès se termine. S’il n’est pas activé, un utilisateur doit appliquer les décisions manuellement une fois la révision terminée.
  • applyActions a la valeur removeAccessApplyAction. Cette action supprime les invités refusés du groupe. L’invité peut toujours se connecter à votre locataire, mais ne sera pas membre du groupe ou ne disposera pas des privilèges d’accès accordés par le biais du groupe.

Demande

Dans cet appel, remplacez les valeurs suivantes :

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 avec l’ID du réviseur de secours.
  • Valeur de startDate avec la date du jour et valeur de endDate avec une date un an à partir de la date de début.
POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Guest access to marketing group",
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/v1.0/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "fallbackReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 3,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": "P30D",
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "endDate",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2025-03-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

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#identityGovernance/accessReviews/definitions/$entity",
    "id": "c22ae540-b89a-4d24-bac0-4ef35e6591ea",
    "displayName": "Guest access to marketing group",
    "createdDateTime": null,
    "lastModifiedDateTime": null,
    "status": "NotStarted",
    "descriptionForAdmins": null,
    "descriptionForReviewers": null,
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "instanceEnumerationScope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "fallbackReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 3,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": "P30D",
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "endDate",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2025-03-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

Étape 2 : Répertorier les instances de la révision d’accès

La requête suivante répertorie toutes les instances de la définition de révision d’accès. S’il existe plusieurs groupes Microsoft 365 avec des invités dans votre locataire, cette demande retourne une instance pour chaque groupe Microsoft 365 avec des invités.

Demande

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances

Réponse

Dans cette réponse, l’étendue inclut le groupe de tests, car il a un invité. Dans cette réponse, le instance de révision d’accès est actuellement InProgress. Étant donné qu’il s’agit d’une révision trimestrielle, une nouvelle instance de révision est créée automatiquement tous les trois mois et les réviseurs peuvent appliquer de nouvelles décisions.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances",
    "value": [
        {
            "id": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "startDateTime": "2024-03-21T17:00:36.96Z",
            "endDateTime": "2024-03-24T17:00:36.96Z",
            "status": "InProgress",
            "scope": {
                "query": "/groups/59ab642a-2776-4e32-9b68-9ff7a47b7f6a/members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
                "queryType": "MicrosoftGraph"
            }
        }
    ]
}

Étape 3 : Obtenir des décisions

Obtenez les décisions prises pour la instance d’une révision d’accès. Dans une révision trimestrielle comme celle-ci, et tant que la révision d’accès est toujours active :

  • Tous les trois mois, une nouvelle instance de révision est créée.
  • Les réviseurs doivent appliquer de nouvelles décisions pour les nouvelles instances.

Demande

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances/6392b1a7-9c25-4844-83e5-34e23c88e16a/decisions

Réponse

La réponse suivante montre la décision prise pour la instance de l’examen.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances('6392b1a7-9c25-4844-83e5-34e23c88e16a')/decisions",
    "@odata.count": 1,
    "value": [
        {
            "id": "0e76ee07-b4c6-469e-bc9d-e73fc9a8d660",
            "accessReviewId": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "reviewedDateTime": "2021-02-10T17:06:26.147Z",
            "decision": "Approve",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Deny",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "AAD Access Reviews",
                "userPrincipalName": "AAD Access Reviews"
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "target": {
                "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItemUserTarget",
                "userId": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20",
                "userDisplayName": "John Doe (Tailspin Toys)",
                "userPrincipalName": "john@tailspintoys.com"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20",
                "displayName": "John Doe (Tailspin Toys)",
                "userPrincipalName": "john@tailspintoys.com"
            }
        }
    ]
}

Étape 4 : Nettoyer les ressources

Dans cette étape, vous supprimez la définition de révision d’accès. Étant donné que la définition de la planification de révision d’accès est le blueprint de la révision d’accès, la suppression de la définition supprime les paramètres, instances et décisions associés. La requête retourne une 204 No Content réponse.

DELETE https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea

Contenu connexe