Revisión del acceso a grupos de seguridad mediante las API de revisiones de acceso

La API de revisiones de acceso de Microsoft Graph permite a las organizaciones auditar y dar fe del acceso que las identidades (también denominadas entidades de seguridad) se asignan a los recursos de la organización. Puede usar grupos de seguridad para administrar de forma eficaz el acceso a los recursos de la organización. Por ejemplo, acceso a un sitio de SharePoint que contiene cuadernos de estrategias de marketing. Además, mediante la API de revisiones de acceso, las organizaciones pueden atestiguar periódicamente las entidades de seguridad que tienen acceso a dichos grupos y, por extensión, a los recursos de la organización.

En este tutorial, aprenderá a:

  • Cree una revisión de acceso periódica de pertenencias a grupos de seguridad.
  • Atestigua la necesidad de mantener el acceso a un grupo.

Requisitos previos

Para completar este tutorial, necesita los siguientes recursos y privilegios:

  • Un inquilino de Microsoft Entra en funcionamiento con una licencia Microsoft Entra ID P2 o Gobierno de Microsoft Entra ID habilitada.
  • Dos invitados de prueba y un grupo de seguridad de prueba en el inquilino. Los invitados deben ser miembros del grupo y el grupo debe tener al menos un propietario.
  • Inicie sesión en un cliente de API, como Graph Explorer , para llamar a Microsoft Graph con una cuenta que tenga al menos el rol Administrador de gobernanza de identidades .
    • [Opcional] Abra una nueva ventana del explorador incógnito, anónimo o InPrivate . Inicie sesión más adelante en este tutorial.
  • Concédese los siguientes permisos delegados: AccessReview.ReadWrite.All.

Nota:

La revisión de los grupos que se rigen por PIM solo asigna propietarios activos como revisores. Los propietarios aptos no están incluidos. Se requiere al menos un revisor de reserva para la revisión de acceso de los grupos regidos por PIM. Si no hay propietarios activos cuando comienza la revisión, se asigna la revisión a los revisores de reserva.

Paso 1: Crear una revisión de acceso para el grupo de seguridad

Solicitud

En esta llamada, reemplace los valores siguientes:

  • eb75ccd2-59ef-48b7-8f76-cc3f33f899f4 con el identificador del grupo de seguridad.
  • Valor de startDate con la fecha de hoy y el valor de endDate con una fecha de cinco días a partir de la fecha de inicio.

La revisión de acceso tiene la siguiente configuración:

  • Es una revisión autoatestante como inferida cuando no se especifica un valor para la propiedad reviewers . Por lo tanto, cada miembro del grupo da fe de su necesidad de mantener el acceso al grupo.
  • El ámbito de la revisión es tanto los miembros directos como transitivos del grupo.
  • El revisor debe proporcionar una justificación de por qué necesita mantener el acceso al grupo.
  • La decisión predeterminada es Deny cuando los revisores no responden a la solicitud de revisión de acceso antes de que expire la instancia. La Deny decisión quita los miembros del grupo del grupo.
  • Es una revisión de acceso única que termina después de cinco días. Por lo tanto, una vez concedido el acceso, el usuario no necesita volver a atestiguar el acceso dentro del período de revisión de acceso.
  • Las entidades de seguridad definidas en el ámbito de la revisión reciben notificaciones por correo electrónico y avisos que les piden que atestiguan su necesidad de mantener el acceso.
POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "One-time self-review for members of Building security",
    "descriptionForAdmins": "One-time self-review for members of Building security",
    "descriptionForReviewers": "One-time self-review for members of Building security",
    "scope": {
        "query": "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
        "queryType": "MicrosoftGraph"
    },
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 5,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2024-03-30"
            }
        }
    }
}

Respuesta

El estado de la revisión de acceso es NotStarted. Puede recuperar la revisión de acceso (GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b) para supervisar el estado y, cuando su estado es InProgress, se han creado instancias para la revisión de acceso y se pueden publicar decisiones. También puede recuperar la revisión de acceso para ver su configuración completa.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
    "displayName": "One-time self-review for members of Building security",
    "createdDateTime": null,
    "lastModifiedDateTime": null,
    "status": "NotStarted",
    "descriptionForAdmins": "One-time self-review for members of Building security",
    "descriptionForReviewers": "One-time self-review for members of Building security",
    "scope": {},
    "instanceEnumerationScope": {},
    "reviewers": [],
    "fallbackReviewers": [],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 5,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": null,
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2024-03-30"
            }
        },
        "applyActions": [],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

Paso 2: Enumerar instancias de la revisión de acceso

Una vez marcado el estado de la revisión de acceso como InProgress, ejecute la siguiente consulta para enumerar todas las instancias de la definición de revisión de acceso. Dado que creó una revisión de acceso única en el paso anterior, la solicitud devuelve solo una instancia con un identificador como el identificador de la definición de programación.

Solicitud

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances

Respuesta

En esta respuesta, el estado de la instancia es InProgress porque startDateTime es pasado y endDateTime es en el futuro. Si startDateTime es en el futuro, el estado es NotStarted. Por otro lado, si endDateTime está en el pasado, el estado es Completed.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances",
    "value": [
        {
            "id": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "startDateTime": "2024-03-21T17:35:25.24Z",
            "endDateTime": "2024-03-30T08:00:00Z",
            "status": "InProgress",
            "scope": {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers/microsoft.graph.user",
                "queryType": "MicrosoftGraph",
                "queryRoot": null
            },
            "reviewers": [],
            "fallbackReviewers": []
        }
    ]
}

Paso 3: Comprobar quién se ha contactado para la revisión

Puede confirmar que se ha contactado a todos los miembros del grupo de seguridad para publicar sus decisiones de revisión para esta instancia de la revisión de acceso.

Solicitud

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/contactedReviewers

Respuesta

La siguiente respuesta muestra que se notificó a los dos miembros del grupo de seguridad de su revisión pendiente.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/contactedReviewers",
    "@odata.count": 2,
    "value": [
        {
            "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "displayName": "Adele Vance",
            "userPrincipalName": "AdeleV@Contoso.com",
            "createdDateTime": "2024-03-21T17:35:34.4092545Z"
        },
        {
            "id": "bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
            "displayName": "Alex Wilber",
            "userPrincipalName": "AlexW@Contoso.com",
            "createdDateTime": "2024-03-21T17:35:34.4092545Z"
        }
    ]
}

Paso 4: Tomar decisiones

Le interesan las decisiones tomadas para la instancia de la revisión de acceso.

Solicitud

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions

Respuesta

En la respuesta siguiente se muestran las decisiones tomadas en la instancia de la revisión. Dado que el grupo de seguridad tiene dos miembros, se esperan dos elementos de decisión.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/decisions",
    "@odata.count": 2,
    "value": [
        {
            "id": "4db68765-472d-4aa2-847a-433ea94bcfaf",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
                "displayName": "Alex Wilber",
                "type": "user",
                "userPrincipalName": "AlexW@Contoso.com",
                "lastUserSignInDateTime": "2/11/2022 5:31:37 PM +00:00"
            }
        },
        {
            "id": "c7de8fba-4d6a-4fab-a659-62ff0c02643d",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@Contoso.com",
                "lastUserSignInDateTime": "2/11/2022 4:58:13 PM +00:00"
            }
        }
    ]
}

Desde la llamada, la propiedad de decisión tiene el valor de NotReviewed porque los miembros del grupo no han completado su autoatestación. En el paso siguiente se muestra cómo cada miembro puede dar fe de su necesidad de revisión de acceso.

Paso 5: Autoatestar una decisión de acceso pendiente

Ha configurado la revisión de acceso como autoatestante. Esta configuración requiere que ambos miembros del grupo atestiguan automáticamente su necesidad de mantener su acceso al grupo.

Nota:

Complete este paso como uno de los dos miembros del grupo de seguridad.

En este paso, enumera las revisiones de acceso pendientes y, a continuación, completa el proceso de autoatestación. Puede completar este paso de dos maneras, mediante la API o mediante el portal Mi acceso. El otro revisor no se autoatesta y, en su lugar, las decisiones predeterminadas se aplican a su revisión de acceso.

Inicie una nueva sesión de explorador de exploración de incógnito, anónimo o InPrivate e inicie sesión como uno de los dos miembros del grupo de seguridad. Al hacerlo, no interrumpe la sesión de administrador actual. Como alternativa, puede interrumpir la sesión de administrador actual si inicia sesión en el Explorador de Graph y vuelve a iniciar sesión como uno de los dos miembros del grupo.

Método 1: Uso de la API de revisiones de acceso para revisar el acceso pendiente

Enumerar los elementos de decisión de las revisiones de acceso

Solicitud
GET https://graph.microsoft.com/v1.0/identitygovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions/filterByCurrentUser(on='reviewer')
Respuesta

A partir de la respuesta, usted (Adele Vance) tiene una revisión de acceso pendiente (la decisión es NotReviewed) para autoatestar. Las propiedades principal y de recurso indican la entidad de seguridad a la que se aplica la decisión y el recurso al que se está revisando el acceso. En este caso, Adele Vance y el grupo de seguridad respectivamente.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(accessReviewInstanceDecisionItem)",
    "@odata.count": 1,
    "value": [
        {
            "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItem",
            "id": "c7de8fba-4d6a-4fab-a659-62ff0c02643d",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@Contoso.com",
                "lastUserSignInDateTime": "2/15/2022 9:35:23 AM +00:00"
            }
        }
    ]
}

Registrar una decisión

Para completar la revisión de acceso, Adele Vance confirma la necesidad de mantener el acceso al grupo de seguridad.

La solicitud devuelve un código de respuesta 204 No Content.

PATCH https://graph.microsoft.com/v1.0/identitygovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions/c7de8fba-4d6a-4fab-a659-62ff0c02643d

{
    "decision": "Approve",
    "justification": "As the assistant security manager, I still need access to the building security group."
}

Comprobación de las decisiones

Para comprobar las decisiones que ha registrado para la revisión de acceso, enumere los elementos de decisión de revisión de acceso. Aunque el período de revisión de acceso no ha expirado ni las decisiones aplicadas, applyResult se marca como New y se le permite cambiar la decisión.

Ahora puede cerrar la sesión y salir de la sesión del explorador de incógnito.

Método 2: Uso del portal Mi acceso

Como alternativa, puede comprobar las instancias de revisión de acceso pendientes a través del portal Mi acceso .

  • Enumere las revisiones de acceso pendientes. El usuario puede seguir una de las dos maneras de llegar:

    • Opción 1: Seleccione el botón Revisar acceso en la notificación por correo electrónico que recibieron en su bandeja de entrada de correo. La notificación por correo electrónico es similar a la siguiente captura de pantalla. Este botón es un vínculo directo a la revisión de acceso pendiente.

    Email notificación para revisar el acceso.

    • Opción 2: Vaya al portal Mi acceso . Seleccione el menú Revisiones de acceso y seleccione la pestaña Grupos y aplicaciones .
  • En la lista de revisiones de acceso, seleccione la revisión de acceso para la que desea publicar la decisión. Seleccione para publicar la decisión de que todavía necesita acceso a Seguridad de la compilación. Escriba un motivo y, a continuación, seleccione Enviar.

    Atestigua la necesidad de mantener el acceso a un recurso.

Ahora puede cerrar la sesión y salir de la sesión del explorador de incógnito.

Paso 6: Confirmar las decisiones y el estado de la revisión de acceso

De nuevo en la sesión del explorador principal donde todavía ha iniciado sesión con privilegios de administrador, repita el paso 4 para ver que la propiedad de decisión de Adele Vance es ahora Approve. Cuando la revisión de acceso finaliza o expira, la decisión predeterminada de Deny se registra para Alex Wilber. Las decisiones se aplican automáticamente porque autoApplyDecisionsEnabled se estableció en true y finalizó el período de la instancia de revisión de acceso. Adele mantiene el acceso al grupo de seguridad mientras Alex se quita automáticamente del grupo.

Enhorabuena. Ha creado una revisión de acceso y ha autoatestado la necesidad de mantener el acceso. Solo se atestigua una vez y mantendrá el acceso hasta que se quite mediante una Deny decisión de otra instancia de revisión de acceso o a través de otro proceso interno.

Paso 7: Limpiar los recursos

En esta llamada, eliminará la definición de revisión de acceso. Dado que la definición de programación de revisión de acceso es el plano técnico de la revisión de acceso, al eliminar la definición se quitan las opciones de configuración, las instancias y las decisiones relacionadas.

La solicitud devuelve un código de respuesta 204 No Content.

DELETE https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b

Conclusión

Ha creado una revisión de acceso en la que las entidades de seguridad atestiguan automáticamente su necesidad de mantener su acceso a un recurso, en este caso, el grupo de seguridad De compilación .

En este tutorial se ha mostrado uno de los escenarios de la API de revisiones de acceso de Microsoft Entra. La API de revisiones de acceso admite diferentes escenarios a través de una combinación de recursos, entidades de seguridad y revisores para satisfacer las necesidades de atestación de acceso. Para obtener más información, consulte la API de revisiones de acceso.