Partilhar via


Rever o acesso a grupos de segurança através de APIs de revisões de acesso

As APIs de revisão de acesso no Microsoft Graph permitem às organizações auditar e atestar o acesso que as identidades (também denominadas principais) têm aos recursos. Pode utilizar grupos de segurança para gerir de forma eficiente o acesso aos recursos na sua organização, como um site do SharePoint com manuais de procedimentos de marketing. Ao utilizar a API de revisões de acesso, as organizações podem atestar periodicamente os principais que têm acesso a esses grupos e recursos.

Neste tutorial, você aprende a:

  • Crie uma revisão de acesso periódica de associações a grupos de segurança.
  • Atesta automaticlmente a necessidade de manter o acesso a um grupo.

Pré-requisitos

Para concluir este tutorial, precisa destes recursos e privilégios:

  • Um inquilino Microsoft Entra funcional com uma licença Microsoft Entra ID P2 ou Microsoft Entra ID Governance ativada.
  • Dois convidados de teste e um grupo de segurança de teste no seu inquilino. Os convidados devem ser membros do grupo e o grupo deve ter, pelo menos, um proprietário.
  • Inicie sessão num cliente de API, como o Graph Explorer para chamar o Microsoft Graph com uma conta que tenha, pelo menos, a função de Administrador de Governação de Identidades.
    • [Opcional] Abra uma nova janela anónima, anónima ou inPrivate do browser . Inicie sessão mais tarde neste tutorial.
  • Conceda a si mesmo as seguintes permissões delegadas: AccessReview.ReadWrite.All.

Observação

A revisão dos grupos regidos pelo PIM só atribui proprietários ativos como revisores. Os proprietários elegíveis não estão incluídos. É necessário, pelo menos, um revisor de contingência para a revisão de acesso dos grupos regidos pelo PIM. Se não existirem proprietários ativos quando a revisão começar, é atribuída a revisão aos revisores de contingência.

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

Solicitação

Nesta chamada, substitua estes valores:

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

A revisão de acesso utiliza estas definições:

  • É uma revisão de atestação automática como inferida quando não especifica um valor para a propriedade revisores . Por conseguinte, cada membro do grupo atesta de forma autónoma a necessidade de manter o acesso ao grupo.
  • O âmbito da revisão são os membros diretos e transitivos do grupo.
  • O revisor tem de fornecer uma justificação para a necessidade de manter o acesso ao grupo.
  • A decisão predefinida é Deny quando os revisores não respondem ao pedido de revisão de acesso antes de a instância expirar. A Deny decisão remove os membros do grupo do grupo.
  • É uma revisão de acesso única que termina após cinco dias. Por conseguinte, assim que o acesso for concedido, o utilizador não precisa de atestar automaticamente novamente dentro do período de revisão de acesso.
  • Os principais que são definidos no âmbito da revisão recebem notificações por email e lembretes que os pedem para atestarem a 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. Obtenha a revisão de acesso (GEThttps://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b) para monitorizar o status. Quando o respetivo status é InProgress, as instâncias são criadas para a revisão de acesso e as decisões podem ser publicadas. Também pode obter a revisão de acesso para ver as definiçõ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": []
}

Passo 2: listar instâncias da revisão de acesso

Assim que a status da revisão de acesso estiver marcada como InProgress, execute a seguinte consulta para listar todas as instâncias da definição de revisão de acesso. Uma vez que criou uma revisão de acesso única no passo anterior, o pedido devolve apenas uma instância com um ID, como o 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, a status da instância deve-se InProgress ao facto de startDateTime ter passado e endDateTime estar no futuro. Se startDateTime estiver no futuro, o status é NotStarted. Por outro lado, se endDateTime estiver no passado, o status é 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": []
        }
    ]
}

Passo 3: verificar quem foi contactado para a revisão

Pode confirmar que todos os membros do grupo de segurança foram contactados para publicar as respetivas 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 seguinte resposta mostra que os dois membros do grupo de segurança foram notificados da 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"
        }
    ]
}

Passo 4: Obter decisões

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 seguinte mostra as decisões tomadas na instância da revisão. Uma vez que o grupo de segurança tem dois membros, são esperados dois itens de decisão.

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 o seu auto-atestado. O passo seguinte mostra como cada membro pode atestar a sua necessidade de revisão de acesso.

Passo 5: Atestar automaticmente uma decisão de acesso pendente

Configurou a revisão de acesso como autotesting. Esta configuração requer que ambos os membros do grupo atestem automaticamente a necessidade de manter o acesso ao grupo.

Observação

Conclua este passo como um dos dois membros do grupo de segurança.

Neste passo, irá listar as revisões de acesso pendentes e concluir o processo de auto-atestado. Pode concluir este passo de uma de duas formas: utilizar a API ou o portal O Meu Acesso. O outro revisor não atesta automaticamente, pelo que as decisões predefinidas são aplicadas à revisão de acesso.

Inicie uma nova sessão de browser de navegação anónima, anónima ou InPrivate nova e inicie sessão como um dos dois membros do grupo de segurança. Ao fazê-lo, não interrompe a sua sessão de administrador atual. Em alternativa, pode interromper a sua sessão de administrador atual ao terminar sessão no Graph Explorer e voltar a iniciar sessão como um dos dois membros do grupo.

Inicie uma nova sessão de navegação anónima, anónima ou InPrivate nova e inicie sessão como um dos dois membros do grupo de segurança. Desta forma, não interrompe a sua sessão de administrador atual. Em alternativa, pode terminar sessão no Graph Explorer e voltar a iniciar sessão como um dos dois membros do grupo.

Método 1: Utilizar as APIs de revisões de acesso para rever automaticmente o acesso pendente

Listar os itens de decisão das revisões 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

A partir da resposta, o utilizador (Adele Vance) tem uma revisão de acesso pendente (a decisão é NotReviewed) para atestar por si próprio. As propriedades do principal e do recurso indicam o principal ao qual a decisão se aplica e o recurso ao qual o acesso está a ser analisado. Neste 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"
            }
        }
    ]
}

Registar 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 registou para a revisão de acesso, liste os 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, applyResult é marcado como New e pode alterar a decisão.

Agora pode terminar sessão e sair da sessão anónima do browser.

Método 2: Utilizar o portal O Meu Acesso

Em alternativa, pode marcar as instâncias de revisão de acesso pendentes através do portal O Meu Acesso.

  • Liste as revisões de acesso pendentes. O utilizador pode seguir uma de duas formas de aceder ao mesmo:

    • Opção 1: selecione o botão Rever acesso na notificação por e-mail que receberam na respetiva caixa de entrada de correio. A notificação por e-mail é semelhante à seguinte captura de ecrã. Este botão é uma ligação direta para a revisão de acesso pendente.

    Email notificação para rever o acesso.

    • Opção 2: aceda ao portal O Meu Acesso . Selecione o menu Revisões do Access e selecione o separador Grupos e Aplicações .
  • Na lista de revisões de acesso, selecione a revisão de acesso para a qual pretende publicar a decisão. Selecione Sim para publicar a decisão de que ainda precisa de acesso a Segurança de edifícios. Introduza um motivo e, em seguida, selecione Submeter.

    Atestarautomaticlmentemente a necessidade de manter o acesso a um recurso.

Agora pode terminar sessão e sair da sessão anónima do browser.

Passo 6: Confirmar as decisões e a status da revisão de acesso

Novamente na main sessão do browser onde ainda tem sessão iniciada com privilégios de administrador, repita o Passo 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 predefinida de Deny é registada para Alex Wilber. As decisões são aplicadas automaticamente porque 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! Criou uma revisão de acesso e atestado automaticamente para a sua necessidade de manter o acesso. Só atesta uma vez e mantém o acesso até que seja removido através de uma Deny decisão de outra instância de revisão de acesso ou de outro processo interno.

Etapa 7: Limpar recursos

Nesta chamada, irá eliminar a definição de revisão de acesso. Uma vez que a definição de agenda da revisão de acesso é o esquema da revisão de acesso, eliminar a definição remove as definiçõ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

Criou uma revisão de acesso na qual os principais atestaram automaticamente a necessidade de manter o acesso a um recurso, neste caso, o grupo de segurança Edifício .

Este tutorial demonstrou um dos cenários de automatização para as APIs de revisões de acesso Microsoft Entra. As APIs suportam diferentes cenários através de uma combinação de recursos, principais e revisores para se adequarem às suas necessidades de atestado de acesso. Para obter mais informações, veja a API de revisões de acesso.