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"
            }
        }
    }
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new AccessReviewScheduleDefinition
{
	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 = new AccessReviewScope
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"query" , "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers"
			},
			{
				"queryType" , "MicrosoftGraph"
			},
		},
	},
	InstanceEnumerationScope = new AccessReviewScope
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"query" , "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4"
			},
			{
				"queryType" , "MicrosoftGraph"
			},
		},
	},
	Settings = new AccessReviewScheduleSettings
	{
		MailNotificationsEnabled = true,
		ReminderNotificationsEnabled = true,
		JustificationRequiredOnApproval = true,
		DefaultDecisionEnabled = true,
		DefaultDecision = "Deny",
		InstanceDurationInDays = 5,
		AutoApplyDecisionsEnabled = true,
		RecommendationsEnabled = true,
		Recurrence = new PatternedRecurrence
		{
			Pattern = null,
			Range = new RecurrenceRange
			{
				Type = RecurrenceRangeType.Numbered,
				NumberOfOccurrences = 0,
				RecurrenceTimeZone = null,
				StartDate = new Date(DateTime.Parse("2024-03-21")),
				EndDate = new Date(DateTime.Parse("2024-03-30")),
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.IdentityGovernance.AccessReviews.Definitions.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewAccessReviewScheduleDefinition()
displayName := "One-time self-review for members of Building security"
requestBody.SetDisplayName(&displayName) 
descriptionForAdmins := "One-time self-review for members of Building security"
requestBody.SetDescriptionForAdmins(&descriptionForAdmins) 
descriptionForReviewers := "One-time self-review for members of Building security"
requestBody.SetDescriptionForReviewers(&descriptionForReviewers) 
scope := graphmodels.NewAccessReviewScope()
additionalData := map[string]interface{}{
	"query" : "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers", 
	"queryType" : "MicrosoftGraph", 
}
scope.SetAdditionalData(additionalData)
requestBody.SetScope(scope)
instanceEnumerationScope := graphmodels.NewAccessReviewScope()
additionalData := map[string]interface{}{
	"query" : "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4", 
	"queryType" : "MicrosoftGraph", 
}
instanceEnumerationScope.SetAdditionalData(additionalData)
requestBody.SetInstanceEnumerationScope(instanceEnumerationScope)
settings := graphmodels.NewAccessReviewScheduleSettings()
mailNotificationsEnabled := true
settings.SetMailNotificationsEnabled(&mailNotificationsEnabled) 
reminderNotificationsEnabled := true
settings.SetReminderNotificationsEnabled(&reminderNotificationsEnabled) 
justificationRequiredOnApproval := true
settings.SetJustificationRequiredOnApproval(&justificationRequiredOnApproval) 
defaultDecisionEnabled := true
settings.SetDefaultDecisionEnabled(&defaultDecisionEnabled) 
defaultDecision := "Deny"
settings.SetDefaultDecision(&defaultDecision) 
instanceDurationInDays := int32(5)
settings.SetInstanceDurationInDays(&instanceDurationInDays) 
autoApplyDecisionsEnabled := true
settings.SetAutoApplyDecisionsEnabled(&autoApplyDecisionsEnabled) 
recommendationsEnabled := true
settings.SetRecommendationsEnabled(&recommendationsEnabled) 
recurrence := graphmodels.NewPatternedRecurrence()
pattern := null
recurrence.SetPattern(&pattern) 
range := graphmodels.NewRecurrenceRange()
type := graphmodels.NUMBERED_RECURRENCERANGETYPE 
range.SetType(&type) 
numberOfOccurrences := int32(0)
range.SetNumberOfOccurrences(&numberOfOccurrences) 
recurrenceTimeZone := null
range.SetRecurrenceTimeZone(&recurrenceTimeZone) 
startDate := 2024-03-21
range.SetStartDate(&startDate) 
endDate := 2024-03-30
range.SetEndDate(&endDate) 
recurrence.SetRange(range)
settings.SetRecurrence(recurrence)
requestBody.SetSettings(settings)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
definitions, err := graphClient.IdentityGovernance().AccessReviews().Definitions().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

AccessReviewScheduleDefinition accessReviewScheduleDefinition = new AccessReviewScheduleDefinition();
accessReviewScheduleDefinition.setDisplayName("One-time self-review for members of Building security");
accessReviewScheduleDefinition.setDescriptionForAdmins("One-time self-review for members of Building security");
accessReviewScheduleDefinition.setDescriptionForReviewers("One-time self-review for members of Building security");
AccessReviewScope scope = new AccessReviewScope();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("query", "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers");
additionalData.put("queryType", "MicrosoftGraph");
scope.setAdditionalData(additionalData);
accessReviewScheduleDefinition.setScope(scope);
AccessReviewScope instanceEnumerationScope = new AccessReviewScope();
HashMap<String, Object> additionalData1 = new HashMap<String, Object>();
additionalData1.put("query", "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4");
additionalData1.put("queryType", "MicrosoftGraph");
instanceEnumerationScope.setAdditionalData(additionalData1);
accessReviewScheduleDefinition.setInstanceEnumerationScope(instanceEnumerationScope);
AccessReviewScheduleSettings settings = new AccessReviewScheduleSettings();
settings.setMailNotificationsEnabled(true);
settings.setReminderNotificationsEnabled(true);
settings.setJustificationRequiredOnApproval(true);
settings.setDefaultDecisionEnabled(true);
settings.setDefaultDecision("Deny");
settings.setInstanceDurationInDays(5);
settings.setAutoApplyDecisionsEnabled(true);
settings.setRecommendationsEnabled(true);
PatternedRecurrence recurrence = new PatternedRecurrence();
recurrence.setPattern(null);
RecurrenceRange range = new RecurrenceRange();
range.setType(RecurrenceRangeType.Numbered);
range.setNumberOfOccurrences(0);
range.setRecurrenceTimeZone(null);
LocalDate startDate = LocalDate.parse("2024-03-21");
range.setStartDate(startDate);
LocalDate endDate = LocalDate.parse("2024-03-30");
range.setEndDate(endDate);
recurrence.setRange(range);
settings.setRecurrence(recurrence);
accessReviewScheduleDefinition.setSettings(settings);
AccessReviewScheduleDefinition result = graphClient.identityGovernance().accessReviews().definitions().post(accessReviewScheduleDefinition);


const options = {
	authProvider,
};

const client = Client.init(options);

const accessReviewScheduleDefinition = {
    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'
            }
        }
    }
};

await client.api('/identityGovernance/accessReviews/definitions')
	.post(accessReviewScheduleDefinition);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\AccessReviewScheduleDefinition;
use Microsoft\Graph\Generated\Models\AccessReviewScope;
use Microsoft\Graph\Generated\Models\AccessReviewScheduleSettings;
use Microsoft\Graph\Generated\Models\PatternedRecurrence;
use Microsoft\Graph\Generated\Models\RecurrenceRange;
use Microsoft\Graph\Generated\Models\RecurrenceRangeType;
use Microsoft\Kiota\Abstractions\Types\Date;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new AccessReviewScheduleDefinition();
$requestBody->setDisplayName('One-time self-review for members of Building security');
$requestBody->setDescriptionForAdmins('One-time self-review for members of Building security');
$requestBody->setDescriptionForReviewers('One-time self-review for members of Building security');
$scope = new AccessReviewScope();
$additionalData = [
	'query' => '/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers',
	'queryType' => 'MicrosoftGraph',
];
$scope->setAdditionalData($additionalData);
$requestBody->setScope($scope);
$instanceEnumerationScope = new AccessReviewScope();
$additionalData = [
	'query' => '/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4',
	'queryType' => 'MicrosoftGraph',
];
$instanceEnumerationScope->setAdditionalData($additionalData);
$requestBody->setInstanceEnumerationScope($instanceEnumerationScope);
$settings = new AccessReviewScheduleSettings();
$settings->setMailNotificationsEnabled(true);
$settings->setReminderNotificationsEnabled(true);
$settings->setJustificationRequiredOnApproval(true);
$settings->setDefaultDecisionEnabled(true);
$settings->setDefaultDecision('Deny');
$settings->setInstanceDurationInDays(5);
$settings->setAutoApplyDecisionsEnabled(true);
$settings->setRecommendationsEnabled(true);
$settingsRecurrence = new PatternedRecurrence();
$settingsRecurrence->setPattern(null);
$settingsRecurrenceRange = new RecurrenceRange();
$settingsRecurrenceRange->setType(new RecurrenceRangeType('numbered'));
$settingsRecurrenceRange->setNumberOfOccurrences(0);
$settingsRecurrenceRange->setRecurrenceTimeZone(null);
$settingsRecurrenceRange->setStartDate(new Date('2024-03-21'));
$settingsRecurrenceRange->setEndDate(new Date('2024-03-30'));
$settingsRecurrence->setRange($settingsRecurrenceRange);
$settings->setRecurrence($settingsRecurrence);
$requestBody->setSettings($settings);

$result = $graphServiceClient->identityGovernance()->accessReviews()->definitions()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Identity.Governance

$params = @{
	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"
			}
		}
	}
}

New-MgIdentityGovernanceAccessReviewDefinition -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.access_review_schedule_definition import AccessReviewScheduleDefinition
from msgraph.generated.models.access_review_scope import AccessReviewScope
from msgraph.generated.models.access_review_schedule_settings import AccessReviewScheduleSettings
from msgraph.generated.models.patterned_recurrence import PatternedRecurrence
from msgraph.generated.models.recurrence_range import RecurrenceRange
from msgraph.generated.models.recurrence_range_type import RecurrenceRangeType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = AccessReviewScheduleDefinition(
	display_name = "One-time self-review for members of Building security",
	description_for_admins = "One-time self-review for members of Building security",
	description_for_reviewers = "One-time self-review for members of Building security",
	scope = AccessReviewScope(
		additional_data = {
				"query" : "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers",
				"query_type" : "MicrosoftGraph",
		}
	),
	instance_enumeration_scope = AccessReviewScope(
		additional_data = {
				"query" : "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
				"query_type" : "MicrosoftGraph",
		}
	),
	settings = AccessReviewScheduleSettings(
		mail_notifications_enabled = True,
		reminder_notifications_enabled = True,
		justification_required_on_approval = True,
		default_decision_enabled = True,
		default_decision = "Deny",
		instance_duration_in_days = 5,
		auto_apply_decisions_enabled = True,
		recommendations_enabled = True,
		recurrence = PatternedRecurrence(
			pattern = None,
			range = RecurrenceRange(
				type = RecurrenceRangeType.Numbered,
				number_of_occurrences = 0,
				recurrence_time_zone = None,
				start_date = "2024-03-21",
				end_date = "2024-03-30",
			),
		),
	),
)

result = await graph_client.identity_governance.access_reviews.definitions.post(request_body)

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.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.IdentityGovernance.AccessReviews.Definitions["{accessReviewScheduleDefinition-id}"].Instances.GetAsync();



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
instances, err := graphClient.IdentityGovernance().AccessReviews().Definitions().ByAccessReviewScheduleDefinitionId("accessReviewScheduleDefinition-id").Instances().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

AccessReviewInstanceCollectionResponse result = graphClient.identityGovernance().accessReviews().definitions().byAccessReviewScheduleDefinitionId("{accessReviewScheduleDefinition-id}").instances().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let instances = await client.api('/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->identityGovernance()->accessReviews()->definitions()->byAccessReviewScheduleDefinitionId('accessReviewScheduleDefinition-id')->instances()->get()->wait();


Import-Module Microsoft.Graph.Identity.Governance

Get-MgIdentityGovernanceAccessReviewDefinitionInstance -AccessReviewScheduleDefinitionId $accessReviewScheduleDefinitionId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.identity_governance.access_reviews.definitions.by_access_review_schedule_definition_id('accessReviewScheduleDefinition-id').instances.get()

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.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.IdentityGovernance.AccessReviews.Definitions["{accessReviewScheduleDefinition-id}"].Instances["{accessReviewInstance-id}"].ContactedReviewers.GetAsync();



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
contactedReviewers, err := graphClient.IdentityGovernance().AccessReviews().Definitions().ByAccessReviewScheduleDefinitionId("accessReviewScheduleDefinition-id").Instances().ByAccessReviewInstanceId("accessReviewInstance-id").ContactedReviewers().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

AccessReviewReviewerCollectionResponse result = graphClient.identityGovernance().accessReviews().definitions().byAccessReviewScheduleDefinitionId("{accessReviewScheduleDefinition-id}").instances().byAccessReviewInstanceId("{accessReviewInstance-id}").contactedReviewers().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let contactedReviewers = await client.api('/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/contactedReviewers')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->identityGovernance()->accessReviews()->definitions()->byAccessReviewScheduleDefinitionId('accessReviewScheduleDefinition-id')->instances()->byAccessReviewInstanceId('accessReviewInstance-id')->contactedReviewers()->get()->wait();


Import-Module Microsoft.Graph.Identity.Governance

Get-MgIdentityGovernanceAccessReviewDefinitionInstanceContactedReviewer -AccessReviewScheduleDefinitionId $accessReviewScheduleDefinitionId -AccessReviewInstanceId $accessReviewInstanceId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.identity_governance.access_reviews.definitions.by_access_review_schedule_definition_id('accessReviewScheduleDefinition-id').instances.by_access_review_instance_id('accessReviewInstance-id').contacted_reviewers.get()

Resposta

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.IdentityGovernance.AccessReviews.Definitions["{accessReviewScheduleDefinition-id}"].Instances["{accessReviewInstance-id}"].Decisions.GetAsync();



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
decisions, err := graphClient.IdentityGovernance().AccessReviews().Definitions().ByAccessReviewScheduleDefinitionId("accessReviewScheduleDefinition-id").Instances().ByAccessReviewInstanceId("accessReviewInstance-id").Decisions().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

AccessReviewInstanceDecisionItemCollectionResponse result = graphClient.identityGovernance().accessReviews().definitions().byAccessReviewScheduleDefinitionId("{accessReviewScheduleDefinition-id}").instances().byAccessReviewInstanceId("{accessReviewInstance-id}").decisions().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let decisions = await client.api('/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->identityGovernance()->accessReviews()->definitions()->byAccessReviewScheduleDefinitionId('accessReviewScheduleDefinition-id')->instances()->byAccessReviewInstanceId('accessReviewInstance-id')->decisions()->get()->wait();


Import-Module Microsoft.Graph.Identity.Governance

Get-MgIdentityGovernanceAccessReviewDefinitionInstanceDecision -AccessReviewScheduleDefinitionId $accessReviewScheduleDefinitionId -AccessReviewInstanceId $accessReviewInstanceId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.identity_governance.access_reviews.definitions.by_access_review_schedule_definition_id('accessReviewScheduleDefinition-id').instances.by_access_review_instance_id('accessReviewInstance-id').decisions.get()

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.

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.

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.
- 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.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.IdentityGovernance.AccessReviews.Definitions["{accessReviewScheduleDefinition-id}"].DeleteAsync();



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.IdentityGovernance().AccessReviews().Definitions().ByAccessReviewScheduleDefinitionId("accessReviewScheduleDefinition-id").Delete(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.identityGovernance().accessReviews().definitions().byAccessReviewScheduleDefinitionId("{accessReviewScheduleDefinition-id}").delete();


const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b')
	.version('beta')
	.delete();


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$graphServiceClient->identityGovernance()->accessReviews()->definitions()->byAccessReviewScheduleDefinitionId('accessReviewScheduleDefinition-id')->delete()->wait();


Import-Module Microsoft.Graph.Beta.Identity.Governance

Remove-MgBetaIdentityGovernanceAccessReviewDefinition -AccessReviewScheduleDefinitionId $accessReviewScheduleDefinitionId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.identity_governance.access_reviews.definitions.by_access_review_schedule_definition_id('accessReviewScheduleDefinition-id').delete()

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.

Comentários

Esta página foi útil?

Last updated on 2025-03-18

Compartilhar via

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

Pré-requisitos

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

Solicitação

Resposta

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

Solicitação

Resposta

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

Solicitação

Resposta

Passo 4: Obter decisões

Solicitação

Resposta

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

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

Resposta

Registar uma decisão

Verificar as decisões

Método 2: Utilizar o portal O Meu Acesso

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

Etapa 7: Limpar recursos

Conclusão

Conteúdo relacionado

Comentários

Recursos adicionais