Configurar o escopo das revisões de acesso usando APIs de revisões de acesso
As APIs de acesso Microsoft Entra permitem que você examine programaticamente o acesso que usuários, entidades de serviço ou grupos precisam Microsoft Entra recursos em seu locatário.
Você configura os recursos Microsoft Entra a serem revisados na propriedade de escopo do recurso accessReviewScheduleDefinition. Os recursos a seguir expõem as configurações para configurar o escopo da revisão de acesso:
| Recurso | Descrição | Cenários de revisão de acesso de exemplo |
|---|---|---|
| accessReviewQueryScope | Melhor aplicável ao revisar o conjunto completo ou o subconjunto de entidades que têm acesso a um recurso ou grupo de recursos relacionados. |
|
| accessReviewInactiveUsersQueryScope | Herda do accessReviewQueryScope. Usado quando somente usuários inativos são revisados. Seu status inativo é especificado pela propriedade inactiveDuration. |
|
| principalResourceMembershipsScope | Herda do accessReviewScope. Aplicável melhor para examinar o acesso das entidades aos recursos em que você configura pools exclusivos de entidades e recursos. |
|
Neste artigo, você aprenderá a escopo de sua revisão de acesso configurando os três tipos de recurso derivados.
Configurar escopo usando accessReviewQueryScope e accessReviewInactiveUsersQueryScope
Para configurar o escopo usando o tipo de recurso accessReviewQueryScope, defina os valores de suas propriedades queryRoot e queryType.
accessReviewInactiveUsersQueryScope requer todas as propriedades do accessReviewQueryScope e inclui uma propriedade inactiveDuration .
Exemplo 1: examinar todos os usuários com atribuição direta e transitiva para um grupo
Cenário de exemplo: 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 para um grupo
Como essa revisão é aplicada a usuários inativos, use o recurso accessReviewInactiveUsersQueryScope e especifique a propriedade @odata.type com o valor #microsoft.graph.accessReviewInactiveUsersQueryScope.
"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 para 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 escopos da revisão para apenas 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 estão incluídos na revisão.
Cenário de exemplo: 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. Somente três objetos são direcionados nesta revisão, usuários AU1 e AU2 e grupo G1.
"scope": {
"query": "/groups/{groupId}/members",
"queryType": "MicrosoftGraph"
}
Exemplo 5: examinar todos os usuários com atribuição direta para qualquer grupo do Microsoft 365
Como essa revisão é aplicada em todos os grupos do Microsoft 365, configure a instânciaEnumerationScope para especificar os grupos do Microsoft 365 a serem revisados. Grupos que são de associação dinâmica ou atribuição de função 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
Como essa revisão é aplicada em todos os grupos do Microsoft 365, configure a instânciaEnumerationScope para especificar os grupos do Microsoft 365 a serem revisados. Grupos que são de associação dinâmica ou atribuição de função 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/?$filter=(userType eq 'Guest')",
"queryType": "MicrosoftGraph"
}
Exemplo 7: examinar todos os usuários convidados inativos com atribuição direta para qualquer grupo do Microsoft 365
Como essa revisão é aplicada a usuários inativos, use o recurso accessReviewInactiveUsersQueryScope e especifique a propriedade @odata.type com o valor #microsoft.graph.accessReviewInactiveUsersQueryScope. Além disso, como essa revisão é aplicada em todos os grupos do Microsoft 365, configure a instânciaEnumerationScope para especificar os grupos do Microsoft 365 a serem revisados. Grupos que são de associação dinâmica ou atribuição de função 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 para equipes, exceto equipes com canais compartilhados
Como essa revisão é aplicada em todos os grupos do Microsoft 365 associados ao Teams, configure a instânciaEnumerationScope para especificar os grupos microsoft 365 associados ao Teams a serem revisados. Grupos que são de associação dinâmica ou atribuição de função não estão incluídos nesta revisão.
Esta revisão não inclui usuários de conexão direta B2B em equipes com canais compartilhados. Para incluir usuários de conexão direta B2B em equipes com canais compartilhados, confira Exemplo 14: Examine 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 às equipes
Como essa revisão é aplicada em todos os grupos do Microsoft 365 associados ao Teams, configure a instânciaEnumerationScope para especificar os grupos microsoft 365 associados ao Teams a serem revisados. Grupos que são de associação dinâmica ou atribuição de função não estão incluídos nesta revisão.
Esta revisão não inclui usuários de conexão direta B2B em equipes com canais compartilhados. Para incluir usuários de conexão direta B2B em equipes com canais compartilhados, confira Exemplo 14: Examine 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.accessReviewInactiveUsersQueryScope",
"query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
"queryType": "MicrosoftGraph",
"inactiveDuration": "P30D"
}
Exemplo 10: examinar toda a atribuição para 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 Microsoft Entra
Exemplo 12.1: examine 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: examine todos os usuários com atribuições qualificadas 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: examinar 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"
}
Usar 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 para várias entidades ou grupos de entidades de segurança para vários recursos.
Exemplo 13: examinar todos os usuários convidados inativos com atribuição direta a grupos
"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"
}
]
}
Exemplo 14: examine 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 é 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 do B2B em canais compartilhados, você deve especificar 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 de conexão direta B2B e equipes em canais compartilhados.
Observação
A revisão de acesso de usuários e equipes de conexão direta B2B só tem suporte para revisões de acesso em estágio único e não para revisões de acesso em vários estágios.
Exemplo 15: examinar todos os usuários convidados atribuídos a uma função de diretório
"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"
}
]
}
Exemplo 16: examinar todos os usuários com atribuição direta ou transitiva para um aplicativo
"scope": {
"@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
"principalScopes": [
{
"@odata.type": "#microsoft.graph.accessReviewQueryScope",
"query": "/v1.0/users",
"queryType": "MicrosoftGraph",
"queryRoot": null
},
{
"@odata.type": "#microsoft.graph.accessReviewQueryScope",
"query": "./members/microsoft.graph.user",
"queryType": "MicrosoftGraph",
"queryRoot": "/v1.0/groups"
}
],
"resourceScopes": [
{
"@odata.type": "#microsoft.graph.accessReviewQueryScope",
"query": "/v1.0/servicePrincipals/{servicePrincipalId}",
"queryType": "MicrosoftGraph",
"queryRoot": null
}
]
}
Conteúdo relacionado
- Atribuir revisores à definição de revisão de acesso
- Experimente tutoriais para saber como usar a API de revisões de acesso para examinar o acesso aos recursos de Microsoft Entra
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de