Tutorial: Usar la API de revisiones de acceso para revisar el acceso a los grupos de seguridad

En este tutorial, usará el Explorador de Graph para revisar el acceso a un grupo de seguridad en el espacio empresarial.

Puedes usar Graph Explorer o Postman para probar y probar las llamadas api de opiniones de acceso antes de automatizarlas en un script o una aplicación. Esto le ahorra tiempo al ayudarle a definir y validar correctamente sus consultas sin volver a compilar repetidamente la aplicación.

Nota

Los objetos de respuesta que se muestran en este tutorial podrían acortarse para mejorar la legibilidad.

Requisitos previos

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

  • Un inquilino de Azure AD en funcionamiento con una licencia Azure AD Premium P2 o EMS E5 habilitada.
  • Inicie sesión en Graph Explorer como usuario en un rol de administrador global.
    • [Opcional] Inicie una nueva sesión de explorador de incógnito o InPrivate o inicie una sesión en un explorador anónimo. Más adelante, inicie sesión en este tutorial.
  • Los siguientes permisos delegados: AccessReview.ReadWrite.All , Group.ReadWrite.All .

Para dar su consentimiento a los permisos necesarios en Graph Explorer:

  1. Seleccione el icono de engranaje de configuración a la derecha de los detalles de la cuenta de usuario y, a continuación, seleccione Seleccionar permisos.

    Seleccione los permisos de Microsoft Graph

  2. Desplácese por la lista de permisos a estos permisos:

    • AccessReview (3), expanda y seleccione AccessReview.ReadWrite.All.
    • Grupo (2), expanda y, a continuación, seleccione Group.ReadWrite.All.

    Seleccione Consentimiento y, en la ventana emergente, elija Consentimiento en nombre de su organización y, a continuación, seleccione Aceptar para aceptar el consentimiento de los permisos.

    Consentimiento a los permisos Graph Microsoft

Paso 1: Crear usuarios de prueba en el espacio empresarial

Cree tres nuevos usuarios de prueba ejecutando la solicitud por debajo de tres veces, cambiando las propiedades displayName, mailNickname y userPrincipalName cada vez. Registre sus identificadores.

Solicitud

POST /users
Content-Type: application/json

{
    "accountEnabled": true,
    "displayName": "Aline Dupuy",
    "mailNickname": "AlineD",
    "userPrincipalName": "AlineD@contoso.com",
    "passwordProfile": {
        "forceChangePasswordNextSignIn": true,
        "password": "xWwvJ]6NMw+bWH-d"
    }
}

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
    "id": "43b12b0c-ee2c-4257-96fe-505d823e06ab",
    "displayName": "Aline Dupuy",
    "mailNickname": "AlineD",
    "userPrincipalName": "AlineD@contoso.com",
    "userType": "Member"
}

Paso 2: Crear un grupo de seguridad, asignar propietarios y agregar miembros

Cree un grupo de seguridad denominado Building security group que sea el destino de las revisiones de acceso de este tutorial. Asigne a este grupo dos propietarios de grupo y dos miembros. Estos miembros serán objeto de revisión por parte de los propietarios del grupo.

Solicitud

En esta llamada, reemplace:

  • 010b2de0-0ed4-4ece-bfa2-22fff71d0497 y b828cc0e-4240-46ed-bb25-888744487e2d con los identificadores de los dos propietarios de grupo.
    • Uno de los identificadores pertenece a uno de los usuarios que creó en el paso 1.
    • El otro es su identificador. Para recuperar el identificador, ejecute GET en https://graph.microsoft.com/beta/me .
  • 43b12b0c-ee2c-4257-96fe-505d823e06ab y 859924d0-7115-422a-9ee8-ea8c0c014707 con los identificadores de los dos miembros del grupo. Estos son los otros dos miembros que creó en el paso 1.
POST https://graph.microsoft.com/beta/groups
Content-Type: application/json

{
    "description": "Building security group",
    "displayName": "Building security group",
    "groupTypes": [],
    "mailEnabled": false,
    "mailNickname": "buildingsecurity",
    "securityEnabled": true,
    "owners@odata.bind": [
        "https://graph.microsoft.com/beta/users/010b2de0-0ed4-4ece-bfa2-22fff71d0497",
        "https://graph.microsoft.com/beta/users/b828cc0e-4240-46ed-bb25-888744487e2d"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/beta/users/43b12b0c-ee2c-4257-96fe-505d823e06ab",
        "https://graph.microsoft.com/beta/users/859924d0-7115-422a-9ee8-ea8c0c014707"
    ]
}

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "id": "825f1b5e-6fb2-4d9a-b393-d491101acc0c",
    "displayName": "Building security group",
    "groupTypes": []
}

En la respuesta, registre el identificador del nuevo grupo para usarlo más adelante en este tutorial.

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

Cree una revisión de acceso para los miembros del grupo de seguridad con la siguiente configuración:

  • Es una revisión de acceso autoexcediendo. En este caso, los usuarios en revisión se autoatestarán su necesidad de acceso al grupo.
  • Esta es una revisión de acceso única. En este caso, una vez concedido el acceso, el usuario no necesita autoatestar de nuevo dentro del período de revisión de acceso.
  • El ámbito de revisión está limitado a los miembros del grupo de seguridad De creación.

Solicitud

En esta llamada, reemplace lo siguiente:

  • 825f1b5e-6fb2-4d9a-b393-d491101acc0c con el identificador del grupo de seguridad de creación.
  • El ámbito especifica que la revisión se aplica a todos los miembros del grupo de seguridad De creación. Para obtener más opciones para configurar el ámbito, vea la sección Ver también.
  • Valor de startDate con la fecha de hoy y el valor de endDate con una fecha de un año a partir de la fecha de inicio.

Al no especificar el valor de la propiedad reviewers, esta revisión de acceso se configura como autoexcediendo con los miembros como revisores.

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "One-time self-review for members of Building security group",
    "descriptionForAdmins": "One-time self-review for members of Building security group",
    "descriptionForReviewers": "One-time self-review for members of Building security group",
    "scope": {
        "query": "/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": false,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 0,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2021-02-09",
                "endDate": "2022-12-31"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "d7286a17-3a01-406a-b872-986b6b40317c",
    "displayName": "One-time self-review for members of Building security group",
    "status": "NotStarted",
    "createdBy": {
        "id": "b828cc0e-4240-46ed-bb25-888744487e2d",
        "displayName": "MOD Administrator",
        "userPrincipalName": "admin@contoso.com"
    },
    "scope": {
        "query": "/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [],
    "backupReviewers": [],
    "settings": {
        "defaultDecisionEnabled": false,
        "defaultDecision": "Deny",
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2021-02-09",
                "endDate": "2022-12-31"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

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

En la consulta siguiente se enumeran todas las instancias de la definición de revisión de acceso. Dado que ha creado una revisión de acceso única en el paso 3, la solicitud devuelve solo una instancia cuyo identificador es el mismo que el identificador de la definición de acceso.

Solicitud

En esta llamada, reemplace d7286a17-3a01-406a-b872-986b6b40317c por el identificador de la definición de revisión de acceso devuelta en el paso 3.

GET https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/d7286a17-3a01-406a-b872-986b6b40317c/instances

Respuesta

En esta respuesta, el estado de la instancia de revisión de acceso se debe a que startDateTime es pasado y InProgress endDateTime está en el futuro. Si startDateTime está en el futuro, el estado será NotStarted . Por otra parte, si endDateTime está en el pasado, el estado será Completed .

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions('d7286a17-3a01-406a-b872-986b6b40317c')/instances",
    "value": [
        {
            "id": "d7286a17-3a01-406a-b872-986b6b40317c",
            "startDateTime": "2021-02-10T15:09:40.153Z",
            "endDateTime": "2022-12-31T08:00:00Z",
            "status": "InProgress",
            "scope": {
                "query": "/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c/transitiveMembers",
                "queryType": "MicrosoftGraph"
            }
        }
    ]
}

Paso 5: Obtener decisiones

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

Solicitud

En esta llamada, reemplace d7286a17-3a01-406a-b872-986b6b40317c por el identificador de la definición de revisión de acceso devuelta en el paso 3.

GET https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/d7286a17-3a01-406a-b872-986b6b40317c/instances/d7286a17-3a01-406a-b872-986b6b40317c/decisions

Respuesta

La siguiente respuesta muestra la decisión tomada para la instancia de la revisión.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions('d7286a17-3a01-406a-b872-986b6b40317c')/instances('d7286a17-3a01-406a-b872-986b6b40317c')/decisions",
    "@odata.count": 2,
    "value": [
        {
            "id": "1c74f500-9082-4dfe-80ac-784a6edb71d7",
            "accessReviewId": "d7286a17-3a01-406a-b872-986b6b40317c",
            "decision": "NotReviewed",
            "applyResult": "New",
            "recommendation": "Approve",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "target": {
                "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItemUserTarget",
                "userId": "43b12b0c-ee2c-4257-96fe-505d823e06ab",
                "userDisplayName": "Alex Wilber",
                "userPrincipalName": "AlexW@contoso.com"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "43b12b0c-ee2c-4257-96fe-505d823e06ab",
                "displayName": "Alex Wilber",
                "userPrincipalName": "AlexW@contoso.com"
            }
        },
        {
            "id": "7744be81-7d17-40c9-8fd3-c9072b1ccace",
            "accessReviewId": "d7286a17-3a01-406a-b872-986b6b40317c",
            "decision": "NotReviewed",
            "applyResult": "New",
            "recommendation": "Approve",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "target": {
                "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItemUserTarget",
                "userId": "859924d0-7115-422a-9ee8-ea8c0c014707",
                "userDisplayName": "Allan Deyoung",
                "userPrincipalName": "AllanD@contoso.com"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "859924d0-7115-422a-9ee8-ea8c0c014707",
                "displayName": "Allan Deyoung",
                "userPrincipalName": "AllanD@contoso.com"
            }
        }
    ]
}

Desde la llamada, la propiedad decision tiene el valor de NotReviewed . Esto se debe a que ninguno de los dos miembros ha completado su autoaestación. Siga el paso 6 para obtener información sobre cómo cada miembro puede autoatestar su necesidad de revisión de acceso.

Paso 6: Autoex revisión del acceso pendiente

En el paso 3, configuró la revisión de acceso como una revisión personal. Esto significa que ambos miembros del grupo de seguridad de creación deben autoatesta su necesidad de mantener el acceso al grupo. Completará este paso como uno de los dos miembros del grupo de seguridad De creación.

In this step, you will:

  1. Enumerar las instancias de revisión de acceso pendientes.
  2. Complete el proceso de autoaestación de revisión de acceso.

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

Enumerar las instancias de revisión de acceso pendientes

En la sesión del explorador de incógnito y en Graph Explorer, ejecute la siguiente consulta para enumerar las instancias de revisión de acceso pendientes:

Solicitud

GET /me/pendingAccessReviewInstances

Respuesta

En la siguiente respuesta, el usuario Alex Wilber de id tiene 1 revisión de acceso pendiente 43b12b0c-ee2c-4257-96fe-505d823e06ab para autoatestar.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('43b12b0c-ee2c-4257-96fe-505d823e06ab')/pendingAccessReviewInstances",
    "@odata.count": 1,
    "value": [
        {
            "id": "d7286a17-3a01-406a-b872-986b6b40317c",
            "startDateTime": "2021-02-10T15:09:40.153Z",
            "endDateTime": "2022-12-31T08:00:00Z",
            "status": "InProgress",
            "scope": {
                "query": "/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c/transitiveMembers",
                "queryType": "MicrosoftGraph"
            }
        }
    ]
}

El uso de /me/pendingAccessReviewInstances la llamada en un contexto de usuario tiene varias ventajas:

  • No se requiere ninguna entidad de servicio. Un usuario puede llamar y leer sus acciones de revisión de acceso pendientes.
  • Pueden ser usados por widgets o complementos en una página intranet, o un bot o demonio que se ejecutan como un servicio en segundo plano. Estos pueden notificarle nuevas revisiones de acceso o actualizaciones para obtener acceso a las revisiones.

Completar la autoaestación de revisión de acceso

En la misma sesión del explorador de incógnito, inicie sesión https://myaccess.microsoft.com/ para completar la autoaestación. En la barra de navegación derecha, seleccione revisiones de acceso y elija la revisión de acceso. Seleccione , que todavía necesita acceso al grupo de seguridad De creación, escriba un motivo y, a continuación, haga clic en Enviar.

Autoatestar la revisión de acceso

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

De nuevo en la sesión principal del explorador en la que todavía ha iniciado sesión como usuario de administrador global, repita el paso 4 para ver que la propiedad de decisión del miembro que completó el paso 5 es ahora Approve .

¡Felicidades! Ha creado una revisión de acceso y se ha autoatestado la necesidad de acceso. Solo lo hace una vez y mantiene el acceso hasta que expire la definición de revisión de acceso.

Paso 7: Limpiar los recursos

Elimine los recursos que creó para este tutorial: crear un grupo de seguridad, la definición de programación de revisión de acceso y los tres usuarios de prueba.

Eliminar el grupo de seguridad

Solicitud

En esta llamada, reemplace 825f1b5e-6fb2-4d9a-b393-d491101acc0c por el identificador del grupo de seguridad de creación.

DELETE https://graph.microsoft.com/beta/groups/825f1b5e-6fb2-4d9a-b393-d491101acc0c

Respuesta

HTTP/1.1 204 No Content
Content-type: text/plain

Eliminar la definición de revisión de acceso

En esta llamada, reemplace d7286a17-3a01-406a-b872-986b6b40317c por el identificador de la definición de revisión de acceso. Dado que la definición de programación de revisión de acceso es el plano de la revisión de acceso, eliminar la definición eliminará la configuración, las instancias y las decisiones asociadas con la revisión de acceso.

Solicitud

DELETE https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/d7286a17-3a01-406a-b872-986b6b40317c

Respuesta

HTTP/1.1 204 No Content
Content-type: text/plain

Eliminar los tres usuarios de prueba

En esta llamada, reemplace 43b12b0c-ee2c-4257-96fe-505d823e06ab por el identificador del usuario de prueba. Repita esta acción dos veces con los identificadores de los otros dos usuarios para eliminarlos.

Solicitud

DELETE https://graph.microsoft.com/beta/users/43b12b0c-ee2c-4257-96fe-505d823e06ab

Respuesta

HTTP/1.1 204 No Content
Content-type: text/plain

Consulte también