Managed Hsms - Create Or Update

Create or update a managed HSM Pool in the specified subscription.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/managedHSMs/{name}?api-version=2022-07-01

URI Parameters

Name In Required Type Description
name
path True

string

Name of the managed HSM Pool

resourceGroupName
path True

string

Name of the resource group that contains the managed HSM pool.

subscriptionId
path True

string

Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

api-version
query True

string

Client Api Version.

Request Body

Name Type Description
location

string

The supported Azure location where the managed HSM Pool should be created.

properties

ManagedHsmProperties

Properties of the managed HSM

sku

ManagedHsmSku

SKU details

tags

object

Resource tags

Responses

Name Type Description
200 OK

ManagedHsm

Created or updated managed HSM Pool

202 Accepted

ManagedHsm

Accepted and the operation will complete asynchronously.

Headers

Location: string

Other Status Codes

ManagedHsmError

The error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create a new managed HSM Pool or update an existing managed HSM Pool

Sample request

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/hsm-group/providers/Microsoft.KeyVault/managedHSMs/hsm1?api-version=2022-07-01

{
  "properties": {
    "tenantId": "00000000-0000-0000-0000-000000000000",
    "initialAdminObjectIds": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "enableSoftDelete": true,
    "softDeleteRetentionInDays": 90,
    "enablePurgeProtection": false
  },
  "location": "westus",
  "sku": {
    "family": "B",
    "name": "Standard_B1"
  },
  "tags": {
    "Dept": "hsm",
    "Environment": "dogfood"
  }
}

Sample response

Location: https://some.endpoint.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/hsm-group/providers/Microsoft.KeyVault/managedHSMs/hsm1?api-version=2022-07-01&kv-operation=abJjb2RkIjoiAGVsZXRlTWFuYWdlZEhzbUFzeW5jYm9
{
  "properties": {
    "tenantId": "00000000-0000-0000-0000-000000000000",
    "initialAdminObjectIds": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "enableSoftDelete": true,
    "softDeleteRetentionInDays": 90,
    "enablePurgeProtection": false,
    "hsmUri": null,
    "provisioningState": "Provisioning",
    "statusMessage": "Allocating hardware"
  },
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/hsm-group/providers/Microsoft.KeyVault/managedHSMs/hsm1",
  "name": "hsm1",
  "type": "Microsoft.KeyVault/managedHSMs",
  "location": "westus",
  "sku": {
    "family": "B",
    "name": "Standard_B1"
  },
  "tags": {
    "Dept": "hsm",
    "Environment": "dogfood"
  }
}
{
  "properties": {
    "tenantId": "00000000-0000-0000-0000-000000000000",
    "initialAdminObjectIds": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "enableSoftDelete": true,
    "softDeleteRetentionInDays": 90,
    "enablePurgeProtection": false,
    "hsmUri": "https://westus.hsm1.managedhsm.azure.net",
    "provisioningState": "Succeeded",
    "statusMessage": "ManagedHsm is functional."
  },
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/hsm-group/providers/Microsoft.KeyVault/managedHSMs/hsm1",
  "name": "hsm1",
  "type": "Microsoft.KeyVault/managedHSMs",
  "location": "westus",
  "sku": {
    "family": "B",
    "name": "Standard_B1"
  },
  "tags": {
    "Dept": "hsm",
    "Environment": "dogfood"
  }
}

Definitions

Name Description
ActionsRequired

A message indicating if changes on the service provider require any updates on the consumer.

ActivationStatus

Activation Status

CreateMode

The create mode to indicate whether the resource is being created or is being recovered from a deleted resource.

Error

The server error.

identityType

The type of identity that created the key vault resource.

ManagedHsm

Resource information with extended details.

ManagedHsmError

The error exception.

ManagedHsmProperties

Properties of the managed HSM Pool

ManagedHSMSecurityDomainProperties

The security domain properties of the managed hsm.

ManagedHsmSku

SKU details

ManagedHsmSkuFamily

SKU Family of the managed HSM Pool

ManagedHsmSkuName

SKU of the managed HSM Pool

MHSMIPRule

A rule governing the accessibility of a managed hsm pool from a specific ip address or ip range.

MHSMNetworkRuleSet

A set of rules governing the network accessibility of a managed hsm pool.

MHSMPrivateEndpoint

Private endpoint object properties.

MHSMPrivateEndpointConnectionItem

Private endpoint connection item.

MHSMPrivateLinkServiceConnectionState

An object that represents the approval state of the private link connection.

MHSMVirtualNetworkRule

A rule governing the accessibility of a managed hsm pool from a specific virtual network.

NetworkRuleAction

The default action when no rule from ipRules and from virtualNetworkRules match. This is only used after the bypass property has been evaluated.

NetworkRuleBypassOptions

Tells what traffic can bypass network rules. This can be 'AzureServices' or 'None'. If not specified the default is 'AzureServices'.

PrivateEndpointConnectionProvisioningState

Provisioning state of the private endpoint connection.

PrivateEndpointServiceConnectionStatus

Indicates whether the connection has been approved, rejected or removed by the key vault owner.

ProvisioningState

Provisioning state.

PublicNetworkAccess

Control permission to the managed HSM from public networks.

SystemData

Metadata pertaining to creation and last modification of the key vault resource.

ActionsRequired

A message indicating if changes on the service provider require any updates on the consumer.

Name Type Description
None

string

ActivationStatus

Activation Status

Name Type Description
Active

string

The managed HSM Pool is active.

Failed

string

Failed to activate managed hsm.

NotActivated

string

The managed HSM Pool is not yet activated.

Unknown

string

An unknown error occurred while activating managed hsm.

CreateMode

The create mode to indicate whether the resource is being created or is being recovered from a deleted resource.

Name Type Description
default

string

Create a new managed HSM pool. This is the default option.

recover

string

Recover the managed HSM pool from a soft-deleted resource.

Error

The server error.

Name Type Description
code

string

The error code.

innererror

Error

The inner error, contains a more specific error code.

message

string

The error message.

identityType

The type of identity that created the key vault resource.

Name Type Description
Application

string

Key

string

ManagedIdentity

string

User

string

ManagedHsm

Resource information with extended details.

Name Type Description
id

string

The Azure Resource Manager resource ID for the managed HSM Pool.

location

string

The supported Azure location where the managed HSM Pool should be created.

name

string

The name of the managed HSM Pool.

properties

ManagedHsmProperties

Properties of the managed HSM

sku

ManagedHsmSku

SKU details

systemData

SystemData

Metadata pertaining to creation and last modification of the key vault resource.

tags

object

Resource tags

type

string

The resource type of the managed HSM Pool.

ManagedHsmError

The error exception.

Name Type Description
error

Error

The server error.

ManagedHsmProperties

Properties of the managed HSM Pool

Name Type Default value Description
createMode

CreateMode

The create mode to indicate whether the resource is being created or is being recovered from a deleted resource.

enablePurgeProtection

boolean

True

Property specifying whether protection against purge is enabled for this managed HSM pool. Setting this property to true activates protection against purge for this managed HSM pool and its content - only the Managed HSM service may initiate a hard, irrecoverable deletion. Enabling this functionality is irreversible.

enableSoftDelete

boolean

True

Property to specify whether the 'soft delete' functionality is enabled for this managed HSM pool. Soft delete is enabled by default for all managed HSMs and is immutable.

hsmUri

string

The URI of the managed hsm pool for performing operations on keys.

initialAdminObjectIds

string[]

Array of initial administrators object ids for this managed hsm pool.

networkAcls

MHSMNetworkRuleSet

Rules governing the accessibility of the key vault from specific network locations.

privateEndpointConnections

MHSMPrivateEndpointConnectionItem[]

List of private endpoint connections associated with the managed hsm pool.

provisioningState

ProvisioningState

Provisioning state.

publicNetworkAccess

PublicNetworkAccess

Enabled

Control permission to the managed HSM from public networks.

scheduledPurgeDate

string

The scheduled purge date in UTC.

securityDomainProperties

ManagedHSMSecurityDomainProperties

Managed HSM security domain properties.

softDeleteRetentionInDays

integer

90

Soft deleted data retention days. When you delete an HSM or a key, it will remain recoverable for the configured retention period or for a default period of 90 days. It accepts values between 7 and 90.

statusMessage

string

Resource Status Message.

tenantId

string

The Azure Active Directory tenant ID that should be used for authenticating requests to the managed HSM pool.

ManagedHSMSecurityDomainProperties

The security domain properties of the managed hsm.

Name Type Description
activationStatus

ActivationStatus

Activation Status

activationStatusMessage

string

Activation Status Message.

ManagedHsmSku

SKU details

Name Type Description
family

ManagedHsmSkuFamily

SKU Family of the managed HSM Pool

name

ManagedHsmSkuName

SKU of the managed HSM Pool

ManagedHsmSkuFamily

SKU Family of the managed HSM Pool

Name Type Description
B

string

ManagedHsmSkuName

SKU of the managed HSM Pool

Name Type Description
Custom_B32

string

Custom_B6

string

Standard_B1

string

MHSMIPRule

A rule governing the accessibility of a managed hsm pool from a specific ip address or ip range.

Name Type Description
value

string

An IPv4 address range in CIDR notation, such as '124.56.78.91' (simple IP address) or '124.56.78.0/24' (all addresses that start with 124.56.78).

MHSMNetworkRuleSet

A set of rules governing the network accessibility of a managed hsm pool.

Name Type Description
bypass

NetworkRuleBypassOptions

Tells what traffic can bypass network rules. This can be 'AzureServices' or 'None'. If not specified the default is 'AzureServices'.

defaultAction

NetworkRuleAction

The default action when no rule from ipRules and from virtualNetworkRules match. This is only used after the bypass property has been evaluated.

ipRules

MHSMIPRule[]

The list of IP address rules.

virtualNetworkRules

MHSMVirtualNetworkRule[]

The list of virtual network rules.

MHSMPrivateEndpoint

Private endpoint object properties.

Name Type Description
id

string

Full identifier of the private endpoint resource.

MHSMPrivateEndpointConnectionItem

Private endpoint connection item.

Name Type Description
etag

string

Modified whenever there is a change in the state of private endpoint connection.

id

string

Id of private endpoint connection.

properties.privateEndpoint

MHSMPrivateEndpoint

Properties of the private endpoint object.

properties.privateLinkServiceConnectionState

MHSMPrivateLinkServiceConnectionState

Approval state of the private link connection.

properties.provisioningState

PrivateEndpointConnectionProvisioningState

Provisioning state of the private endpoint connection.

MHSMPrivateLinkServiceConnectionState

An object that represents the approval state of the private link connection.

Name Type Description
actionsRequired

ActionsRequired

A message indicating if changes on the service provider require any updates on the consumer.

description

string

The reason for approval or rejection.

status

PrivateEndpointServiceConnectionStatus

Indicates whether the connection has been approved, rejected or removed by the key vault owner.

MHSMVirtualNetworkRule

A rule governing the accessibility of a managed hsm pool from a specific virtual network.

Name Type Description
id

string

Full resource id of a vnet subnet, such as '/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/subnet1'.

NetworkRuleAction

The default action when no rule from ipRules and from virtualNetworkRules match. This is only used after the bypass property has been evaluated.

Name Type Description
Allow

string

Deny

string

NetworkRuleBypassOptions

Tells what traffic can bypass network rules. This can be 'AzureServices' or 'None'. If not specified the default is 'AzureServices'.

Name Type Description
AzureServices

string

None

string

PrivateEndpointConnectionProvisioningState

Provisioning state of the private endpoint connection.

Name Type Description
Creating

string

Deleting

string

Disconnected

string

Failed

string

Succeeded

string

Updating

string

PrivateEndpointServiceConnectionStatus

Indicates whether the connection has been approved, rejected or removed by the key vault owner.

Name Type Description
Approved

string

Disconnected

string

Pending

string

Rejected

string

ProvisioningState

Provisioning state.

Name Type Description
Activated

string

The managed HSM pool is ready for normal use.

Deleting

string

The managed HSM Pool is currently being deleted.

Failed

string

Provisioning of the managed HSM Pool has failed.

Provisioning

string

The managed HSM Pool is currently being provisioned.

Restoring

string

The managed HSM pool is being restored from full HSM backup.

SecurityDomainRestore

string

The managed HSM pool is waiting for a security domain restore action.

Succeeded

string

The managed HSM Pool has been full provisioned.

Updating

string

The managed HSM Pool is currently being updated.

PublicNetworkAccess

Control permission to the managed HSM from public networks.

Name Type Description
Disabled

string

Enabled

string

SystemData

Metadata pertaining to creation and last modification of the key vault resource.

Name Type Description
createdAt

string

The timestamp of the key vault resource creation (UTC).

createdBy

string

The identity that created the key vault resource.

createdByType

identityType

The type of identity that created the key vault resource.

lastModifiedAt

string

The timestamp of the key vault resource last modification (UTC).

lastModifiedBy

string

The identity that last modified the key vault resource.

lastModifiedByType

identityType

The type of identity that last modified the key vault resource.