Gerenciamento de funções do HSM Gerenciado

2025-04-30

Observação

O Key Vault é compatível com dois tipos de recurso: cofres e HSMs Gerenciados. Este artigo é sobre o HSM Gerenciado. Se você quiser saber como gerenciar um cofre, consulte Gerenciar o Key Vault usando a CLI do Azure.

Este artigo fornece instruções práticas para gerenciar funções e atribuições de função para um HSM gerenciado usando a CLI do Azure. Ele implementa o modelo de controle de acesso baseado em função descrito no controle de acesso para HSM gerenciado usando as funções internas documentadas em funções internas do RBAC local para HSM Gerenciado.

Para obter uma visão geral do HSM gerenciado, consulte o que é HSM gerenciado?. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Para permitir que uma entidade de segurança (como um usuário, uma entidade de serviço, um grupo ou uma identidade gerenciada) execute operações do plano de dados do HSM Gerenciado, é necessário atribuir a ela uma função que permita realizar essas operações. Por exemplo, se você quiser permitir que um aplicativo execute uma operação de assinatura usando uma chave, será necessário atribuir a ele uma função que contenha "Microsoft.KeyVault/managedHSM/keys/sign/action" como uma das ações de dados. Uma função pode ser atribuída em um escopo específico. O RBAC local do HSM Gerenciado é compatível com dois escopos: em todo o HSM (/ ou /keys) e por chave (/keys/<keyname>).

Para obter uma lista de todas as funções internas do HSM gerenciado e as operações que elas permitem, consulte as funções internas do HSM gerenciado.

Pré-requisitos

Para usar comandos da CLI do Azure neste artigo, você deve ter os seguintes itens:

Uma assinatura do Microsoft Azure. Se você não tiver um, poderá se inscrever para uma avaliação gratuita.
A CLI do Azure versão 2.25.0 ou posterior. Execute az --version para encontrar a versão. Se você precisar instalar ou atualizar, consulte Instalar a CLI do Azure.
Um HSM gerenciado na sua assinatura. Confira o Início Rápido: Provisionar e ativar um HSM gerenciado usando a CLI do Azure para provisionar e ativar um HSM gerenciado.

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que você pode usar por meio do navegador. Você pode usar o Bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. Você pode usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada em seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Link
Selecione Experimente no canto superior direito de um código ou bloco de comando. Selecionar Try It não copia automaticamente o código ou o comando para o Cloud Shell.
https://shell.azure.comAcesse ou selecione o botão Iniciar Cloud Shell para abrir o Cloud Shell no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito no portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.
Cole o código ou o comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e Linux ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou o comando.

Para entrar no Azure usando a CLI, você pode digitar:

az login

Para obter mais informações sobre as opções de entrada por meio da CLI, consulte entrar com a CLI do Azure

Criar uma atribuição de função

Atribuir funções para todas as chaves

Use o comando az keyvault role assignment create para atribuir a função Usuário de Cripto de HSM Gerenciado ao usuário identificado pelo nome principal user2@contoso.com para todas as chaves (escopo /keys) no ContosoHSM.

az keyvault role assignment create --hsm-name ContosoMHSM --role "Managed HSM Crypto User" --assignee user2@contoso.com  --scope /keys

Atribuir função para uma chave específica

Use o comando az keyvault role assignment create para atribuir uma função de Usuário de Criptografia de HSM Gerenciado ao usuário identificado pelo nome principal user2@contoso.com para uma chave específica chamada myrsakey.

az keyvault role assignment create --hsm-name ContosoMHSM --role "Managed HSM Crypto User" --assignee user2@contoso.com  --scope /keys/myrsakey

Listar as atribuições de função existentes

Use az keyvault role assignment list para listar as atribuições de função.

Todas as atribuições de função no escopo/(padrão, quando nenhum --scope estiver especificado) para todos os usuários (padrão, quando nenhum --assignee estiver especificado)

az keyvault role assignment list --hsm-name ContosoMHSM

Todas as atribuições de função no nível do HSM para um usuário específico user1@contoso.com .

az keyvault role assignment list --hsm-name ContosoMHSM --assignee user@contoso.com

Observação

Quando o escopo for / (ou /chaves), o comando listará apenas todas as atribuições de função no nível superior e não mostrará as atribuições de função no nível de chave individual.

Todas as atribuições de função para um usuário user2@contoso.com específico para uma chave específica myrsakey.

az keyvault role assignment list --hsm-name ContosoMHSM --assignee user2@contoso.com --scope /keys/myrsakey

Uma atribuição de função específica para a função Responsável pela criptografia do HSM gerenciado para um usuário específico user2@contoso.com para uma chave específica myrsakey

az keyvault role assignment list --hsm-name ContosoMHSM --assignee user2@contoso.com --scope /keys/myrsakey --role "Managed HSM Crypto Officer"

Excluir uma atribuição de função

Use o comando az keyvault role assignment delete para excluir a função de Oficial de Criptografia do HSM Gerenciado atribuída ao usuário user2@contoso.com para a chave myrsakey2.

az keyvault role assignment delete --hsm-name ContosoMHSM --role "Managed HSM Crypto Officer" --assignee user2@contoso.com  --scope /keys/myrsakey2

Liste todas as definições de função disponíveis

Use o comando az keyvault role definition list para listar todas as definições de função.

az keyvault role definition list --hsm-name ContosoMHSM

Criar uma definição de função

O HSM gerenciado tem várias funções internas (predefinidas) que são úteis para os cenários de uso mais comuns. Você pode definir sua função com uma lista de ações específicas que ela tem permissão para executar. Em seguida, você pode atribuir essa função a entidades de segurança para lhes conceder a permissão para as ações especificadas.

Use o comando az keyvault role definition create para uma função chamada Minha função personalizada usando uma cadeia de caracteres JSON.

az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{
    "roleName": "My Custom Role",
    "description": "The description of the custom rule.",
    "actions": [],
    "notActions": [],
    "dataActions": [
        "Microsoft.KeyVault/managedHsm/keys/read/action"
    ],
    "notDataActions": []
}'

Use o comando az keyvault role definition create para uma função de um arquivo chamado my-custom-role-definition.json contendo a cadeia de caracteres JSON para uma definição de função. Consulte o exemplo acima.

az keyvault role definition create --hsm-name ContosoMHSM --role-definition @my-custom-role-definition.json

Mostrar detalhes de uma definição de função

Use o comando az keyvault role definition show para ver detalhes de uma definição de função específica usando o nome (um GUID).

az keyvault role definition show --hsm-name ContosoMHSM --name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Atualizar uma definição de função personalizada

Use az keyvault role definition update o comando para atualizar uma função chamada Minha Função Personalizada usando uma cadeia de caracteres JSON.

az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{
            "roleName": "My Custom Role",
            "name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "id": "Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-
        xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "description": "The description of the custom rule.",
            "actions": [],
            "notActions": [],
            "dataActions": [
                "Microsoft.KeyVault/managedHsm/keys/read/action",
                "Microsoft.KeyVault/managedHsm/keys/write/action",
                "Microsoft.KeyVault/managedHsm/keys/backup/action",
                "Microsoft.KeyVault/managedHsm/keys/create"
            ],
            "notDataActions": []
        }'

Excluir definição de função personalizada

Use o comando az keyvault role definition delete da CLI do Azure para excluir uma definição de função personalizada usando o nome (um GUID).

az keyvault role definition delete --hsm-name ContosoMHSM --name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Observação

Funções integradas não podem ser excluídas. Quando funções personalizadas são excluídas, todas as atribuições de função que usam essa função personalizada são desabilitadas.

Próximas etapas

Confira uma visão geral do RBAC (controle de acesso baseado em função) do Azure.
Saiba mais sobre o modelo de controle de acesso do HSM gerenciado
Veja todas as funções integradas para RBAC local do HSM gerenciado

Compartilhar via

Gerenciamento de funções do HSM Gerenciado

Pré-requisitos

Azure Cloud Shell

Entrar no Azure

Criar uma atribuição de função

Atribuir funções para todas as chaves

Atribuir função para uma chave específica

Listar as atribuições de função existentes

Excluir uma atribuição de função

Liste todas as definições de função disponíveis

Criar uma definição de função

Mostrar detalhes de uma definição de função

Atualizar uma definição de função personalizada

Excluir definição de função personalizada

Próximas etapas

Comentários

Recursos adicionais