Configurar o escopo de revisão de acesso usando APIs do Microsoft Graph

As APIs de revisões de acesso do Microsoft Entra permitem que você examine programaticamente o acesso que usuários, entidades de serviço ou grupos têm aos recursos do Microsoft Entra em seu locatário.

Configure os recursos do Microsoft Entra a serem revisados na propriedade scope do recurso accessReviewScheduleDefinition. Os seguintes recursos mostram as configurações para definir o escopo da revisão de acesso:

Recurso	Descrição	Exemplos de cenários de revisão de acesso
accessReviewQueryScope	Melhor aplicável ao examinar o conjunto completo ou o subconjunto de entidades de segurança que têm acesso a um recurso ou grupo de recursos relacionados.	Associação de usuários atribuídos a um grupo, membros diretos ou membros diretos e transitivos. Acesso de usuário convidado a um grupo. Acesso de usuário convidado a todos os grupos do Microsoft 365. Entidades de serviço atribuídas a funções privilegiadas. Acesso do usuário e da entidade de serviço aos pacotes de acesso de Gerenciamento de Direitos.
accessReviewInactiveUsersQueryScope	Herda de accessReviewQueryScope. Usado quando apenas usuários inativos são revisados. Seu status inativo é especificado pela propriedade inactiveDuration.	Associação de grupo somente para usuários inativos
principalResourceMembershipsScope	Herda de accessReviewScope. Melhor aplicável para examinar o acesso das entidades de segurança aos recursos em que você configura pools exclusivos de entidades de segurança e recursos.	Acesso de três entidades de segurança específicas a um grupo do Microsoft 365 e uma função privilegiada do Microsoft Entra.

Este artigo explica como definir o escopo de sua revisão de acesso configurando os três tipos de recursos derivados.

Configurar o escopo usando accessReviewQueryScope e accessReviewInactiveUsersQueryScope

Para configurar o escopo usando o tipo de recurso accessReviewQueryScope, defina os valores de suas propriedades query, queryRoot e queryType .

accessReviewInactiveUsersQueryScope requer todas as propriedades de accessReviewQueryScope e inclui uma propriedade inactiveDuration .

Exemplos

Observação

Os exemplos nesta seção mostram as únicas combinações válidas de principalScopes e resourceScopes compatíveis com a API do Graph.

Exemplo 1: Examinar todos os usuários com atribuição direta e transitiva para um grupo

Exemplo de cenário: Suponha que o grupo A tenha três membros diretos - usuários AU1 e AU2 e grupo G1. O grupo G1, por outro lado, tem dois membros - usuários GU1 e GU2. Os usuários GU1 e GU2 são, portanto, membros transitivos do grupo aninhado G1. Quatro objetos estão incluídos na revisão: usuários AU1, AU2, GU1 e GU2.

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

Exemplo 2: Examinar todos os usuários inativos com atribuição direta e transitiva a um grupo

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

Exemplo 3: Examinar todos os usuários convidados com atribuição direta e transitiva a um grupo

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

Exemplo 4: Examinar todos os usuários e grupos com atribuição direta a um grupo

O exemplo a seguir define o escopo da revisão para membros diretos do grupo que são usuários ou outros grupos. Neste escopo:

Os usuários diretos são incluídos na revisão.
Os grupos diretos são incluídos na revisão.
Os membros transitivos dos grupos, ou seja, membros de grupos aninhados, não são incluídos na revisão.

Exemplo de cenário: Suponha que o grupo A tenha três membros diretos - usuários AU1 e AU2 e grupo G1. O grupo G1, por outro lado, tem dois membros - usuários GU1 e GU2. Os usuários GU1 e GU2 são, portanto, membros transitivos do grupo aninhado G1. Apenas três objetos são visados nesta revisão, os usuários AU1 e AU2 e o grupo G1.

"scope": {
    "query": "/groups/{groupId}/members",
    "queryType": "MicrosoftGraph"
}

Exemplo 5: Revisar todos os usuários com atribuição direta a qualquer grupo do Microsoft 365

Como essa revisão se aplica a todos os grupos do Microsoft 365, configure o instanceEnumerationScope para especificar os grupos do Microsoft 365 a serem examinados. Os grupos de associação dinâmica ou atribuíveis a funções não estão incluídos nesta revisão.

"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"
}

Exemplo 6: Examinar todos os usuários convidados com atribuição direta a qualquer grupo do Microsoft 365

"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"
}

Exemplo 7: Examinar todos os usuários convidados inativos com atribuição direta a qualquer grupo do Microsoft 365

Como essa revisão se aplica a usuários inativos, use o recurso accessReviewInactiveUsersQueryScope e especifique a propriedade de tipo @odata.type com o valor #microsoft.graph.accessReviewInactiveUsersQueryScope. Além disso, como essa revisão se aplica a todos os grupos do Microsoft 365, configure o instanceEnumerationScope para especificar os grupos do Microsoft 365 a serem examinados. Os grupos de associação dinâmica ou atribuíveis a funções não estão incluídos nesta revisão.

"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"
}

Exemplo 8: Examinar todos os usuários convidados com atribuição direta ao Teams, exceto equipes com canais compartilhados

Como essa revisão se aplica a todos os grupos do Microsoft 365 associados ao Teams, configure o instanceEnumerationScope para especificar os grupos do Microsoft 365 associados ao Teams a serem examinados. Os grupos de associação dinâmica ou atribuíveis a funções não estão incluídos nesta revisão.

Esta revisão exclui usuários de conexão direta B2B no Teams com canais compartilhados. Para incluir usuários de conexão direta B2B em equipes com canais compartilhados, consulte o Exemplo 14: Examinar todos os usuários atribuídos a uma equipe, incluindo usuários de conexão direta B2B em uma equipe com canais compartilhados.

"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"
}

Exemplo 9: Examinar todos os usuários convidados inativos com atribuição direta ao Teams

"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"
}

Exemplo 10: Examinar todas as atribuições aos pacotes de acesso do Gerenciamento de Direitos

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

Exemplo 11: Examinar todas as entidades de serviço atribuídas a uma função privilegiada

"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"
}

Exemplo 12: Examinar usuários atribuídos a uma função de administrador do Microsoft Entra

Exemplo 12.1: Examinar todos os usuários com atribuições ativas ou qualificadas para uma função de diretório

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

Exemplo 12.2: Revisar todos os usuários com atribuições elegíveis para uma função de diretório

"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"
}

Exemplo 12.2: Revisar todos os usuários com atribuições ativas para uma função de diretório

"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"
}

Use principalResourceMembershipsScope para configurar o escopo

O principalResourceMembershipsScope expõe as propriedades principalScopes e resourceScopes para dar suporte a opções de configuração mais personalizadas para o escopo do objeto accessReviewScheduleDefinition . Os recursos incluem a revisão do acesso de várias entidades de segurança ou de grupos de entidades de segurança a vários recursos.

Exemplo 13: Examinar todos os usuários atribuídos a uma equipe, incluindo usuários de conexão direta B2B em uma equipe com canais compartilhados

Neste exemplo, o escopo de revisão de acesso inclui todos os usuários que são membros de uma equipe ou atribuídos a um canal compartilhado dentro da equipe. Esses membros incluem usuários internos, usuários diretos e transitivos, usuários de colaboração B2B e usuários de conexão direta 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",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/teams/{groupId}/channels?$filter=(membershipType eq 'shared')",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ]
}

Para examinar usuários e equipes de conexão direta B2B em canais compartilhados, especifique o /teams/{groupId}/channels?$filter=(membershipType eq 'shared') padrão de consulta no objeto resourceScopes. Uma revisão de todas as equipes , como os exemplos 8 e 9, não inclui usuários e equipes de conexão direta B2B em canais compartilhados.