Partilhar via


Gerenciar o acesso aos recursos usando as APIs de gerenciamento de direitos

Microsoft Entra gerenciamento de direitos permite gerenciar o acesso aos recursos que os funcionários precisam ser produtivos. Neste tutorial, você usa as APIs de gerenciamento de direitos para criar um pacote de recursos que os usuários internos solicitam. As APIs são a alternativa programática para criar aplicativos personalizados em vez de usar o centro de administração do Microsoft Entra.

Neste tutorial, você aprende a:

  • Crie um pacote de acesso que os usuários possam solicitar por autoatendimento.
  • Atribua um recurso de grupo ao pacote de acesso.
  • Solicitar um pacote 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. Qualquer uma dessas licenças é suficiente para os recursos neste tutorial.
  • Uma conta de convidado de teste e um grupo de segurança de teste em seu locatário. O grupo de segurança é o recurso neste tutorial. Certifique-se de ser o proprietário do grupo ou atribuiu a função Administrador de Grupos . Neste tutorial:
    • O usuário tem a ID 007d1c7e-7fa8-4e33-b678-5e437acdcddc e se chama Requestor1.
      • [Opcional] Abra uma nova janela anônima do navegador. Você entra mais tarde neste tutorial.
    • O grupo tem a ID f4892fac-e81c-4712-bdf2-a4450008a4b0 com o nome de exibição "Grupo de marketing" e "Recursos de marketing".
  • Entre em um cliente de API, como o Graph Explorer com uma conta que tenha pelo menos a função de Administrador de Governança de Identidade.
  • Conceda a si mesmo as seguintes permissões delegadas: User.ReadWrite.All, Group.ReadWrite.Alle EntitlementManagement.ReadWrite.All.

Observação

Algumas etapas neste tutorial usam o beta ponto de extremidade.

Etapa 1: adicionar recursos a um catálogo e criar um pacote de acesso

Um pacote de acesso é um pacote de recursos que uma equipe ou projeto precisa e é regido com políticas. Os pacotes de acesso são definidos em contêineres chamados catálogos. Os catálogos podem referenciar recursos, como grupos, aplicativos e sites, que são usados no pacote de acesso. O gerenciamento de direitos inclui um catálogo padrão General .

Nesta etapa, você cria um pacote de acesso à Campanha de Marketing no catálogo geral.

Etapa 1.1: Obter o identificador para o catálogo geral

Primeiro, obtenha a ID do catálogo ao qual você deseja adicionar recursos.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/catalogs?$filter=(displayName eq 'General')

Resposta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/entitlementManagement/catalogs?$select=catalogType,createdDateTime",
    "value": [
        {
            "id": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
            "displayName": "General",
            "description": "Built-in catalog.",
            "catalogType": "serviceDefault",
            "state": "published",
            "isExternallyVisible": true,
            "createdDateTime": "2023-04-13T14:43:19.44Z",
            "modifiedDateTime": "2023-04-13T14:43:19.44Z"
        }
    ]
}

Etapa 1.2: Adicionar o grupo ao catálogo

Neste tutorial, o recurso é um grupo de segurança que tem a ID e93e24d1-2b65-4a6c-a1dd-654a12225487.

Para adicionar o grupo que você criou ao catálogo, forneça os seguintes valores de propriedade:

  • catalogId - a ID do catálogo que você está usando
  • originId - a id do grupo que você criou

Se você não for o proprietário do grupo que você referencia na originId ou não tiver a função Administrador de Grupos , essa solicitação falhará com um 403 Forbidden código de erro.

Solicitação

POST https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/resourceRequests
Content-type: application/json

{
  "catalogId":"cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
  "requestType": "AdminAdd",
  "justification": "",
  "accessPackageResource": {
    "resourceType": "AadGroup",
    "originId": "e93e24d1-2b65-4a6c-a1dd-654a12225487",
    "originSystem": "AadGroup"
  }
}

Resposta

Nesta resposta, a id representa a ID do grupo como um recurso no catálogo geral. Essa ID não é a ID do grupo. Grave esta ID.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/resourceRequests/$entity",
    "id": "44e521e0-fb6b-4d5e-a282-e7e68dc59493",
    "requestType": "AdminAdd",
    "requestState": "Delivered",
    "requestStatus": "Fulfilled",
    "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
    "executeImmediately": false,
    "justification": "",
    "expirationDateTime": null
}

Etapa 1.3: Obter recursos de catálogo

Nesta etapa, você recupera os detalhes dos recursos que correspondem à ID do recurso de grupo que você adicionou ao catálogo geral.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/catalogs/cec5d6ab-c75d-47c0-9c1c-92e89f66e384/resources?$filter=originId eq 'e93e24d1-2b65-4a6c-a1dd-654a12225487'

Resposta

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs('cec5d6ab-c75d-47c0-9c1c-92e89f66e384')/resources",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/entitlementManagement/catalogs('<guid>')/resources?$select=attributes,createdDateTime",
  "value": [
    {
      "id": "4a1e21c5-8a76-4578-acb1-641160e076e8",
      "displayName": "Marketing resources",
      "description": "Marketing group",
      "originId": "e93e24d1-2b65-4a6c-a1dd-654a12225487",
      "originSystem": "AadGroup",
      "createdDateTime": "2024-03-26T09:44:50.527Z",
      "attributes": []
    }
  ]
}

Etapa 1.4: Obter funções de recursos

O pacote de acesso atribui os usuários às funções de um recurso. A função típica de um grupo é a Member função. Outros recursos, como sites e aplicativos do SharePoint Online, podem ter várias funções. A função típica de um grupo usado em um pacote de acesso é a Member função. Você precisa da função membro para adicionar uma função de recurso ao pacote de acesso posteriormente neste tutorial.

Na solicitação, use a ID do catálogo e a ID do recurso de grupo no catálogo que você gravou para obter a origemId da função de recurso membro. Registre o valor da propriedade originId a ser usada posteriormente neste tutorial.

Solicitação

GET https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/catalogs/ede67938-cda7-4127-a9ca-7c7bf86a19b7/resourceRoles?$filter=(originSystem eq 'AadGroup' and displayName eq 'Member' and resource/id eq '274a1e21c5-8a76-4578-acb1-641160e076e')&$expand=resource

Resposta

Como você filtrado pela originId, nome de exibição e ID do recurso, se tiver êxito, um único valor será retornado, o que representa a função Membro desse grupo. Se nenhuma função for retornada, marcar os valores de ID do catálogo e o recurso do pacote de acesso.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs('ede67938-cda7-4127-a9ca-7c7bf86a19b7')/resourceRoles(resource())",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET identityGovernance/entitlementManagement/catalogs('<guid>')/resourceRoles?$select=description,displayName",
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "displayName": "Member",
            "description": null,
            "originSystem": "AadGroup",
            "originId": "Member_e93e24d1-2b65-4a6c-a1dd-654a12225487",
            "resource@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/catalogs('ede67938-cda7-4127-a9ca-7c7bf86a19b7')/resourceRoles('00000000-0000-0000-0000-000000000000')/resource/$entity",
            "resource": {
                "id": "ec09e90e-e021-4599-a8c3-bce77c2b2000",
                "displayName": "Marketing resources",
                "description": "Marketing group",
                "originId": "e93e24d1-2b65-4a6c-a1dd-654a12225487",
                "originSystem": "AadGroup",
                "createdDateTime": "2023-04-13T14:43:21.43Z",
                "attributes": []
            }
        }
    ]
}

Etapa 1.5: Criar o pacote de acesso

Agora você tem um catálogo com um recurso de grupo e deseja usar a função de recurso do membro do grupo no pacote de acesso. A próxima etapa é criar o pacote de acesso. Depois de ter o pacote de acesso, você pode adicionar a função de recurso a ele e criar uma política de como os usuários podem solicitar acesso a essa função de recurso. Você usa a ID do catálogo que você gravou anteriormente para criar o pacote de acesso. Registre a ID do pacote de acesso a ser usado posteriormente neste tutorial.

Solicitação

POST https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages
Content-type: application/json

{
  "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
  "displayName": "Marketing Campaign",
  "description": "Access to resources for the campaign"
}

Resposta

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/accessPackages/$entity",
    "id": "88203d16-0e31-41d4-87b2-dd402f1435e9",
    "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
    "displayName": "Marketing Campaign",
    "description": "Access to resources for the campaign",
    "isHidden": false,
    "isRoleScopesVisible": false,
    "createdBy": "admin@contoso.com",
    "createdDateTime": "2024-03-26T17:36:45.411033Z",
    "modifiedBy": "admin@contoso.com",
    "modifiedDateTime": "2024-03-26T17:36:45.411033Z"
}

Etapa 1.6: Adicionar uma função de recurso ao pacote de acesso

Solicitação

POST https://graph.microsoft.com/v1.0/identityGovernance/entitlementManagement/accessPackages/88203d16-0e31-41d4-87b2-dd402f1435e9/accessPackageResourceRoleScopes
Content-type: application/json

{
  "role": {
    "originId":"Member_f4892fac-e81c-4712-bdf2-a4450008a4b0",
    "displayName":"Member",
    "originSystem":"AadGroup",
    "resource": {
      "id":"4a1e21c5-8a76-4578-acb1-641160e076e8",
      "resourceType":"Security Group",
      "originId":"f4892fac-e81c-4712-bdf2-a4450008a4b0",
      "originSystem":"AadGroup"
    }
  },
  "scope": {
    "originId":"f4892fac-e81c-4712-bdf2-a4450008a4b0",
    "originSystem":"AadGroup"
  }
}

Resposta

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/entitlementManagement/accessPackages('88203d16-0e31-41d4-87b2-dd402f1435e9')/accessPackageResourceRoleScopes/$entity",
  "id": "e081321b-2802-4834-a6ca-6f598ce3cdf7_6dbd2209-9d14-4c76-b92b-fcb00e835fe1",
  "createdDateTime": "2024-03-26T19:56:00.6320729Z",
}

O pacote de acesso agora tem uma função de recurso, que é a associação de grupo. A função é atribuída a qualquer usuário que tenha o pacote de acesso.

Etapa 1.7: Criar uma política de pacote de acesso

Agora que você criou o pacote de acesso e adicionou recursos e funções, você pode decidir quem pode acessá-lo criando uma política de pacote de acesso. Neste tutorial, você habilita a conta Requestor1 que você criou para solicitar acesso aos recursos no pacote de acesso. Para esta tarefa, você precisa desses valores:

  • id do pacote de acesso para o valor da propriedade accessPackageId
  • id da conta de usuário Requestor1 para o valor da propriedade id em allowedRequestors

O valor da propriedade durationInDays permite que a conta Requestor1 acesse os recursos no pacote de acesso por até 30 dias. Registre o valor da propriedade ID que é retornada a ser usada posteriormente neste tutorial.

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies
Content-type: application/json

{
  "accessPackageId": "88203d16-0e31-41d4-87b2-dd402f1435e9",
  "displayName": "Specific users",
  "description": "Specific users can request assignment",
  "accessReviewSettings": null,
  "durationInDays": 30,
  "requestorSettings": {
    "scopeType": "SpecificDirectorySubjects",
    "acceptRequests": true,
    "allowedRequestors": [
       {
         "@odata.type": "#microsoft.graph.singleUser",
         "isBackup": false,
         "id": "007d1c7e-7fa8-4e33-b678-5e437acdcddc",
         "description": "Requestor1"
       }
    ]
  },
  "requestApprovalSettings": {
    "isApprovalRequired": false,
    "isApprovalRequiredForExtension": false,
    "isRequestorJustificationRequired": false,
    "approvalMode": "NoApproval",
    "approvalStages": []
  }
}

Resposta

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentPolicies/$entity",
  "id": "db440482-1210-4a60-9b55-3ac7a72f63ba",
  "accessPackageId": "88203d16-0e31-41d4-87b2-dd402f1435e9",
  "displayName": "Specific users",
  "description": "Specific users can request assignment",
  "canExtend": false,
  "durationInDays": 30,
  "expirationDateTime": null,
  "createdBy": "admin@contoso.com",
  "createdDateTime": "2020-06-29T19:47:44.7399675Z",
  "modifiedBy": "admin@contoso.com",
  "modifiedDateTime": "2020-06-29T19:47:44.7555489Z",
  "accessReviewSettings": null,
  "requestorSettings": {
    "scopeType": "SpecificDirectorySubjects",
    "acceptRequests": true,
    "allowedRequestors": [
      {
        "@odata.type": "#microsoft.graph.singleUser",
        "isBackup": false,
        "id": "007d1c7e-7fa8-4e33-b678-5e437acdcddc",
        "description": "Requestor1"
      }
    ]
  },
  "requestApprovalSettings": {
    "isApprovalRequired": false,
    "isApprovalRequiredForExtension": false,
    "isRequestorJustificationRequired": false,
    "approvalMode": "NoApproval",
    "approvalStages": []
  }
}

Etapa 2: Solicitar acesso

Nesta etapa, a conta de usuário Requestor1 solicita acesso aos recursos no pacote de acesso.

Para solicitar acesso aos recursos no pacote de acesso, você precisa fornecer esses valores:

  • id da conta de usuário Requestor1 que você criou para o valor da propriedade targetId
  • id da política de atribuição para o valor da propriedade assignmentPolicyId
  • id do pacote de acesso para o valor da propriedade accessPackageId

Na resposta, o status é Accepted e um estado é Submitted. Registre o valor da propriedade ID retornada para obter o status da solicitação posteriormente.

Inicie uma nova sessão anônima do navegador e entre no Requestor1. 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 Requestor1

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests
Content-type: application/json

{
  "requestType": "UserAdd",
  "accessPackageAssignment":{
     "targetId":"007d1c7e-7fa8-4e33-b678-5e437acdcddc",
     "assignmentPolicyId":"db440482-1210-4a60-9b55-3ac7a72f63ba",
     "accessPackageId":"88203d16-0e31-41d4-87b2-dd402f1435e9"
  }
}

Resposta

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentRequests/$entity",
    "createdDateTime": null,
    "completedDate": null,
    "id": "a6bb6942-3ae1-4259-9908-0133aaee9377",
    "requestType": "UserAdd",
    "requestState": "Submitted",
    "requestStatus": "Accepted",
    "isValidationOnly": false,
    "expirationDateTime": null,
    "justification": null
}

Agora você pode sair e sair da sessão anônima.

Etapa 3: Validar se o acesso foi atribuído

Nesta etapa, você confirma que a conta de usuário Requestor1 recebeu o pacote de acesso e que agora é membro do grupo de recursos de Marketing . Retorne à sessão de administrador no Graph Explorer.

Etapa 3.1: Obter o status da solicitação

Use o valor da propriedade ID da solicitação para obter o status atual dela. Na resposta, você pode ver o status alterado para Fulfilled e o estado alterado para Entregue.

Solicitação

GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests/a6bb6942-3ae1-4259-9908-0133aaee9377

Resposta

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentRequests/$entity",
  "createdDateTime": "2020-06-29T20:24:24.683Z",
  "completedDate": "2020-06-29T20:24:47.937Z",
  "id": "a6bb6942-3ae1-4259-9908-0133aaee9377",
  "requestType": "UserAdd",
  "requestState": "Delivered",
  "requestStatus": "FulfilledNotificationTriggered",
  "isValidationOnly": false,
  "expirationDateTime": null,
  "justification": null
}

Etapa 3.2: Obter atribuições de pacote de acesso

Você também pode usar a ID da política de pacote de acesso que você criou para ver que os recursos foram atribuídos à conta de usuário Requestor1 .

Solicitação

GET https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignments?$filter=accessPackageAssignmentPolicy/Id eq 'db440482-1210-4a60-9b55-3ac7a72f63ba'&$expand=target,accessPackageAssignmentResourceRoles

Resposta

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignments",
  "value": [
    {
      "id": "a6bb6942-3ae1-4259-9908-0133aaee9377",
      "catalogId": "cec5d6ab-c75d-47c0-9c1c-92e89f66e384",
      "accessPackageId": "88203d16-0e31-41d4-87b2-dd402f1435e9",
      "assignmentPolicyId": "db440482-1210-4a60-9b55-3ac7a72f63ba",
      "targetId": "2bc42425-6dc5-4f2a-9ebb-7a7464481eb0",
      "assignmentStatus": "Delivered",
      "assignmentState": "Delivered",
      "isExtended": false,
      "expiredDateTime": null,
      "target": {
         "id": "8586ddc8-0ff7-4c24-9c79-f192bc3566e3",
         "objectId": "2bc42425-6dc5-4f2a-9ebb-7a7464481eb0"
      },
      "accessPackageAssignmentResourceRoles": [
         {
            "id": "bdb7e0a0-a927-42ab-bf30-c5b5533dc54a",
            "originSystem": "AadGroup",
            "status": "Fulfilled"
         }
      ]
    }
  ]
}

Etapa 3.3: Obter os membros do grupo

Depois que a solicitação tiver sido concedida, você poderá usar a ID que você gravou para o grupo de recursos de Marketing para ver se a conta de usuário Requestor1 foi adicionada a ela.

Solicitação

GET https://graph.microsoft.com/v1.0/groups/f4892fac-e81c-4712-bdf2-a4450008a4b0/members

Resposta:

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
  "value": [
    {
      "@odata.type": "#microsoft.graph.user",
      "id": "007d1c7e-7fa8-4e33-b678-5e437acdcddc",
      "deletedDateTime": null,
      "accountEnabled": true,
      "ageGroup": null,
      "businessPhones": [],
      "city": null,
      "createdDateTime": "2020-06-23T18:43:24Z",
      "creationType": null,
      "companyName": null,
      "consentProvidedForMinor": null,
      "country": null,
      "department": null,
      "displayName": "Requestor1",
      "employeeId": null,
      "faxNumber": null,
      "givenName": null,
      "imAddresses": [],
      "infoCatalogs": [],
      "isResourceAccount": null,
      "jobTitle": null,
      "legalAgeGroupClassification": null,
      "mail": null,
      "mailNickname": "Requestor1"
    }
  ]
}

Etapa 4: Limpar recursos

Nesta etapa, você remove as alterações feitas e exclui o pacote de acesso da Campanha de Marketing .

Remover uma atribuição de pacote de acesso

Você deve remover todas as atribuições para o pacote de acesso antes de poder excluí-la. Use a ID da solicitação de atribuição que você gravou anteriormente para excluí-la.

Solicitação

POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests
Content-type: application/json

{
  "requestType": "AdminRemove",
  "accessPackageAssignment":{
     "id": "a6bb6942-3ae1-4259-9908-0133aaee9377"
  }
}

Resposta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#accessPackageAssignmentRequests/$entity",
    "createdDateTime": null,
    "completedDate": null,
    "id": "78eaee8c-e6cf-48c9-8f99-aae44c35e379",
    "requestType": "AdminRemove",
    "requestState": "Submitted",
    "requestStatus": "Accepted",
    "isValidationOnly": false,
    "expirationDateTime": null,
    "justification": null
}

Excluir a política de atribuição de pacote de acesso

Use a ID da política de atribuição que você gravou anteriormente para excluí-la. Verifique se todas as atribuições são removidas primeiro. A solicitação retorna o código de resposta 204 No Content.

DELETE https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentPolicies/6c1f65ec-8c25-4a45-83c2-a1de2a6d0e9f

Excluir o pacote de acesso

Use a ID do pacote de acesso que você gravou anteriormente para excluí-la. A solicitação retorna o código de resposta 204 No Content.

Solicitação

DELETE https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackages/cf54c6ca-d717-49bc-babe-d140d035dfdd

Conclusão

Neste tutorial, os recursos da campanha de marketing eram membros em um único grupo, que poderia ter acesso a outros recursos. Os recursos também podem ser uma coleção de grupos, aplicativos ou sites do SharePoint Online.

Os recursos neste tutorial têm suporte em licenças de Microsoft Entra ID P2 ou Microsoft Entra ID Governance. No entanto, outros recursos avançados de gerenciamento de direitos exigem licenciamento adicional. Para obter mais informações, consulte Microsoft Entra ID Governance conceitos básicos de licenciamento.