Managed HSM role management

This article provides practical instructions for managing roles and role assignments for a Managed HSM by using the Azure CLI. It implements the role-based access control model described in Access control for Managed HSM by using the built-in roles documented in Local RBAC built-in roles for Managed HSM.

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.

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

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

Prerequisites

An Azure subscription is required. If you don't have one, create a free account before you begin.

You also need:

• 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.

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 by using the CLI, enter:

az login

For more information about authentication options through 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 <user-principal-name> for all keys (scope /keys) in the <hsm-name>.

az keyvault role assignment create --hsm-name <hsm-name> --role "Managed HSM Crypto User" --assignee <user-principal-name>  --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 <user-principal-name> for a specific key named <key-name>.

az keyvault role assignment create --hsm-name <hsm-name> --role "Managed HSM Crypto User" --assignee <user-principal-name>  --scope /keys/<key-name>

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 <hsm-name>

All the role assignments at the HSM level for a specific user <user-principal-name>.

az keyvault role assignment list --hsm-name <hsm-name> --assignee <user-principal-name>

All role assignments for a specific user <user-principal-name> for a specific key <key-name>.

az keyvault role assignment list --hsm-name <hsm-name> --assignee <user-principal-name> --scope /keys/<key-name>

A specific role assignment for role Managed HSM Crypto Officer for a specific user <user-principal-name> for a specific key <key-name>

az keyvault role assignment list --hsm-name <hsm-name> --assignee <user-principal-name> --scope /keys/<key-name> --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 <user-principal-name> for key <key-name>.

az keyvault role assignment delete --hsm-name <hsm-name> --role "Managed HSM Crypto Officer" --assignee <user-principal-name>  --scope /keys/<key-name>

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 <hsm-name>

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 <hsm-name> --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 <hsm-name> --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 <hsm-name> --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 <hsm-name> --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 the Azure CLI az keyvault role definition delete command to delete a custom role definition using name (a GUID).

az keyvault role definition delete --hsm-name <hsm-name> --name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Next steps

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