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

  • Artículo

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. Con la colaboración B2B, puede usar grupos de Microsoft 365 para administrar de forma eficaz el acceso de los invitados a recursos como archivos, notas, calendarios e incluso conversaciones de Teams. Y 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 otros recursos de la organización.

En este tutorial, aprenderá a:

  • Cree una revisión de acceso periódica de grupos de Microsoft 365 con invitados.
  • Investigue las decisiones que se aplican a las revisiones de acceso.

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.
  • Un invitado de prueba y un grupo de Microsoft 365 de prueba en el inquilino. El invitado debe ser miembro del grupo de Microsoft 365.
  • 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 .
  • Concédese los siguientes permisos delegados: AccessReview.ReadWrite.All.

Paso 1: Crear una revisión de acceso para todos los grupos de Microsoft 365 con invitados

La siguiente serie de revisión de acceso usa la siguiente configuración:

  • Es una revisión de acceso periódica y se revisa trimestralmente.
  • Los propietarios del grupo son los responsables de la toma de decisiones.
  • El ámbito de revisión solo se limita a los grupos de Microsoft 365 con invitados.
  • Define a un usuario como el revisor de reserva que puede revisar el acceso en caso de que el grupo no tenga ningún propietario asignado.
  • autoApplyDecisionsEnabled está establecido en true. En este caso, las decisiones se aplican automáticamente una vez que el revisor completa la revisión de acceso o finaliza la duración de la revisión de acceso. Si no está habilitado, un usuario debe aplicar las decisiones manualmente una vez completada la revisión.
  • applyActions se establece en removeAccessApplyAction. Esta acción quita los invitados denegados del grupo. El invitado todavía puede iniciar sesión en el inquilino, pero no será miembro del grupo ni tendrá los privilegios de acceso que se conceden a través del grupo.

Solicitud

En esta llamada, reemplace los valores siguientes:

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 con el identificador del revisor de reserva.
  • 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.
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"
            }
        ]
    }
}

Respuesta

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": "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": []
}

Paso 2: 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. Si hay más de un grupo de Microsoft 365 con invitados en el inquilino, esta solicitud devuelve una instancia para cada grupo de Microsoft 365 con invitados.

Solicitud

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

Respuesta

En esta respuesta, el ámbito incluye el grupo de pruebas porque tiene un invitado. En esta respuesta, la instancia de revisión de acceso es actualmente InProgress. Dado que se trata de una revisión trimestral, se crea automáticamente una nueva instancia de revisión cada tres meses y los revisores pueden aplicar nuevas decisiones.

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('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"
            }
        }
    ]
}

Paso 3: Tomar decisiones

Obtenga las decisiones tomadas para la instancia de una revisión de acceso. En una revisión trimestral como esta, y siempre que la revisión de acceso siga activa:

  • Cada tres meses se crea una nueva instancia de revisión.
  • Los revisores deben aplicar nuevas decisiones para las nuevas instancias.

Solicitud

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

Respuesta

En la siguiente respuesta se muestra la decisión adoptada para la instancia de la revisió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('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"
            }
        }
    ]
}

Paso 4: Limpieza de recursos

En este paso, eliminará la definición de revisión de acceso. Puesto que la definición de programación de revisión de acceso es el plano técnico para 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 una 204 No Content respuesta.

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

Contenido relacionado