Gérer les alertes de sécurité pour les rôles Microsoft Entra à l’aide d’API PIM

Privileged Identity Management (PIM) pour les rôles Microsoft Entra génère des alertes lorsqu’il détecte des paramètres suspects ou non sécurisés pour Microsoft Entra rôles dans votre locataire. Cet article décrit les scénarios de gestion des alertes PIM à l’aide de Microsoft Graph.

Pour plus d’informations sur les ressources d’API pour la gestion des alertes de sécurité PIM, consultez Alertes de sécurité pour les rôles Microsoft Entra.

Remarque

Les alertes de sécurité PIM se trouvent actuellement uniquement sur le point de /beta terminaison et ne sont disponibles que pour les rôles Microsoft Entra.

Configuration requise

  • Avoir une compréhension de PIM pour les API de rôles Microsoft Entra.
  • Dans cet article, vous appelez les API dans un scénario délégué.
    • Connectez-vous à un client API tel que Graph Explorer avec des privilèges d’administration pour gérer les règles PIM. Le rôle Administrateur de rôle privilégié est le rôle le moins privilégié suffisant pour gérer les règles PIM.
    • Accordez-vous l’autorisation déléguée RoleManagementAlert.ReadWrite.Directory .

Répertorier toutes les alertes PIM

Demande

Seules les alertes relatives aux rôles intégrés Microsoft Entra et étendues au locataire (/) sont prises en charge et peuvent être récupérées à l’aide de la requête suivante. Le fait de ne pas spécifier l’étendue et le type d’étendue appropriés retournent une 400 Bad Request erreur.

GET https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts?$filter=scopeId eq '/' and scopeType eq 'DirectoryRole'

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 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/roleManagementAlerts/alerts",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/roleManagementAlerts/alerts?$select=alertDefinitionId,incidentCount",
    "value": [
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_InvalidLicenseAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_InvalidLicenseAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 0,
            "isActive": false,
            "lastModifiedDateTime": "0001-01-01T08:00:00Z",
            "lastScannedDateTime": "2023-09-20T17:05:57.457Z"
        },
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_NoMfaOnRoleActivationAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_NoMfaOnRoleActivationAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 0,
            "isActive": false,
            "lastModifiedDateTime": "0001-01-01T08:00:00Z",
            "lastScannedDateTime": "2023-09-20T17:06:01.25Z"
        },
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RedundantAssignmentAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RedundantAssignmentAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 0,
            "isActive": false,
            "lastModifiedDateTime": "0001-01-01T08:00:00Z",
            "lastScannedDateTime": "2023-09-20T17:06:00.603Z"
        },
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 0,
            "isActive": false,
            "lastModifiedDateTime": "0001-01-01T08:00:00Z",
            "lastScannedDateTime": "2023-09-20T17:05:57.78Z"
        },
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_SequentialActivationRenewalsAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_SequentialActivationRenewalsAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 0,
            "isActive": false,
            "lastModifiedDateTime": "0001-01-01T08:00:00Z",
            "lastScannedDateTime": "2023-09-20T17:05:57.857Z"
        },
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_StaleSignInAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_StaleSignInAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 0,
            "isActive": false,
            "lastModifiedDateTime": "0001-01-01T08:00:00Z",
            "lastScannedDateTime": "2023-09-20T17:06:03.117Z"
        },
        {
            "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
            "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "incidentCount": 7,
            "isActive": true,
            "lastModifiedDateTime": "2023-09-20T17:06:01.363Z",
            "lastScannedDateTime": "2023-09-20T17:06:01.363Z"
        }
    ]
}

Obtenir une alerte PIM

Demande

GET https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert

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 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/roleManagementAlerts/alerts/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/roleManagementAlerts/alerts('<key>')?$select=alertDefinitionId,incidentCount",
    "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
    "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
    "scopeId": "/",
    "scopeType": "DirectoryRole",
    "incidentCount": 7,
    "isActive": true,
    "lastModifiedDateTime": "2023-09-20T17:06:01.363Z",
    "lastScannedDateTime": "2023-09-20T17:06:01.363Z"
}

Obtenir une alerte de sécurité et développer les relations pour lire la définition, la configuration et les incidents

Demande

Vous pouvez lire une alerte de sécurité et sa définition, sa configuration et les incidents associés dans le locataire dans une seule requête. Développez toutes les relations à l’aide du caractère générique (*), ou développez les relations individuellement à l’aide $expand=alertDefinition,alertConfiguration,alertIncidentsde . Cette requête vous permet d’éviter de récupérer la définition, la configuration et les incidents d’alerte séparément, puis de les corréler à l’alerte.

GET https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert?$expand=*

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 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/roleManagementAlerts/alerts(alertConfiguration(),alertDefinition(),alertIncidents())/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/roleManagementAlerts/alerts('<key>')?$select=alertDefinitionId,incidentCount",
    "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
    "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
    "scopeId": "/",
    "scopeType": "DirectoryRole",
    "incidentCount": 7,
    "isActive": true,
    "lastModifiedDateTime": "2023-09-20T17:06:01.363Z",
    "lastScannedDateTime": "2023-09-20T17:06:01.363Z",
    "alertConfiguration": {
        "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertConfiguration",
        "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
        "alertDefinitionId": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
        "scopeType": "DirectoryRole",
        "scopeId": "/",
        "isEnabled": true,
        "globalAdminCountThreshold": 3,
        "percentageOfGlobalAdminsOutOfRolesThreshold": 10
    },
    "alertDefinition": {
        "id": "DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert",
        "displayName": "There are too many global administrators",
        "scopeType": "DirectoryRole",
        "scopeId": "/",
        "description": "The percentage of global administrators is high, relative to other privileged roles. It is recommended to use least privileged roles, with just enough privileges to perform the required tasks.",
        "severityLevel": "low",
        "securityImpact": "Global administrator is the highest privileged role. If a Global Administrator is compromised, the attacker gains access to all of their permissions, which puts your whole system at risk.",
        "mitigationSteps": "·Review the users in the list and remove any that do not absolutely need the Global Administrator role.·Assign lower privileged roles to these users instead.",
        "howToPrevent": "Assign users the least privileged role they need.",
        "isRemediatable": true,
        "isConfigurable": true
    },
    "alertIncidents@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/roleManagementAlerts/alerts('DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert')/alertIncidents",
    "alertIncidents": [
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "60caa50f-7863-4f48-bf97-2a8fb990b681",
            "assigneeId": "60caa50f-7863-4f48-bf97-2a8fb990b681",
            "assigneeDisplayName": "MOD Administrator",
            "assigneeUserPrincipalName": "admin@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "6dd82b18-d45f-4346-bf87-e9700db41849",
            "assigneeId": "6dd82b18-d45f-4346-bf87-e9700db41849",
            "assigneeDisplayName": "Nestor Wilke",
            "assigneeUserPrincipalName": "NestorW@Contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "87404028-0c5b-4d0a-9d9d-3150e4b5ce74",
            "assigneeId": "87404028-0c5b-4d0a-9d9d-3150e4b5ce74",
            "assigneeDisplayName": "Isaiah Langer",
            "assigneeUserPrincipalName": "IsaiahL@Contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "143ebd3d-e522-485c-aa52-94675ee83e6c",
            "assigneeId": "143ebd3d-e522-485c-aa52-94675ee83e6c",
            "assigneeDisplayName": "Lidia Holloway",
            "assigneeUserPrincipalName": "LidiaH@Contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "2832ca72-700e-4f20-a3c7-97028803a95b",
            "assigneeId": "2832ca72-700e-4f20-a3c7-97028803a95b",
            "assigneeDisplayName": "Microsoft Service Account",
            "assigneeUserPrincipalName": "ms-serviceaccount@Contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "31336492-bf1b-48bb-a072-e554e4f992fc",
            "assigneeId": "31336492-bf1b-48bb-a072-e554e4f992fc",
            "assigneeDisplayName": "Megan Bowen",
            "assigneeUserPrincipalName": "MeganB@Contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "308110a6-4f71-49c2-bbef-c6dbda50b392",
            "assigneeId": "308110a6-4f71-49c2-bbef-c6dbda50b392",
            "assigneeDisplayName": "Allan Deyoung",
            "assigneeUserPrincipalName": "AllanD@Contoso.com"
        }
    ]
}

Obtenir les détails des incidents qui ont déclenché une alerte

Demande

GET https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert/alertIncidents

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 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/roleManagementAlerts/alerts('DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert')/alertIncidents",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/roleManagementAlerts/alerts('<key>')/alertIncidents?$select=id",
    "value": [
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "143ebd3d-e522-485c-aa52-94675ee83e6c",
            "assigneeId": "143ebd3d-e522-485c-aa52-94675ee83e6c",
            "assigneeDisplayName": "Lidia Holloway",
            "assigneeUserPrincipalName": "LidiaH@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "2832ca72-700e-4f20-a3c7-97028803a95b",
            "assigneeId": "2832ca72-700e-4f20-a3c7-97028803a95b",
            "assigneeDisplayName": "Microsoft Service Account",
            "assigneeUserPrincipalName": "ms-serviceaccount@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "308110a6-4f71-49c2-bbef-c6dbda50b392",
            "assigneeId": "308110a6-4f71-49c2-bbef-c6dbda50b392",
            "assigneeDisplayName": "Allan Deyoung",
            "assigneeUserPrincipalName": "AllanD@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "31336492-bf1b-48bb-a072-e554e4f992fc",
            "assigneeId": "31336492-bf1b-48bb-a072-e554e4f992fc",
            "assigneeDisplayName": "Megan Bowen",
            "assigneeUserPrincipalName": "MeganB@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "60caa50f-7863-4f48-bf97-2a8fb990b681",
            "assigneeId": "60caa50f-7863-4f48-bf97-2a8fb990b681",
            "assigneeDisplayName": "MOD Administrator",
            "assigneeUserPrincipalName": "admin@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "6dd82b18-d45f-4346-bf87-e9700db41849",
            "assigneeId": "6dd82b18-d45f-4346-bf87-e9700db41849",
            "assigneeDisplayName": "Nestor Wilke",
            "assigneeUserPrincipalName": "NestorW@contoso.com"
        },
        {
            "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertIncident",
            "id": "87404028-0c5b-4d0a-9d9d-3150e4b5ce74",
            "assigneeId": "87404028-0c5b-4d0a-9d9d-3150e4b5ce74",
            "assigneeDisplayName": "Isaiah Langer",
            "assigneeUserPrincipalName": "IsaiahL@contoso.com"
        }
    ]
}

Ignorer une alerte

Vous ignorez une alerte en affectant à la propriété isActive la valeur true. Lorsque vous ignorez une alerte, PIM n’analyse plus l’alerte dans votre locataire à la recherche d’incidents. Les incidents existants peuvent toujours être interrogés, mais aucun nouvel incident n’est généré. Vous pouvez réactiver l’alerte en définissant la isActive propriété sur true ou en actualisant le type d’alerte.

La requête retourne une 204 No Content réponse.

PATCH https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert
Content-Type: application/json

{
    "isActive": false
}

Alertes d’actualisation

Dans PIM, vous pouvez actualiser un seul type d’alerte ou toutes les alertes dans le locataire. Lorsque vous actualisez l’un ou l’autre type, PIM analyse le locataire à la recherche d’incidents qui correspondent aux alertes. Cette requête est une opération de longue durée et retourne un en-tête Location que vous pouvez utiliser pour interroger le status de l’opération, à savoir si l’actualisation a réussi ou échoué. Lors d’une actualisation réussie, PIM inclut des alertes que vous avez précédemment ignorées, réactive les alertes ignorées (mises à jour isActive vers true), et analyse et génère de nouveaux incidents pour les alertes.

Actualiser un type d’alerte unique

Demande

POST https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert/refresh

Réponse

HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/operations/refresh:DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert

Actualiser tous les types d’alerte dans le locataire

Demande

Seuls l’étendue du locataire (/) et DirectoryRole le type d’étendue sont pris en charge.

POST https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/refresh
Content-Type: application/json

{
    "scopeId" : "/",
    "scopeType" : "DirectoryRole"
}

Réponse

HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/operations/refresh:DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert

Mettre à jour une configuration d’alerte

La mise à jour d’une configuration d’alerte signifie modifier les paramètres spécifiques au locataire qui contrôlent la façon dont PIM analyse le locataire à la recherche d’incidents qui correspondent au type d’alerte. Par exemple, si vous souhaitez analyser l’alerte dans le locataire ou si vous pouvez modifier le seuil qui, lorsque le croisement déclenche un incident connu.

PATCH https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alertConfigurations/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_TooManyGlobalAdminsAssignedToTenantAlert
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.tooManyGlobalAdminsAssignedToTenantAlertConfiguration",
    "isEnabled": true,
    "globalAdminCountThreshold": 4,
    "percentageOfGlobalAdminsOutOfRolesThreshold": 10
}

La requête retourne une 204 No Content réponse.

Corriger un incident d’alerte

La correction d’un incident d’alerte signifie demander Microsoft Entra ID d’appliquer les étapes d’atténuation définies dans la définition de l’alerte. Par exemple, si la définition d’alerte recommande de supprimer un utilisateur d’un rôle, la correction de l’incident signifie qu’Microsoft Entra ID supprime l’utilisateur du rôle.

Demande

POST https://graph.microsoft.com/beta/identityGovernance/roleManagementAlerts/alerts/DirectoryRole_3b0e753b-22fa-4c16-9bf2-470b80be80d6_RolesAssignedOutsidePimAlert/alertIncidents/9e864769-63e3-4635-8069-551bcd46183d/remediate

Réponse

HTTP/1.1 200 OK