Configurar o âmbito das revisões de acesso com as APIs de revisões de acesso

  • Artigo

As APIs Microsoft Entra de revisões de acesso permitem-lhe rever programaticamente o acesso que os utilizadores, principais de serviço ou grupos têm de Microsoft Entra recursos no seu inquilino.

Configure os recursos Microsoft Entra a rever na propriedade de âmbito do recurso accessReviewScheduleDefinition. Os seguintes recursos expõem as definições para configurar o âmbito da revisão de acesso:

Recurso Descrição Exemplos de cenários de revisão de acesso
accessReviewQueryScope Aplicável ao rever o conjunto completo ou subconjunto de principais que têm acesso a um recurso ou grupo de recursos relacionados.
  • Associação de utilizadores atribuídos a um grupo, membros diretos ou membros diretos e transitivos.
  • Acesso de utilizador convidado a um grupo.
  • Acesso de utilizador convidado a todos os grupos do Microsoft 365.
  • Principais de serviço atribuídos a funções com privilégios.
  • Acesso do principal de utilizador e serviço aos pacotes de acesso da Gestão de Direitos.
accessReviewInactiveUsersQueryScope Herda do accessReviewQueryScope. Utilizado quando apenas os utilizadores inativos são revistos. O respetivo status inativo é especificado pela propriedade inactiveDuration.
  • Associação a grupos apenas para utilizadores inativos
    principalResourceMembershipsScope Herda do accessReviewScope. Aplicável para rever o acesso dos principais aos recursos onde configura conjuntos exclusivos de principais e recursos.
    • Acesso a três principais específicos a um grupo do Microsoft 365 e a uma função de Microsoft Entra com privilégios.

      Neste artigo, vai aprender a definir o âmbito da sua revisão de acesso ao configurar os três tipos de recursos derivados.

      Configurar o âmbito com accessReviewQueryScope e accessReviewInactiveUsersQueryScope

      Para configurar o âmbito com o tipo de recurso accessReviewQueryScope, defina os valores das respetivas propriedades queryRoot e queryType.

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

      Exemplos

      Observação

      Os exemplos nesta secção mostram as únicas combinações válidas de principalScopes e resourceScopes que a Microsoft API do Graph suporta.

      Exemplo 1: rever todos os utilizadores com atribuição direta e transitiva a um grupo

      Cenário de exemplo: Suponha que o grupo A tem três membros diretos : utilizadores AU1 e AU2 e grupo G1. O grupo G1, por outro lado, tem dois membros : os utilizadores GU1 e GU2. Por conseguinte, os utilizadores GU1 e GU2 são membros transitivos do grupo aninhado G1. Estão incluídos quatro objetos na revisão: utilizadores AU1, AU2, GU1 e GU2.

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

      Exemplo 2: Rever todos os utilizadores inativos com atribuição direta e transitiva a um grupo

      Uma vez que esta revisão é aplicada a utilizadores inativos, utilize 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: Rever todos os utilizadores 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: Rever todos os utilizadores e grupos com atribuição direta a um grupo

      O exemplo seguinte define o âmbito da revisão apenas para os membros diretos do grupo que são utilizadores ou outros grupos. Neste âmbito:

      • Os utilizadores diretos estão incluídos na revisão.
      • Os grupos diretos estã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 tem três membros diretos : utilizadores AU1 e AU2 e grupo G1. O grupo G1, por outro lado, tem dois membros : os utilizadores GU1 e GU2. Por conseguinte, os utilizadores GU1 e GU2 são membros transitivos do grupo aninhado G1. Apenas três objetos são visados nesta revisão, os utilizadores AU1 e AU2 e o grupo G1.

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

      Exemplo 5: Rever todos os utilizadores com atribuição direta a qualquer grupo do Microsoft 365

      Uma vez que esta revisão é aplicada a todos os grupos do Microsoft 365, configure a instanceEnumerationScope para especificar os grupos do Microsoft 365 a rever. Grupos de associação dinâmica ou atribuível a funções não estão incluídas 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: Rever todos os utilizadores convidados com atribuição direta a qualquer grupo do Microsoft 365

      Uma vez que esta revisão é aplicada a todos os grupos do Microsoft 365, configure a instanceEnumerationScope para especificar os grupos do Microsoft 365 a rever. Grupos de associação dinâmica ou atribuível a funções não estão incluídas 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: Rever todos os utilizadores convidados inativos com atribuição direta a qualquer grupo do Microsoft 365

      Uma vez que esta revisão é aplicada a utilizadores inativos, utilize o recurso accessReviewInactiveUsersQueryScope e especifique a propriedade @odata.type com o valor #microsoft.graph.accessReviewInactiveUsersQueryScope. Além disso, uma vez que esta revisão é aplicada a todos os grupos do Microsoft 365, configure a instanceEnumerationScope para especificar os grupos do Microsoft 365 a rever. Grupos de associação dinâmica ou atribuível a funções não estão incluídas 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: Rever todos os utilizadores convidados com atribuição direta a equipas, exceto equipas com canais partilhados

      Uma vez que esta revisão é aplicada a todos os grupos do Microsoft 365 associados ao Teams, configure a instanceEnumerationScope para especificar os grupos do Microsoft 365 associados ao Teams a rever. Grupos de associação dinâmica ou atribuível a funções não estão incluídas nesta revisão.

      Esta revisão não inclui utilizadores B2B de ligação direta em equipas com canais partilhados. Para incluir utilizadores B2B de ligação direta em equipas com canais partilhados, consulte Exemplo 14: Rever todos os utilizadores atribuídos a uma equipa, incluindo os utilizadores B2B de ligação direta numa equipa com canais partilhados.

      "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: Rever todos os utilizadores convidados inativos com atribuição direta às equipas

      Uma vez que esta revisão é aplicada a todos os grupos do Microsoft 365 associados ao Teams, configure a instanceEnumerationScope para especificar os grupos do Microsoft 365 associados ao Teams a rever. Grupos de associação dinâmica ou atribuível a funções não estão incluídas nesta revisão.

      Esta revisão não inclui utilizadores B2B de ligação direta em equipas com canais partilhados. Para incluir utilizadores B2B de ligação direta em equipas com canais partilhados, consulte Exemplo 14: Rever todos os utilizadores atribuídos a uma equipa, incluindo os utilizadores B2B de ligação direta numa equipa com canais partilhados.

      "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: Rever toda a atribuição aos pacotes de acesso da Gestão 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: Rever todos os principais de serviço atribuídos a uma função com privilégios

      "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: Rever os utilizadores atribuídos a uma função de administrador Microsoft Entra

      Exemplo 12.1: Rever todos os utilizadores com atribuições ativas ou elegíveis para uma função de diretório

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

      Exemplo 12.2: Rever todos os utilizadores 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: Rever todos os utilizadores com atribuições ativas a 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"
}

      Utilizar principalResourceMembershipsScope para configurar o âmbito

      O principalResourceMembershipsScope expõe as propriedades principalScopes e resourceScopes para suportar opções de configuração mais personalizadas para o âmbito do objeto accessReviewScheduleDefinition . As capacidades incluem rever o acesso de vários principais ou grupos de principais a vários recursos.

      Exemplo 13: Rever todos os utilizadores atribuídos a uma equipa, incluindo utilizadores B2B de ligação direta numa equipa com canais partilhados

      Neste exemplo, o âmbito da revisão de acesso é todos os utilizadores que são membros de uma equipa ou atribuídos a um canal partilhado dentro da equipa. Estes membros incluem utilizadores internos, utilizadores diretos e transitivos, utilizadores de colaboração B2B e utilizadores B2B de ligação direta.

      "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 rever os utilizadores e as equipas de ligação direta B2B nos canais partilhados, tem de especificar o /teams/{groupId}/channels?$filter=(membershipType eq 'shared') padrão de consulta no objeto resourceScopes. Uma revisão de todas as equipas , como os exemplos 8 e 9, não inclui utilizadores de ligação direta B2B e equipas em canais partilhados.

      Observação

      A revisão de acesso de utilizadores e equipas de ligação direta B2B só é suportada para revisões de acesso de fase única e não para revisões de acesso em várias fases.

      Exemplo 14: Rever todos os utilizadores 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 15: Rever todos os utilizadores com atribuição direta ou transitiva a uma aplicação

      "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