Criar roleEligibilityScheduleRequest

Namespace: microsoft.graph

No PIM, solicite uma qualificação de função para uma entidade de segurança por meio do objeto unifiedRoleEligibilityScheduleRequest . Essa operação permite que administradores e usuários qualificados adicionem, revoguem ou estendam atribuições qualificadas.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global Governo dos EUA L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) RoleEligibilitySchedule.ReadWrite.Directory RoleManagement.ReadWrite.Directory
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application RoleEligibilitySchedule.ReadWrite.Directory RoleManagement.ReadWrite.Directory

Importante

Para acesso delegado usando contas corporativas ou de estudante, o usuário conectado deve receber uma função do Microsoft Entra com suporte ou uma função personalizada que conceda as permissões necessárias para esta operação. Esta operação dá suporte às seguintes funções internas, que fornecem apenas o menor privilégio necessário:

  • Para operações de leitura: Leitor Global, Operador de Segurança, Leitor de Segurança, Administrador de Segurança ou Administrador de Função Privilegiada
  • Para operações de gravação: Administrador de Função Privilegiada

Solicitação HTTP

POST /roleManagement/directory/roleEligibilityScheduleRequests

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON do objeto unifiedRoleEligibilityScheduleRequest .

Você pode especificar as propriedades a seguir ao criar um unifiedRoleEligibilityScheduleRequest.

Propriedade Tipo Descrição
ação unifiedRoleScheduleRequestActions Representa o tipo de operação na solicitação de qualificação de função. Os valores possíveis são: adminAssign, adminUpdate, adminRemove, selfActivateadminExtendadminRenewselfDeactivate, selfExtend, . unknownFutureValueselfRenew
  • adminAssign: para que os administradores atribuam funções qualificadas às entidades de segurança.
  • adminRemove: para que os administradores removam funções qualificadas das entidades de segurança.
  • adminUpdate: para que os administradores alterem as qualificações de função existentes.
  • adminExtend: para que os administradores estendam as qualificações de função que expiram.
  • adminRenew: para que os administradores renovem as qualificações expiradas.
  • selfActivate: para que os usuários ativem suas atribuições.
  • selfDeactivate: Para que os usuários desativem suas atribuições ativas.
  • selfExtend: para que os usuários solicitem a extensão de suas atribuições que estão expirando.
  • SelfRenew: para que os usuários solicitem a renovação de suas atribuições expiradas.
appScopeId Cadeia de caracteres Identificador do escopo específico do aplicativo quando a elegibilidade da função tem como escopo um aplicativo. O escopo da qualificação de uma função determina o conjunto de recursos para os quais a entidade de segurança está qualificada para acessar. Escopos de aplicativo são escopos definidos e compreendidos somente por este aplicativo. Use / para escopos de aplicativo em todo o locatário. Use directoryScopeId para limitar o escopo a objetos de diretório específicos, por exemplo, unidades administrativas. É necessário directoryScopeId ou appScopeId .
directoryScopeId Cadeia de caracteres Identificador do objeto de diretório que representa o escopo da qualificação da função. O escopo de uma qualificação de função determina o conjunto de recursos para os quais a entidade de segurança recebeu acesso. Escopos de diretório são escopos compartilhados armazenados no diretório que são compreendidos por vários aplicativos. Use / para escopo de todo o locatário. Use appScopeId para limitar o escopo a apenas um aplicativo. É necessário directoryScopeId ou appScopeId .
isValidationOnly Booliano Determina se a chamada é uma validação ou uma chamada real. Defina essa propriedade apenas se quiser marcar se uma ativação está sujeita a regras adicionais, como MFA, antes de realmente enviar a solicitação. Opcional.
Justificação Cadeia de caracteres Uma mensagem fornecida por usuários e administradores ao criar, eles criam o objeto unifiedRoleEligibilityScheduleRequest .

Ações opcionais para selfDeactivate eadminRemove; podem ser opcionais ou necessárias para outros tipos de ação, dependendo das regras na política vinculada à função do Microsoft Entra. Para obter mais informações, consulte Regras no PIM.
principalId Cadeia de caracteres Identificador da entidade de segurança que recebeu a qualificação da função. Obrigatório.
roleDefinitionId Cadeia de caracteres Identificador do objeto unifiedRoleDefinition que está sendo atribuído à entidade de segurança. Obrigatório.
Informações de agendamento requestSchedule O período de elegibilidade da função. Opcional quando a ação é adminRemove. O período de elegibilidade depende das configurações da função do Microsoft Entra.
ticketInfo ticketInfo Detalhes do ticket vinculados à solicitação de qualificação da função, incluindo detalhes do número do ticket e do sistema do ticket.

Ações opcionais para selfDeactivate eadminRemove; podem ser opcionais ou necessárias para outros tipos de ação, dependendo das regras na política vinculada à função do Microsoft Entra. Para obter mais informações, consulte Regras no PIM.

Resposta

Se for bem-sucedido, esse método retornará um código de 201 Created resposta e um objeto unifiedRoleEligibilityScheduleRequest no corpo da resposta.

Exemplos

Exemplo 1: Administração para atribuir uma solicitação de agendamento de qualificação de função

Solicitação

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilityScheduleRequests
Content-Type: application/json

{
    "action": "adminAssign",
    "justification": "Assign Attribute Assignment Admin eligibility to restricted user",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "scheduleInfo": {
        "startDateTime": "2022-04-10T00:00:00Z",
        "expiration": {
            "type": "afterDateTime",
            "endDateTime": "2024-04-10T00:00:00Z"
        }
    }
}

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#roleManagement/directory/roleEligibilityScheduleRequests/$entity",
    "id": "50877283-9d40-433c-bab8-7986dc10458a",
    "status": "Provisioned",
    "createdDateTime": "2022-04-12T09:05:39.7594064Z",
    "completedDateTime": "2022-04-12T09:05:41.8532931Z",
    "approvalId": null,
    "customData": null,
    "action": "adminAssign",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": "50877283-9d40-433c-bab8-7986dc10458a",
    "justification": "Assign Attribute Assignment Admin eligibility to restricted user",
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5"
        }
    },
    "scheduleInfo": {
        "startDateTime": "2022-04-12T09:05:41.8532931Z",
        "recurrence": null,
        "expiration": {
            "type": "afterDateTime",
            "endDateTime": "2024-04-10T00:00:00Z",
            "duration": null
        }
    },
    "ticketInfo": {
        "ticketNumber": null,
        "ticketSystem": null
    }
}

Exemplo 2: Administração para remover uma solicitação de agendamento de qualificação de função existente

Na solicitação a seguir, o administrador cria uma solicitação para revogar a qualificação de uma entidade de segurança com ID 071cc716-8147-4397-a5ba-b2105951cc0b para uma função com ID 8424c6f0-a189-499e-bbd0-26c1753c96d4.

Solicitação

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleEligibilityScheduleRequests
Content-Type: application/json

{
    "action": "adminRemove",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b"
}

Resposta

O exemplo a seguir mostra a resposta. O objeto de resposta mostra que a qualificação de uma função anterior para uma entidade de segurança é Revoked. A entidade de segurança não verá mais sua função qualificada anteriormente.

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#roleManagement/directory/roleEligibilityScheduleRequests/$entity",
    "id": "f341269e-c926-41fa-a905-cef3b01b2a67",
    "status": "Revoked",
    "createdDateTime": "2022-04-12T09:12:15.6859992Z",
    "completedDateTime": null,
    "approvalId": null,
    "customData": null,
    "action": "adminRemove",
    "principalId": "071cc716-8147-4397-a5ba-b2105951cc0b",
    "roleDefinitionId": "8424c6f0-a189-499e-bbd0-26c1753c96d4",
    "directoryScopeId": "/",
    "appScopeId": null,
    "isValidationOnly": false,
    "targetScheduleId": null,
    "justification": null,
    "scheduleInfo": null,
    "createdBy": {
        "application": null,
        "device": null,
        "user": {
            "displayName": null,
            "id": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5"
        }
    },
    "ticketInfo": {
        "ticketNumber": null,
        "ticketSystem": null
    }
}