Configurar el ámbito de la revisión de acceso mediante microsoft Graph API

La API de revisiones de acceso de Azure AD permite revisar mediante programación el acceso que los usuarios, las entidades de servicio o los grupos tienen a los recursos de Azure AD. La API puede ayudarle a automatizar la revisión proactiva y mantener el control sobre el acceso a los recursos de su organización.

Los recursos que se van a revisar se configuran en la propiedad scope del recurso accessReviewScheduleDefinition . Esta propiedad es del tipo accessReviewScope, un tipo abstracto del que heredan los siguientes recursos de API que se pueden usar para configurar el ámbito de revisión de acceso.

Recurso Descripción Escenarios de ejemplo
accessReviewQueryScope Hereda de accessReviewScope. Se aplica mejor al revisar el conjunto completo o subconjunto de entidades de seguridad que tienen acceso a un recurso o grupo de recursos relacionados.
  • Pertenencia de usuarios asignados a un grupo, ya sean miembros directos o miembros directos y transitivos.
  • Acceso de usuario invitado a un grupo.
  • Acceso de usuario invitado a todos los grupos de Microsoft 365 en un inquilino.
  • Entidades de servicio asignadas a roles con privilegios.
  • Acceso de usuario y entidad de servicio a los paquetes de acceso de administración de derechos.
accessReviewInactiveUsersQueryScope Hereda de accessReviewQueryScope. Se usa cuando solo se revisan los usuarios inactivos. La propiedad inactiveDuration especifica su estado inactivo.
  • Pertenencia a grupos de solo usuarios inactivos.
    principalResourceMembershipsScope Hereda de accessReviewScope. Se aplica mejor a la revisión del acceso de las entidades de seguridad a los recursos en los que se configuran grupos únicos de entidades de seguridad y recursos.
    • Revisar el acceso de tres entidades de seguridad específicas en un grupo de Microsoft 365 y un rol de Azure AD con privilegios.

      En este artículo, aprenderá a limitar la revisión de acceso mediante estos tres tipos de recursos derivados.

      Uso de accessReviewQueryScope y accessReviewInactiveUsersQueryScope para configurar el ámbito

      Para configurar el ámbito mediante el tipo accessReviewQueryScope , establezca los valores de sus propiedades query, queryRoot y queryType . Para obtener descripciones de estas propiedades, consulte el tipo de recurso accessReviewQueryScope .

      accessReviewInactiveUsersQueryScope requiere todas las propiedades de accessReviewQueryScope e incluye una propiedad inactiveDuration .

      Ejemplo 1: Revisión de todos los usuarios asignados a un grupo

      En el ejemplo siguiente se limita la revisión a los miembros directos y transitivos del grupo que son usuarios. Los miembros transitivos son miembros de los grupos anidados.

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/groups/{groupId}/transitiveMembers/microsoft.graph.user",
          "queryType": "MicrosoftGraph"
      }
      

      Escenario de ejemplo: Supongamos que el grupo A tiene tres miembros directos: los usuarios AU1 y AU2 y el grupo G1. Por otro lado, el grupo G1 tiene dos miembros: los usuarios GU1 y GU2. Por lo tanto, los usuarios GU1 y GU2 son miembros transitivos del grupo anidado G1. Se incluirán cuatro objetos en la revisión: usuarios AU1, AU2, GU1 y GU2.

      Para revisar solo los usuarios inactivos asignados al grupo:

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
          "inactiveDuration": "P30D",
          "query": "/groups/{groupId}/transitiveMembers/microsoft.graph.user",
          "queryType": "MicrosoftGraph"
      }
      

      En este ejemplo también se limita la revisión a los miembros directos y transitivos del grupo que son usuarios inactivos.

      Ejemplo 2: Revisión de todos los usuarios invitados asignados a un grupo

      En el ejemplo siguiente se limita la revisión a los miembros directos y transitivos del grupo que son usuarios invitados. Los miembros transitivos son miembros de los grupos anidados.

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/groups/{groupId}/transitiveMembers/microsoft.graph.user/?$filter=(userType eq 'Guest')",    
          "queryType": "MicrosoftGraph"
      }
      

      Ejemplo 3: Revisión de todos los usuarios y grupos asignados a un grupo

      En el ejemplo siguiente se limita la revisión a solo los miembros directos del grupo que son usuarios u otros grupos. En este ámbito:

      • Los usuarios directos se incluyen en la revisión.
      • Los grupos directos se incluyen en la revisión.
      • Los miembros transitivos de los grupos, es decir, los miembros de grupos anidados, no se incluyen en la revisión.
      "scope": {
              "query": "/groups/{groupId}/members",
              "queryType": "MicrosoftGraph"
      }
      

      Escenario de ejemplo: Supongamos que el grupo A tiene tres miembros directos: los usuarios AU1 y AU2 y el grupo G1. Por otro lado, el grupo G1 tiene dos miembros: los usuarios GU1 y GU2. Por lo tanto, los usuarios GU1 y GU2 son miembros transitivos del grupo anidado G1. Solo tres objetos están destinados en la revisión anterior, los usuarios AU1 y AU2 y el grupo G1.

      Ejemplo 4: Revisar todos los usuarios asignados a todos los grupos de Microsoft 365

      En el ejemplo siguiente se crea una revisión de cada grupo de Microsoft 365 que contiene usuarios invitados. Para la instancia de revisión de cada grupo, el ámbito de la revisión es solo para los miembros directos del grupo que son usuarios invitados.

      "instanceEnumerationScope": {
          "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
          "queryType": "MicrosoftGraph"
      },
      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "./members/microsoft.graph.user",
          "queryType": "MicrosoftGraph"
      }
      

      Además, dado que esta revisión se aplica a todos los grupos de Microsoft 365, configure instanceEnumerationScope para especificar los grupos de Microsoft 365 que se van a revisar. Los grupos dinámicos y los grupos a los que se pueden asignar roles no se incluyen en esta revisión.

      Ejemplo 5: Revisar todos los usuarios invitados asignados a todos los grupos de Microsoft 365

      En el ejemplo siguiente se establece el ámbito de la revisión para dirigir a los miembros de todos los grupos de Microsoft 365 que son usuarios invitados.

      "instanceEnumerationScope": {
          "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
          "queryType": "MicrosoftGraph"
      },
      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
          "queryType": "MicrosoftGraph"
      }
      

      Además, dado que esta revisión se aplica a todos los grupos de Microsoft 365, configure instanceEnumerationScope para especificar los grupos de Microsoft 365 que se van a revisar. Los grupos dinámicos y los grupos a los que se pueden asignar roles no se incluyen en esta revisión.

      Revisar todos los usuarios invitados inactivos asignados a todos los grupos de Microsoft 365

      En el ejemplo siguiente se limita la revisión a los miembros directos de todos los usuarios invitados inactivos de Microsoft 365.

      "instanceEnumerationScope": {
          "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
          "queryType": "MicrosoftGraph"
      },
      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
          "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
          "queryType": "MicrosoftGraph",
          "inactiveDuration": "P30D"
      }
      

      Además, dado que esta revisión se aplica a usuarios inactivos, use el recurso accessReviewInactiveUsersQueryScope y especifique la propiedad **de tipo @odata.type** con el valor #microsoft.graph.accessReviewInactiveUsersQueryScope. Los grupos dinámicos y los grupos a los que se pueden asignar roles no se incluyen en esta revisión.

      Ejemplo 6: Revisión de todos los usuarios invitados asignados a todos los equipos

      En el ejemplo siguiente se limita la revisión para dirigir a los miembros de todos los equipos que son usuarios invitados.

      "instanceEnumerationScope": {
          "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
          "queryType": "MicrosoftGraph"
      },
      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
          "queryType": "MicrosoftGraph"
      }
      

      Además, dado que esta revisión se aplica a todos los grupos de Microsoft 365 habilitados para Teams, configure instanceEnumerationScope para especificar los grupos de Microsoft 365 habilitados para Teams que se van a revisar. Los grupos dinámicos y los grupos a los que se pueden asignar roles no se incluyen en esta revisión.

      Esta revisión no incluirá usuarios de conexión directa B2B en equipos con canales compartidos. Para incluir usuarios de conexión directa B2B en equipos con canales compartidos, consulte Ejemplo 11: Revisar todos los usuarios asignados a un equipo, incluidos los usuarios de conexión directa B2B en un equipo con canales compartidos.

      Revisar todos los usuarios invitados inactivos asignados a todos los equipos

      En el ejemplo siguiente se limita la revisión para dirigir a los miembros de todos los equipos que son usuarios invitados inactivos.

      "instanceEnumerationScope": {
          "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
          "queryType": "MicrosoftGraph"
      },
      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
          "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
          "queryType": "MicrosoftGraph",
          "inactiveDuration": "P30D"
      }
      

      Además, dado que esta revisión se aplica a todos los equipos, configure la propiedad instanceEnumerationScope para especificar todos los equipos. Los grupos dinámicos y los grupos a los que se pueden asignar roles no se incluyen en esta revisión.

      Esta revisión no incluirá usuarios de conexión directa B2B en equipos con canales compartidos. Para incluir usuarios de conexión directa B2B en equipos con canales compartidos, consulte Ejemplo 11: Revisar todos los usuarios asignados a un equipo, incluidos los usuarios de conexión directa B2B en un equipo con canales compartidos.


      Ejemplo 7: Revisión de todas las asignaciones a paquetes de acceso de administración de derechos

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/identityGovernance/entitlementManagement/accessPackageAssignments?$filter=(accessPackageId eq '{package id}' and assignmentPolicyId eq '{id}')",
          "queryType": "MicrosoftGraph"
      }
      

      Ejemplo 8: Revisión de todas las entidades de servicio asignadas a un rol con privilegios

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/roleManagement/directory/roleAssignmentScheduleInstances?$expand=principal&$filter=(isof(principal,'microsoft.graph.servicePrincipal') and roleDefinitionId eq '{role ID}')",
          "queryType": "MicrosoftGraph"
      }
      

      Ejemplo 9: Revisión de todos los usuarios asignados a un rol con privilegios

      Revisar todos los usuarios asignados a un rol con privilegios (todas las asignaciones activas y aptas incluidas)

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/roleManagement/directory/roleDefinitions/{role ID}",
          "queryType": "MicrosoftGraph"
      }
      

      Revisión de todos los usuarios con asignación apta a un rol con privilegios

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/roleManagement/directory/roleEligibilityScheduleInstances?$expand=principal&$filter=(isof(principal,'microsoft.graph.user') and roleDefinitionId eq '{role ID}')",
          "queryType": "MicrosoftGraph"
      }
      

      Revisar todos los usuarios con asignación activa a un rol con privilegios

      "scope": {
          "@odata.type": "#microsoft.graph.accessReviewQueryScope",
          "query": "/roleManagement/directory/roleAssignmentScheduleInstances?$expand=principal&$filter=(assignmentType eq 'Assigned' and isof(principal,'microsoft.graph.user') and roleDefinitionId eq '{role ID}')",
          "queryType": "MicrosoftGraph"
      }
      

      Uso de principalResourceMembershipsScope para configurar el ámbito

      El principalResourceMembershipsScope expone las propiedades principalScopes y resourceScopes para admitir opciones de configuración más personalizadas para el ámbito del objeto accessReviewScheduleDefinition. Las funcionalidades incluyen la revisión del acceso de varias entidades de seguridad o grupos de entidades de seguridad a varios recursos.

      Ejemplo 10: Revisión de todos los usuarios invitados inactivos asignados a todos los grupos

      En el ejemplo siguiente se limita la revisión a los miembros directos de todos los grupos que son usuarios invitados inactivos. Los usuarios invitados se consideran usuarios inactivos cuando el período de inactividad es de 30 días a partir de la fecha de inicio de la instancia de revisión de acceso.

      "scope": {
          "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
          "principalScopes": [
              {
                  "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
                  "query": "/users?$filter=(userType eq 'Guest')",
                  "queryType": "MicrosoftGraph",
                  "inactiveDuration": "P30D"
              }
          ],
          "resourceScopes": [
              {
                  "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                  "query": "/groups",
                  "queryType": "MicrosoftGraph"
              }
          ]
      }
      

      Ejemplo 11: Revisar todos los usuarios asignados a un equipo, incluidos los usuarios de conexión directa B2B en un equipo con canales compartidos

      En este ejemplo, el ámbito de revisión de acceso es todos los usuarios que son miembros de un equipo o que están asignados a un canal compartido dentro del equipo. Estos miembros incluyen usuarios internos, usuarios directos y transitivos, usuarios de colaboración B2B y usuarios de conexión directa B2B.

      "scope": {
          "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
          "principalScopes": [
              {
                  "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                  "query": "/users",
                  "queryType": "MicrosoftGraph",
                  "queryRoot": null
              }
          ],
          "resourceScopes": [
              {
                  "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                  "query": "/groups/{groupId}/transitiveMembers/microsoft.graph.user",
                  "queryType": "MicrosoftGraph",
                  "queryRoot": null
              },
              {
                  "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                  "query": "/teams/{groupId}/channels?$filter=(membershipType eq 'shared')",
                  "queryType": "MicrosoftGraph",
                  "queryRoot": null
              }
          ]
      }
      

      Para revisar la conexión directa de B2B a usuarios y equipos dentro de canales compartidos, debe especificar el /teams/{groupId}/channels?$filter=(membershipType eq 'shared') patrón de consulta en el objeto resourceScopes . Una revisión de todos los equipos , como el ejemplo 6, no incluirá usuarios y equipos de conexión directa B2B dentro de canales compartidos.

      Nota

      La revisión de acceso de los usuarios y equipos de conexión directa B2B solo se admite en las revisiones de acceso de una sola fase y no en las revisiones de acceso de varias fases.

      Ejemplo 12: Revisión de todos los usuarios invitados asignados a un rol de directorio

      "scope": {
          "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
          "principalScopes": [
              {
                  "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                  "query": "/users?$filter=(userType eq 'Guest')",
                  "queryType": "MicrosoftGraph"
              }
          ],
          "resourceScopes": [
              {
                  "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                  "query": "/roleManagement/directory/roleDefinitions/{role id}",
                  "queryType": "MicrosoftGraph"
              }
          ]
      }
      

      Pasos siguientes