Managed HSM role management

Note

Key Vault supports two types of resource: vaults and managed HSMs. This article is about Managed HSM. If you want to learn how to manage a vault, please see Manage Key Vault using the Azure CLI.

For an overview of Managed HSM, see What is Managed HSM?. If you don't have an Azure subscription, create a free account before you begin.

This article shows you how to manage roles for a Managed HSM data plane. To learn about Managed HSM access control model, see Managed HSM access control.

To allow a security principal (such as a user, a service principal, group or a managed identity) to perform managed HSM data plane operations, they must be assigned a role that permits performing those operations. For example, if you want to allow an application to perform a sign operation using a key, it must be assigned a role that contains the "Microsoft.KeyVault/managedHSM/keys/sign/action" as one of the data actions. A role can be assigned at a specific scope. Managed HSM local RBAC supports two scopes, HSM-wide (/ or /keys) and per key (/keys/<keyname>).

For a list of all Managed HSM built-in roles and the operations they permit, see Managed HSM built-in roles.

Prerequisites

To use the Azure CLI commands in this article, you must have the following items:

• A subscription to Microsoft Azure. If you don't have one, you can sign up for a free trial.
• The Azure CLI version 2.25.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install the Azure CLI.
• A managed HSM in your subscription. See Quickstart: Provision and activate a managed HSM using Azure CLI to provision and activate a managed HSM.

Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option	Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To use Azure Cloud Shell:

1. Start Cloud Shell.

2. Select the Copy button on a code block (or command block) to copy the code or command.

3. Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

4. Select Enter to run the code or command.

Sign in to Azure

To sign in to Azure using the CLI you can type:

az login

For more information on login options via the CLI, see sign in with Azure CLI

Create a new role assignment

Assign roles for all keys

Use az keyvault role assignment create command to assign a Managed HSM Crypto User role to user identified by user principal name user2@contoso.com for all keys (scope /keys) in the ContosoHSM.

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

Assign role for a specific key

Use az keyvault role assignment create command to assign a Managed HSM Crypto User role to user identified by user principal name user2@contoso.com for a specific key named myrsakey.

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

List existing role assignments

Use az keyvault role assignment list to list role assignments.

All role assignments at scope / (default when no --scope is specified) for all users (default when no --assignee is specified)

az keyvault role assignment list --hsm-name ContosoMHSM

All the role assignments at the HSM level for a specific user user1@contoso.com.

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

Note

When scope is / (or /keys) the list command only lists all the role assignments at the top level and does not show role assignments at individual key level.

All role assignments for a specific user user2@contoso.com for a specific key myrsakey.

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

A specific role assignment for role Managed HSM Crypto Officer for a specific user user2@contoso.com for a specific key myrsakey

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

Delete a role assignment

Use az keyvault role assignment delete command to delete a Managed HSM Crypto Officer role assigned to user user2@contoso.com for key myrsakey2.

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

List all available role definitions

Use az keyvault role definition list command to list all the role definitions.

az keyvault role definition list --hsm-name ContosoMHSM

Create a new role definition

Managed HSM has several built-in (pre-defined) roles that are useful for most common usage scenarios. You can define your own role with a list of specific actions that the role is allowed to perform. Then you can assign this role to principals to grant them the permission to the specified actions.

Use az keyvault role definition create command to a role named My Custom Role using a JSON string.

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 az keyvault role definition create command to a role from a file named my-custom-role-definition.json containing the JSON string for a role definition. See example above.

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

Show details of a role definition

Use az keyvault role definition show command to see details of a specific role definition using name (a GUID).

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

Update a custom role definition

Use az keyvault role definition update command to update a role named My Custom Role using a JSON string.

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": []
        }'

Delete custom role definition

Use az keyvault role definition delete command to see details of a specific role definition using name (a GUID).

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

Note

Built-in roles cannot be deleted. When custom roles are deleted, all the role assignments using that custom role become defunct.

Next steps

• See an overview of Azure role-based access control (Azure RBAC).
• See a tutorial on Managed HSM role management
• Learn more about Managed HSM access control model
• See all the built-in roles for Managed HSM local RBAC