Compartilhar via

Usar o Azure PIM para gerenciar o acesso ativo com a API REST

  • Artigo

O Azure Privileged Identity Management (PIM) permite limitar o acesso de administrador permanente a funções privilegiadas, descobrir quem tem acesso e examinar o acesso privilegiado. Este artigo descreve as maneiras comuns de gerenciar o acesso usando a API REST.

Listar atribuições ativas

Para listar atribuições de função ativas (acesso à lista), você pode usar uma das Instâncias de Agendamento de Atribuição de Função – Listar para Agendamentos de Atribuição de Função ou Escopo– Listar para APIs REST de Escopo. Para refinar seus resultados, especifique um escopo e um filtro opcional. Para chamar essa API, é necessário ter acesso à operação Microsoft.Authorization/roleAssignments/read no escopo especificado. Todas as funções internas recebem acesso a essa operação.

Importante

A diferença entre agendas e instâncias de agendamento é que, embora as instâncias de agendamento incluam apenas atribuições que estão ativas no momento atual, os agendamentos também incluem atribuições que se tornarão ativas no futuro.

  1. Comece com a solicitação a seguir:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?api-version=2020-10-01&$filter={filter}

  2. Dentro do URI, substitua {scope} pelo escopo para o qual você deseja listar as funções de atribuição.

    Escopo Type
    providers/Microsoft.Management/managementGroups/{mg-name} Grupo de gerenciamento
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Recurso

  3. Substitua {filter} pela condição que você deseja aplicar a fim de filtrar a lista de atribuições de função.

    Filtrar Descrição
    $filter=atScope() Liste atribuições de função para apenas o escopo especificado, não incluindo as atribuições de função em subescopos.
    $filter=principalId%20eq%20'{objectId}' Liste atribuições de função para um usuário, grupo ou entidade de serviço específica.
    $filter=roleDefinitionId%20eq%20'{roleDefinitionId}' Listar atribuições de função para uma definição de função especificada.
    $filter=assignedTo('{objectId}') Liste atribuições de função para um usuário específico, incluindo aqueles herdados de grupos.
    $filter=asTarget() Listar atribuições de função para o usuário ou entidade de serviço atual, incluindo as herdadas de grupos.
    $filter=assignedTo('{objectId}')+and+atScope() Listar atribuições de função para um usuário especificado, incluindo as herdadas de grupos apenas para o escopo especificado, sem incluir as atribuições de função em subescopos.

Conceder atribuição ativa

Para criar uma atribuição de função ativa (conceder acesso), use a API REST Solicitações de Agendamento de Atribuição de Função – Criar e especifique a entidade de segurança, a definição de função, o agendamento, o requestType = AdminAssign e o escopo. Para chamar essa API, você deve ter acesso à Microsoft.Authorization/roleAssignments/write operação. Das funções internas, somente Proprietário e Administrador do Acesso do Usuário recebem permissão para acessar essa operação.

  1. Use a API REST Definições de Função - Listar ou veja as Funções internas para obter o identificador da definição de função que você deseja atribuir.

  2. Use uma ferramenta GUID para gerar um identificador exclusivo que será usado para atribuição de função personalizada. O identificador tem o formato: 00000000-0000-0000-0000-000000000000

  3. Comece com a solicitação e corpo a seguir:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

    {
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminAssign",
    "ScheduleInfo": {
      "StartDateTime": "2020-09-09T21:31:27.91Z",
      "Expiration": {
        "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
        "EndDateTime": null,
        "Duration": "P30D" // Use ISO 8601 format
      }
    }
  }
}

  4. Dentro do URI, substitua {scope} pelo escopo da atribuição de função.

    Escopo Type
    providers/Microsoft.Management/managementGroups/{mg-name} Grupo de gerenciamento
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1 Recurso

  5. Substitua {roleAssignmentScheduleRequestName} pelo identificador GUID da atribuição de função.

  6. No corpo da solicitação, substitua {subscriptionId} pelo identificador da sua assinatura.

  7. Substitua {roleDefinitionId} pelo identificador de definição da função.

  8. Substitua {principalId} com o identificador de objeto do usuário, grupo ou entidade de serviço que receberá a função.

Remover atribuição ativa

Para remover uma atribuição de função ativa (remover o acesso), use a API REST Solicitações de Agendamento de Atribuição de Função – Criar para criar uma nova solicitação para revogar a atribuição e especificar a entidade de segurança, a definição de função, requestType = AdminRemove e o escopo. Para chamar essa API, é necessário ter acesso à operação Microsoft.Authorization/roleAssignments/write. Das funções internas, somente Proprietário e Administrador do Acesso do Usuário recebem permissão para acessar essa operação.

  1. Use uma ferramenta GUID para gerar um identificador exclusivo que será usado para atribuição de função personalizada. O identificador tem o formato: 00000000-0000-0000-0000-000000000000

  2. Comece com a solicitação a seguir:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

    {
  "Properties": {
    "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "PrincipalId": "{principalId}",
    "RequestType": "AdminRemove"
    }
}

  3. Dentro do URI, substitua {scope} pelo escopo para remoção da atribuição de função.

    Escopo Type
    providers/Microsoft.Management/managementGroups/{mg-name} Grupo de gerenciamento
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Recurso

  4. Substitua {roleAssignmentScheduleRequestName} pelo identificador GUID da atribuição de função.

Ativar uma atribuição de função qualificada

Para ativar uma atribuição de função qualificada (obter acesso ativado), use a API REST Solicitações de Agendamento de Atribuição de Função – Criar para criar uma nova solicitação e especificar a entidade de segurança, a definição de função, requestType = SelfActivate e o escopo. Para chamar essa API, é necessário ter uma atribuição de função qualificada no escopo.

  1. Use uma ferramenta GUID para gerar um identificador exclusivo que será usado para atribuição de função personalizada. O identificador tem o formato: 00000000-0000-0000-0000-000000000000

  2. [Opcional] Escolha um RoleEligibilitySchedule que você deseja ativar e obtenha o RoleEligibilityScheduleId da API de Agendamentos de Qualificação de Função para passar como o LinkedRoleEligibilityScheduleId. Isso é opcional e, se não for passado, o sistema escolherá um RoleEligibilitySchedule.

  3. Comece com a solicitação a seguir:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

     {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfActivate",
     "ScheduleInfo": {
       "StartDateTime": "2020-09-09T21:31:27.91Z",
       "Expiration": {
         "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
         "EndDateTime": null,
         "Duration": "PT8H" // Use ISO 8601 format
       }
     },
     "LinkedRoleEligibilityScheduleId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignmentSchedules/{roleAssignmentScheduleId}" //Optional
   }
 }

  4. Dentro do URI, substitua {scope} pelo escopo para remoção da atribuição de função.

    Escopo Type
    providers/Microsoft.Management/managementGroups/{mg-name} Grupo de gerenciamento
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Recurso

  5. Substitua {roleAssignmentScheduleRequestName} pelo identificador GUID da atribuição de função.

Desativar uma atribuição de função ativa

Para desativar uma atribuição de função ativada (remover acesso ativado), use as Solicitações de Agendamento de Atribuição de Função – Criar API REST para criar uma nova solicitação e especificar a entidade de segurança, a definição de função, requestType = SelfDeactivate e o escopo. Para chamar essa API, você deve ter uma atribuição de função ativada no escopo.

  1. Use uma ferramenta GUID para gerar um identificador exclusivo que será usado para atribuição de função personalizada. O identificador tem o formato: 00000000-0000-0000-0000-000000000000

  2. Comece com a solicitação a seguir:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

     {
   "Properties": {
     "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
     "PrincipalId": "{principalId}",
     "RequestType": "SelfDeactivate"        
   }
 }

  3. Dentro do URI, substitua {scope} pelo escopo para remoção da atribuição de função.

    Escopo Type
    providers/Microsoft.Management/managementGroups/{mg-name} Grupo de gerenciamento
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Recurso

  4. Substitua {roleAssignmentScheduleRequestName} pelo identificador GUID da atribuição de função.

JEA (Just-Enough-Access)

Se um usuário tiver uma atribuição de função qualificada em um recurso (pai), ele poderá optar por ativar a função em um escopo de nível filho do recurso pai em vez de todo o escopo pai. Por exemplo, se um usuário tiver Contributor uma função qualificada em uma assinatura, ele poderá ativar a função em um nível de grupo de recursos filho da assinatura.

Para obter uma lista de todos os filhos de um recurso no qual você tem acesso qualificado, você pode usar a API de Recursos Filho Qualificados .

  1. Comece com a solicitação a seguir:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}

  2. Dentro do URI, substitua {scope} pelo escopo para o qual você deseja listar as funções de atribuição.

    Escopo Type
    providers/Microsoft.Management/managementGroups/{mg-name} Grupo de gerenciamento
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group

  3. Substitua {filter} pela condição que você deseja aplicar a fim de filtrar a lista de atribuições de função.

    Filtrar Descrição
    $filter=resourceType+eq+'Subscription' Listar recursos do tipo = 'Assinatura'.
    $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup'' Listar recursos do tipo = 'Assinatura' ou tipo = 'ResourceGroup'.

  4. Usar o id de qualquer recurso filho para usar como o scope para a ativação RoleAssignmentScheduleRequest

Erros comuns retornados para uma nova solicitação

Veja a seguir uma lista de erros comuns que você pode encontrar ao criar uma nova solicitação e como atenuá-los.

Mensagem de erro Explanantion Atenuação
code: RoleAssignmentExists
message: a atribuição de função já existe.		 Uma atribuição de função semelhante já existe Você pode GET essa atribuição de função e verificar sua agenda.
code: RoleAssignmentRequestPolicyValidationFailed
message: as seguintes regras de política falharam: ["ExpirationRule"]		 O ScheduleInfo especificado na solicitação excede a duração máxima permitida Você pode GET o RoleManagementPolicy para isso RoleDefinitionId e marcar oRoleManagementPolicyExpirationRule
code: RoleAssignmentRequestPolicyValidationFailed
message: as seguintes regras de política falharam: ["JustificationRule"]		 Você precisa especificar um Justification no corpo da solicitação Você pode GET o RoleManagementPolicy para isso RoleDefinitionId e marcar oRoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: as seguintes regras de política falharam: ["EligibilityRule"]		 Um válido RoleEligibilityScheduleInstance não existe para ativar essa função Um administrador de recursos precisa criar um RoleEligibilityScheduleRequest para essa entidade de segurança
code: RoleAssignmentRequestPolicyValidationFailed
message: as seguintes regras de política falharam: ["TicketingRule"]		 Você precisa especificar um TicketInfo no corpo da solicitação Você pode GET o RoleManagementPolicy para isso RoleDefinitionId e marcar oRoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed
message: as seguintes regras de política falharam: ["MfaRule"]		 Você precisa concluir a Autenticação Multifator do Azure para enviar essa solicitação Você pode GET o RoleManagementPolicy para isso RoleDefinitionId e marcar oRoleManagementPolicyEnablementRule