Examinar o acesso a grupos de segurança usando APIs de revisões de acesso

A API de revisões de acesso no Microsoft Graph permite que as organizações auditem e atestem o acesso que as identidades (também chamadas de entidades) são atribuídas aos recursos na organização. Você pode usar grupos de segurança para gerenciar com eficiência o acesso aos recursos em sua organização. Por exemplo, acesse um site do SharePoint que contém guias estratégicos de marketing. E usando a API de revisões de acesso, as organizações podem atestar periodicamente as entidades que têm acesso a esses grupos e, por extensão, recursos na organização.

Neste tutorial, você aprende a:

  • Crie uma revisão de acesso recorrente de associações a grupos de segurança.
  • Atestar a necessidade de manter o acesso a um grupo.

Pré-requisitos

Para concluir este tutorial, você precisa dos seguintes recursos e privilégios:

  • Um locatário Microsoft Entra funcionando com uma licença P2 ou Microsoft Entra ID Governance Microsoft Entra ID habilitada.
  • Dois convidados de teste e um grupo de segurança de teste em seu locatário. Os convidados devem ser membros do grupo e o grupo deve ter pelo menos um proprietário.
  • Entre em um cliente de API, como o Graph Explorer chamar o Microsoft Graph com uma conta que tenha pelo menos a função administrador de governança de identidade.
    • [Opcional] Abra uma nova janela do navegador incógnito, anônimo ou InPrivate . Você entra mais tarde neste tutorial.
  • Conceda a si mesmo as seguintes permissões delegadas: AccessReview.ReadWrite.All.

Observação

Examine os grupos regidos pelo PIM apenas atribua proprietários ativos como os revisores. Os proprietários qualificados não estão incluídos. Pelo menos um revisor de fallback é necessário para a revisão de acesso de grupos regidos pelo PIM. Se não houver proprietários ativos quando a revisão começar, os revisores de fallback receberão a revisão.

Etapa 1: criar uma revisão de acesso para o grupo de segurança

Solicitação

Nesta chamada, substitua os seguintes valores:

  • eb75ccd2-59ef-48b7-8f76-cc3f33f899f4 com a ID do grupo de segurança.
  • Valor de startDate com a data e o valor de endDate de hoje com uma data de cinco dias a partir da data de início.

A revisão de acesso tem as seguintes configurações:

  • É uma revisão auto-atestando como inferida quando você não especifica um valor para a propriedade revisores . Portanto, cada membro do grupo atesta a necessidade de manter o acesso ao grupo.
  • O escopo da revisão é membros diretos e transitivos do grupo.
  • O revisor deve fornecer uma justificativa para o motivo pelo qual precisa manter o acesso ao grupo.
  • A decisão padrão é Deny quando os revisores não respondem à solicitação de revisão de acesso antes da instância expirar. A Deny decisão remove os membros do grupo do grupo.
  • É uma revisão de acesso único que termina após cinco dias. Portanto, depois que o acesso for concedido, o usuário não precisará atestar novamente dentro do período de revisão de acesso.
  • As entidades de segurança definidas no escopo da revisão recebem notificações por email e lembretes levando-os a auto-atestar sua necessidade de manter o acesso.
POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "One-time self-review for members of Building security",
    "descriptionForAdmins": "One-time self-review for members of Building security",
    "descriptionForReviewers": "One-time self-review for members of Building security",
    "scope": {
        "query": "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
        "queryType": "MicrosoftGraph"
    },
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 5,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2024-03-30"
            }
        }
    }
}

Resposta

O status da revisão de acesso é NotStarted. Você pode recuperar a revisão de acesso (GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b) para monitorar o status e quando seu status for InProgress, as instâncias foram criadas para a revisão de acesso e as decisões podem ser postadas. Você também pode recuperar a revisão de acesso para ver suas configurações completas.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
    "displayName": "One-time self-review for members of Building security",
    "createdDateTime": null,
    "lastModifiedDateTime": null,
    "status": "NotStarted",
    "descriptionForAdmins": "One-time self-review for members of Building security",
    "descriptionForReviewers": "One-time self-review for members of Building security",
    "scope": {},
    "instanceEnumerationScope": {},
    "reviewers": [],
    "fallbackReviewers": [],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 5,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": null,
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2024-03-30"
            }
        },
        "applyActions": [],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

Etapa 2: Listar instâncias da revisão de acesso

Depois que o status da revisão de acesso for marcado como InProgress, execute a consulta a seguir para listar todas as instâncias da definição de revisão de acesso. Como você criou uma revisão de acesso único na etapa anterior, a solicitação retorna apenas uma instância com uma ID como a ID da definição de agenda.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances

Resposta

Nesta resposta, o status da instância é InProgress porque startDateTime é passado e endDateTime está no futuro. Se startDateTime estiver no futuro, o status será NotStarted. Por outro lado, se endDateTime estiver no passado, o status será Completed.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances",
    "value": [
        {
            "id": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "startDateTime": "2024-03-21T17:35:25.24Z",
            "endDateTime": "2024-03-30T08:00:00Z",
            "status": "InProgress",
            "scope": {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers/microsoft.graph.user",
                "queryType": "MicrosoftGraph",
                "queryRoot": null
            },
            "reviewers": [],
            "fallbackReviewers": []
        }
    ]
}

Etapa 3: verificar quem foi contatado para a revisão

Você pode confirmar que todos os membros do grupo de segurança foram contatados para postar suas decisões de revisão para esta instância da revisão de acesso.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/contactedReviewers

Resposta

A resposta a seguir mostra que os dois membros do grupo de segurança foram notificados de sua revisão pendente.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/contactedReviewers",
    "@odata.count": 2,
    "value": [
        {
            "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "displayName": "Adele Vance",
            "userPrincipalName": "AdeleV@Contoso.com",
            "createdDateTime": "2024-03-21T17:35:34.4092545Z"
        },
        {
            "id": "bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
            "displayName": "Alex Wilber",
            "userPrincipalName": "AlexW@Contoso.com",
            "createdDateTime": "2024-03-21T17:35:34.4092545Z"
        }
    ]
}

Etapa 4: Obter decisões

Você está interessado nas decisões tomadas para a instância da revisão de acesso.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions

Resposta

A resposta a seguir mostra as decisões tomadas na instância da revisão. Como o grupo de segurança tem dois membros, dois itens de decisão são esperados.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/decisions",
    "@odata.count": 2,
    "value": [
        {
            "id": "4db68765-472d-4aa2-847a-433ea94bcfaf",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
                "displayName": "Alex Wilber",
                "type": "user",
                "userPrincipalName": "AlexW@Contoso.com",
                "lastUserSignInDateTime": "2/11/2022 5:31:37 PM +00:00"
            }
        },
        {
            "id": "c7de8fba-4d6a-4fab-a659-62ff0c02643d",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@Contoso.com",
                "lastUserSignInDateTime": "2/11/2022 4:58:13 PM +00:00"
            }
        }
    ]
}

Na chamada, a propriedade de decisão tem o valor de NotReviewed porque os membros do grupo não concluíram seu autoatendimento. A próxima etapa mostra como cada membro pode atestar a necessidade de revisão de acesso.

Etapa 5: auto-atestar uma decisão de acesso pendente

Você configurou a revisão de acesso como autoatendimento. Essa configuração exige que ambos os membros do grupo atestem a necessidade de manter o acesso ao grupo.

Observação

Conclua esta etapa como um dos dois membros do grupo de segurança.

Nesta etapa, você lista suas revisões de acesso pendentes e conclui o processo de autoatendimento. Você pode concluir essa etapa de duas maneiras, usando a API ou usando o portal Meu Acesso. O outro revisor não atesta e, em vez disso, as decisões padrão são aplicadas à revisão de acesso.

Inicie uma nova sessão de navegador incógnito, anônimo ou InPrivate e entre como um dos dois membros do grupo de segurança. Ao fazer isso, você não interrompe sua sessão de administrador atual. Como alternativa, você pode interromper sua sessão de administrador atual fazendo logon no Graph Explorer e fazendo logon como um dos dois membros do grupo.

Método 1: usar a API de revisões de acesso para auto-examinar o acesso pendente

Listar seus itens de decisão de revisão de acesso

Solicitação
GET https://graph.microsoft.com/v1.0/identitygovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions/filterByCurrentUser(on='reviewer')
Resposta

Na resposta, você (Adele Vance) tem uma revisão de acesso pendente (a decisão é NotReviewed) para auto-atestar. As propriedades principal e de recurso indicam a entidade de segurança à qual a decisão se aplica e o recurso ao qual o acesso está em análise. Nesse caso, Adele Vance e o grupo de segurança, respectivamente.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(accessReviewInstanceDecisionItem)",
    "@odata.count": 1,
    "value": [
        {
            "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItem",
            "id": "c7de8fba-4d6a-4fab-a659-62ff0c02643d",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@Contoso.com",
                "lastUserSignInDateTime": "2/15/2022 9:35:23 AM +00:00"
            }
        }
    ]
}

Registrar uma decisão

Para concluir a revisão de acesso, Adele Vance confirma a necessidade de manter o acesso ao grupo de segurança.

A solicitação retorna o código de resposta 204 No Content.

PATCH https://graph.microsoft.com/v1.0/identitygovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions/c7de8fba-4d6a-4fab-a659-62ff0c02643d

{
    "decision": "Approve",
    "justification": "As the assistant security manager, I still need access to the building security group."
}

Verificar as decisões

Para verificar as decisões que você gravou para sua revisão de acesso, liste seus itens de decisão de revisão de acesso. Embora o período de revisão de acesso não tenha expirado nem as decisões aplicadas, o applyResult está marcado como New e você pode alterar a decisão.

Agora você pode sair e sair da sessão do navegador incógnito.

Método 2: usar o portal Meu Acesso

Como alternativa, você pode marcar suas instâncias pendentes de revisão de acesso por meio do portal Meu Acesso.

  • Liste as revisões de acesso pendentes. O usuário pode seguir uma das duas maneiras de chegar lá:

    • Opção 1: selecione Examinar o botão de acesso na notificação por email que eles receberam na caixa de entrada. A notificação por email é semelhante à captura de tela a seguir. Este botão é um link direto para a revisão de acesso pendente.

    Email notificação para revisar seu acesso.

    • Opção 2: acesse o portal do portal Meu Acesso . Selecione o menu Revisões de acesso e selecione a guia Grupos e Aplicativos .
  • Na lista de revisões de acesso, selecione a revisão de acesso para a qual você deseja postar a decisão. Selecione Sim para postar a decisão de que você ainda precisa de acesso à segurança de construção. Insira um motivo e selecione Enviar.

    Atestar a necessidade de manter o acesso a um recurso.

Agora você pode sair e sair da sessão do navegador incógnito.

Etapa 6: confirmar as decisões e o status da revisão de acesso

De volta à sessão do navegador main em que você ainda está conectado com privilégios de administrador, repita a Etapa 4 para ver que a propriedade de decisão de Adele Vance agora Approveé . Quando a revisão de acesso termina ou expira, a decisão padrão de Deny é registrada para Alex Wilber. As decisões são então aplicadas automaticamente porque o autoApplyDecisionsEnabled foi definido como true e o período da instância de revisão de acesso terminou. Adele mantém o acesso ao grupo de segurança enquanto Alex é removido automaticamente do grupo.

Parabéns! Você criou uma revisão de acesso e atestou sua necessidade de manter o acesso. Você só atestou uma vez e manterá seu acesso até que ele seja removido por meio de uma Deny decisão de outra instância de revisão de acesso ou por meio de outro processo interno.

Etapa 7: Limpar recursos

Nesta chamada, você exclui a definição de revisão de acesso. Como a definição de agenda de revisão de acesso é o blueprint para a revisão de acesso, excluir a definição remove as configurações, instâncias e decisões relacionadas.

A solicitação retorna o código de resposta 204 No Content.

DELETE https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b

Conclusão

Você criou uma revisão de acesso na qual as entidades de segurança atestam a necessidade de manter o acesso a um recurso, nesse caso, o grupo de segurança building .

Este tutorial demonstrou um dos cenários da API de revisões de acesso Microsoft Entra. A API de revisões de acesso dá suporte a cenários diferentes por meio de uma combinação de recursos, entidades e revisores para atender às suas necessidades de atestado de acesso. Para obter mais informações, confira a API de revisões de acesso.