Compartilhar via


Criar governanceRoleAssignmentRequest

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Cuidado

Esta versão do Privileged Identity Management (PIM) API para recursos Azure será depreciada em breve. Use a nova API DE PIM REST do Azure para funções de recurso do Azure.

Crie um pedido de atribuição de função para representar a operação que pretende numa atribuição de função. A tabela seguinte lista as operações.

Operação Tipo
Atribuir uma atribuição de função AdminAdd
Ativar uma atribuição de função elegível UserAdd
Desativar uma atribuição de função ativada UserRemove
Remover uma atribuição de função AdminRemove
Atualizar uma atribuição de função AdminUpdate
Pedido para prolongar a minha atribuição de função UserExtend
Expandir uma atribuição de função AdminExtend
Pedido para renovar a minha atribuição de função expirada UserRenew
Renovar uma atribuição de função expirada AdminRenew

Esta API está disponível nas seguintes implementações de cloud nacionais.

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

Permissões

A tabela seguinte mostra as permissões ou permissões com menos privilégios necessárias para chamar esta API em cada tipo de recurso suportado. Siga as melhores práticas para pedir permissões com menos privilégios. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Recurso com suporte Delegada (conta corporativa ou de estudante) Delegada (conta pessoal da Microsoft) Application
Microsoft Entra ID PrivilegedAccess.ReadWrite.AzureAD Sem suporte. Sem suporte.
Recursos do Azure PrivilegedAccess.ReadWrite.AzureResources Sem suporte. Sem suporte.
group PrivilegedAccess.ReadWrite.AzureADGroup Sem suporte. Sem suporte.

Solicitação HTTP

POST /privilegedAccess/azureResources/roleAssignmentRequests

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

Corpo da solicitação

No corpo do pedido, forneça uma representação JSON de um objeto governanceRoleAssignmentRequest .

Propriedade Tipo Descrição
resourceId Cadeia de caracteres O identificador exclusivo do recurso do Azure que está associado ao pedido de atribuição de função. Os recursos do Azure podem incluir subscrições, grupos de recursos, máquinas virtuais e bases de dados SQL. Obrigatório.
roleDefinitionId Cadeia de caracteres O identificador da definição de função do Azure à qual o pedido de atribuição de função está associado. Obrigatório.
subjectId Cadeia de caracteres O identificador exclusivo do principal ou assunto ao qual o pedido de atribuição de função está associado. Os principais podem ser utilizadores, grupos ou principais de serviço. Obrigatório.
assignmentState Cadeia de caracteres O estado da atribuição. O valor pode ser Eligible e Active. Obrigatório.
type Cadeia de caracteres O tipo de pedido. O valor pode ser AdminAdd, UserAdd, AdminUpdate, AdminRemove, UserRemove, , UserExtende AdminRenewUserRenewAdminExtend. Obrigatório.
motivo Cadeia de caracteres O motivo tem de ser fornecido para o pedido de atribuição de função para fins de auditoria e revisão.
Cronograma governanceSchedule A agenda do pedido de atribuição de função. Para o tipo de pedido de UserAdd, AdminAdd, AdminUpdatee AdminExtend, é necessário.

Resposta

Se for bem-sucedido, este método devolve um 201 Created código de resposta e um objeto governanceRoleAssignmentRequest no corpo da resposta.

Códigos de erro

Esta API devolve os códigos de erro HTTP padrão. Além disso, também devolve os códigos de erro listados na tabela seguinte.

Código de erro Mensagem de erro Detalhes
400 BadRequest RoleNotFound Não roleDefinitionId é possível localizar o fornecido no corpo do pedido.
400 BadRequest ResourceIsLocked O recurso fornecido no corpo do pedido está no estado de e não pode criar pedidos de atribuição de Locked função.
400 BadRequest SubjectNotFound Não subjectId é possível localizar o fornecido no corpo do pedido.
400 BadRequest PendingRoleAssignmentRequest Já existe uma governação pendenteRoleAssignmentRequest no sistema.
400 BadRequest RoleAssignmentExists A governaçãoRoleAssignment pedida para ser criada já existe no sistema.
400 BadRequest RoleAssignmentDoesNotExist A governaçãoRoleAssignment pedida para ser atualizada/expandida não existe no sistema.
400 BadRequest RoleAssignmentRequestPolicyValidationFailed O governanceRoleAssignmentRequest não cumpre as políticas internas e não pode ser criado.

Exemplos

Os exemplos seguintes mostram como utilizar esta API.

Exemplo 1: o administrador atribui um utilizador a uma função

Neste exemplo, um administrador atribui o utilizador nawu@contoso.com à função Leitor de Faturação.

Nota: Além da permissão, este exemplo requer que o requerente tenha, pelo menos, uma Active atribuição de função de administrador (owner ou user access administrator) no recurso.

Propriedade Tipo Obrigatório Valor
resourceId Cadeia de caracteres Sim <resourceId>
roleDefinitionId Cadeia de caracteres Sim <roleDefinitionId>
subjectId Cadeia de caracteres Sim <subjectId>
assignmentState Cadeia de caracteres Sim Elegível/Ativo
type Cadeia de caracteres Sim AdminAdd
motivo Cadeia de caracteres depende das Definições de função
Cronograma governanceSchedule Sim

Solicitação

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Eligible",
  "type": "AdminAdd",
  "reason": "Assign an eligible role",
  "schedule": {
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "type": "Once"
  }
}

Resposta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "1232e4ea-741a-4be5-8044-5edabdd61672",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminAdd",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate Only",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "duration": "PT0S"
  }
}

Exemplo 2: o utilizador ativa a função elegível

Neste exemplo, o utilizador nawu@contoso.com ativa a função leitor de faturação elegível.

Propriedade Tipo Obrigatório Valor
resourceId Cadeia de caracteres Sim <resourceId>
roleDefinitionId Cadeia de caracteres Sim <roleDefinitionId>
subjectId Cadeia de caracteres Sim <subjectId>
assignmentState Cadeia de caracteres Sim Ativo
type Cadeia de caracteres Sim UserAdd
motivo Cadeia de caracteres depende das Definições de função
Cronograma governanceSchedule Sim

Solicitação

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserAdd",
  "reason": "Activate the owner role",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "duration": "PT9H"
  },
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394"
}

Resposta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "3ad49a7c-918e-4d86-9f84-fab28f8658c0",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394",
  "type": "UserAdd",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Activate the owner role",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "EligibilityRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      },
      {
        "key": "JustificationRule",
        "value": "Grant"
      },
      {
        "key": "ActivationDayRule",
        "value": "Grant"
      },
      {
        "key": "ApprovalRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "endDateTime": "0001-01-01T00:00:00Z",
    "duration": "PT9H"
  }
}

Exemplo 3: o utilizador desativa uma função atribuída

Neste exemplo, o utilizador nawu@contoso.com desativa a função de Leitor de Faturação ativa.

Propriedade Tipo Obrigatório Valor
resourceId Cadeia de caracteres Sim <resourceId>
roleDefinitionId Cadeia de caracteres Sim <roleDefinitionId>
subjectId Cadeia de caracteres Sim <subjectId>
assignmentState Cadeia de caracteres Sim Ativo
type Cadeia de caracteres Sim UserRemove
motivo Cadeia de caracteres Não
Cronograma governanceSchedule Não

Solicitação

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserRemove",
  "reason": "Deactivate the role",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec"
}

Resposta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "abfcdb57-8e5d-42a0-ae67-7598b96fddb1",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec",
  "type": "UserRemove",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate only",
  "schedule": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  }
}

Exemplo 4: o administrador remove o utilizador de uma função

Neste exemplo, um administrador remove o utilizador nawu@contoso.com da função Leitor de Faturação.

Nota: Além da permissão, este exemplo requer que o requerente tenha, pelo menos, uma Active atribuição de função de administrador (owner ou user access administrator) no recurso.

Propriedade Tipo Obrigatório Valor
resourceId Cadeia de caracteres Sim <resourceId>
roleDefinitionId Cadeia de caracteres Sim <roleDefinitionId>
subjectId Cadeia de caracteres Sim <subjectId>
assignmentState Cadeia de caracteres Sim Elegível/Ativo
type Cadeia de caracteres Sim AdminRemove
motivo Cadeia de caracteres Não
Cronograma governanceSchedule Não

Solicitação

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminRemove"
}

Resposta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "c934fcb9-cf53-42ac-a8b4-6246f6726299",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminRemove",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  },
  "schedule": null
}

Exemplo 5: O administrador atualiza a atribuição de função

Neste exemplo, os administradores atualizam a atribuição de função do utilizador nawu@contoso.com para Proprietário.

Nota: Além da permissão, este exemplo requer que o requerente tenha, pelo menos, uma Active atribuição de função de administrador (owner ou user access administrator) no recurso.

Propriedade Tipo Obrigatório Valor
resourceId Cadeia de caracteres Sim <resourceId>
roleDefinitionId Cadeia de caracteres Sim <roleDefinitionId>
subjectId Cadeia de caracteres Sim <subjectId>
assignmentState Cadeia de caracteres Sim Elegível/Ativo
type Cadeia de caracteres Sim AdminUpdate
motivo Cadeia de caracteres depende de roleSettings
Cronograma governanceSchedule Sim

Solicitação

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "assignmentState": "Eligible",
  "type": "AdminUpdate",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31.000Z"
  }
}

Resposta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "4f6d4802-b3ac-4f5a-86d7-a6a4edd7d383",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminUpdate",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31Z",
    "duration": "PT0S"
  }
}

Exemplo 6: o administrador prolonga a atribuição de função prestes a expirar

Este exemplo expande a atribuição de função a expirar para o utilizador ANUJCUSER para Contribuidor do Serviço de Gestão de API.

Nota: Além da permissão, este exemplo requer que o requerente tenha, pelo menos, uma Active atribuição de função de administrador (owner ou user access administrator) no recurso.

Propriedade Tipo Obrigatório Valor
resourceId Cadeia de caracteres Sim <resourceId>
roleDefinitionId Cadeia de caracteres Sim <roleDefinitionId>
subjectId Cadeia de caracteres Sim <subjectId>
assignmentState Cadeia de caracteres Sim Elegível/Ativo
type Cadeia de caracteres Sim AdminExtend
motivo Cadeia de caracteres depende de roleSettings
Cronograma governanceSchedule Sim

Solicitação

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminExtend",
  "reason": "extend role assignment",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z"
  }
}

Resposta

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "486f0c05-47c8-4498-9c06-086a78c83004",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminExtend",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "extend role assignment",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z",
    "duration": "PT0S"
  }
}