Partilhar via

Examinar o acesso de convidado a grupos usando APIs de revisões de acesso

  • Artigo

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. Com a colaboração B2B, você pode usar grupos do Microsoft 365 para gerenciar com eficiência o acesso de convidados a recursos como arquivos, anotações, calendários e até conversas do Teams. 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, outros recursos na organização.

Neste tutorial, você aprende a:

  • Crie uma revisão de acesso recorrente dos grupos do Microsoft 365 com convidados.
  • Investigue as decisões aplicadas às revisões de acesso.

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.
  • Um convidado de teste e um grupo de teste do Microsoft 365 em seu locatário. O convidado deve ser membro do grupo microsoft 365.
  • 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.
  • Conceda a si mesmo as seguintes permissões delegadas: AccessReview.ReadWrite.All.

Etapa 1: criar uma revisão de acesso para todos os grupos do Microsoft 365 com convidados

A série de revisão de acesso a seguir usa as seguintes configurações:

  • É uma revisão de acesso recorrente e revisada trimestralmente.
  • Os proprietários do grupo são os tomadores de decisão.
  • O escopo de revisão é limitado apenas a grupos do Microsoft 365 com convidados.
  • Ele define um usuário como o revisor de fallback que pode examinar o acesso caso o grupo não tenha nenhum proprietário atribuído.
  • autoApplyDecisionsEnabled está definido como true. Nesse caso, as decisões são aplicadas automaticamente depois que o revisor concluir a revisão de acesso ou a duração da revisão de acesso terminar. Se não estiver habilitado, um usuário deverá aplicar as decisões manualmente após a conclusão da revisão.
  • applyActions é definido como removeAccessApplyAction. Essa ação remove convidados negados do grupo. O convidado ainda pode entrar no locatário, mas não será membro do grupo ou terá os privilégios de acesso concedidos por meio do grupo.

Solicitação

Nesta chamada, substitua os seguintes valores:

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 com a ID do revisor de fallback.
  • Valor de startDate com a data e o valor de endDate de hoje com uma data de um ano a partir da data de início.
POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Guest access to marketing group",
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/v1.0/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "fallbackReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 3,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": "P30D",
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "endDate",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2025-03-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

Resposta

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": "c22ae540-b89a-4d24-bac0-4ef35e6591ea",
    "displayName": "Guest access to marketing group",
    "createdDateTime": null,
    "lastModifiedDateTime": null,
    "status": "NotStarted",
    "descriptionForAdmins": null,
    "descriptionForReviewers": null,
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "instanceEnumerationScope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "fallbackReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 3,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": "P30D",
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "endDate",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2025-03-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

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

A consulta a seguir lista todas as instâncias da definição de revisão de acesso. Se houver mais de um grupo do Microsoft 365 com convidados em seu locatário, essa solicitação retornará uma instância para cada grupo do Microsoft 365 com convidados.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances

Resposta

Nesta resposta, o escopo inclui o grupo de teste porque ele tem um convidado. Nesta resposta, a instância de revisão de acesso é atualmente InProgress. Como é uma revisão trimestral, uma nova instância de revisão é criada automaticamente a cada três meses e os revisores podem aplicar novas decisões.

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('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances",
    "value": [
        {
            "id": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "startDateTime": "2024-03-21T17:00:36.96Z",
            "endDateTime": "2024-03-24T17:00:36.96Z",
            "status": "InProgress",
            "scope": {
                "query": "/groups/59ab642a-2776-4e32-9b68-9ff7a47b7f6a/members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
                "queryType": "MicrosoftGraph"
            }
        }
    ]
}

Etapa 3: Obter decisões

Obtenha as decisões tomadas para a instância de uma revisão de acesso. Em uma revisão trimestral como esta, e desde que a revisão de acesso ainda esteja ativa:

  • A cada três meses, uma nova instância de revisão é criada.
  • Os revisores são necessários para aplicar novas decisões para novas instâncias.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances/6392b1a7-9c25-4844-83e5-34e23c88e16a/decisions

Resposta

A resposta a seguir mostra a decisão tomada para a instância da revisã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('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances('6392b1a7-9c25-4844-83e5-34e23c88e16a')/decisions",
    "@odata.count": 1,
    "value": [
        {
            "id": "0e76ee07-b4c6-469e-bc9d-e73fc9a8d660",
            "accessReviewId": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "reviewedDateTime": "2021-02-10T17:06:26.147Z",
            "decision": "Approve",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Deny",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "AAD Access Reviews",
                "userPrincipalName": "AAD Access Reviews"
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "target": {
                "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItemUserTarget",
                "userId": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20",
                "userDisplayName": "John Doe (Tailspin Toys)",
                "userPrincipalName": "john@tailspintoys.com"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20",
                "displayName": "John Doe (Tailspin Toys)",
                "userPrincipalName": "john@tailspintoys.com"
            }
        }
    ]
}

Etapa 4: Limpar recursos

Nesta etapa, 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 uma 204 No Content resposta.

DELETE https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea

Conteúdo relacionado