Quickstart: Create an Azure payment HSM using an ARM template

Article
08/07/2024

Azure Payment HSM is a "BareMetal" service delivered using Thales payShield 10K payment hardware security modules (HSM) to provide cryptographic key operations for real-time, critical payment transactions in the Azure cloud. Azure Payment HSM is designed specifically to help a service provider and an individual financial institution accelerate their payment system's digital transformation strategy and adopt the public cloud. For more information, see Azure Payment HSM: Overview.

This quickstart describes how to create a payment HSM with the host and management port in same virtual network. You can instead:

An Azure Resource Manager template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. You describe your intended deployment without writing the sequence of programming commands to create the deployment.

Prerequisites

Important

Azure Payment HSM is a specialized service. To qualify for onboarding and use of Azure Payment HSM, customers must have an assigned Microsoft Account Manager and have a Cloud Service Architect (CSA).

To inquire about the service, start the qualification process, and prepare the prerequisites before on-boarding, ask your Microsoft account manager and CSA to send a request via email.

You must register the "Microsoft.HardwareSecurityModules" and "Microsoft.Network" resource providers, as well as the Azure Payment HSM features. Steps for doing so are at Register the Azure Payment HSM resource provider and resource provider features.

Warning

You must apply the "FastPathEnabled" feature flag to every subscription ID, and add the "fastpathenabled" tag to every virtual network. For more information, see Fastpathenabled.

To quickly ascertain if the resource providers and features are already registered, use the Azure CLI az provider show command. (The output of this command is more readable if you display it in table-format.)
```
az provider show --namespace "Microsoft.HardwareSecurityModules" -o table

az provider show --namespace "Microsoft.Network" -o table

az feature registration show -n "FastPathEnabled"  --provider-namespace "Microsoft.Network" -o table

az feature registration show -n "AzureDedicatedHsm"  --provider-namespace "Microsoft.HardwareSecurityModules" -o table
```
You can continue with this quick start if all four of these commands return "Registered".
You must have an Azure subscription. You can create a free account if you don't have one.

Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
- Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Review the template

The template used in this quickstart is azuredeploy.json:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "resourceName": {
      "type": "String",
      "metadata": {
        "description": "Azure Payment HSM resource name"
      }
    },
    "stampId": {
      "type": "string",
      "defaultValue": "stamp1",
      "metadata": {
        "description": "stamp id"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "skuName": {
      "type": "string",
      "defaultValue": "payShield10K_LMK1_CPS60",
      "metadata": {
        "description": "PayShield SKU name. It must be one of the following: payShield10K_LMK1_CPS60, payShield10K_LMK1_CPS250, payShield10K_LMK1_CPS2500, payShield10K_LMK2_CPS60, payShield10K_LMK2_CPS250, payShield10K_LMK2_CPS2500"
      }
    },
    "vnetName": {
      "type": "string",
      "metadata": {
        "description": "Virtual network name"
      }
    },
    "vnetAddressPrefix": {
      "type": "string",
      "metadata": {
        "description": "Virtual network address prefix"
      }
    },
    "hsmSubnetName": {
      "type": "String",
      "metadata": {
        "description": "Subnet name"
      }
    },
    "hsmSubnetPrefix": {
      "type": "string",
      "metadata": {
        "description": "Subnet prefix"
      }
    }
  },
  "variables": {},
  "resources": [
   {
     "type": "Microsoft.HardwareSecurityModules/dedicatedHSMs",
     "apiVersion": "2021-11-30",
     "name": "[parameters('resourceName')]",
	   "location": "[parameters('location')]",
     "dependsOn": [
      "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('hsmSubnetName'))]"
     ],
     "sku": {
       "name": "[parameters('skuName')]"
     },
     "properties": {
       "networkProfile": {
         "subnet": {
           "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('hsmSubnetName'))]"
         }
        },
		"managementNetworkProfile": {
          "subnet": {
            "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('hsmSubnetName'))]"
          }
        },
        "stampId": "[parameters('stampId')]"
     }
   },
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2020-11-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "tags": {
        "fastpathenabled": "true"
      },
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vnetAddressPrefix')]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('hsmSubnetName')]",
            "properties": {
              "addressPrefix": "[parameters('hsmSubnetPrefix')]",
              "delegations": [
                {
                  "name": "Microsoft.HardwareSecurityModules.dedicatedHSMs",
                  "properties": {
                    "serviceName": "Microsoft.HardwareSecurityModules/dedicatedHSMs"
                  }
                }
              ],
              "privateEndpointNetworkPolicies": "Enabled",
              "privateLinkServiceNetworkPolicies": "Enabled"
            }
          }
        ],
        "enableDdosProtection": false
      }
    },
    {
      "type": "Microsoft.Network/virtualNetworks/subnets",
      "apiVersion": "2020-11-01",
      "name": "[concat(parameters('vnetName'), '/', parameters('hsmSubnetName'))]",
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ],
      "properties": {
        "addressPrefix": "[parameters('hsmSubnetPrefix')]",
        "delegations": [
          {
            "name": "Microsoft.HardwareSecurityModules.dedicatedHSMs",
            "properties": {
              "serviceName": "Microsoft.HardwareSecurityModules/dedicatedHSMs"
            }
          }
        ],
        "privateEndpointNetworkPolicies": "Enabled",
        "privateLinkServiceNetworkPolicies": "Enabled"
      }
    }
  ]
}

The Azure resource defined in the template is:

Microsoft.HardwareSecurityModules.dedicatedHSMs: Create an Azure payment HSM.

The corresponding azuredeploy.parameters.json file is:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "resourceName": {
      "value": "myhsm1"
    },
    "stampId": {
      "value": "stamp1"
    },
    "skuName": {
      "value": "payShield10K_LMK1_CPS60"
    },
    "vnetName": {
      "value": "myHsmVnet"
    },
    "vnetAddressPrefix": {
      "value": "10.0.0.0/16"
    },
    "hsmSubnetName": {
      "value": "myHsmSubnet"
    },
    "hsmSubnetPrefix": {
      "value": "10.0.0.0/24"
    }
  }
}

In this example, you use the Azure CLI to deploy an ARM template to create an Azure payment HSM.

First, save the "azuredeploy.json" and "azuredeploy.parameters.json" files locally, for use in the next step. The contents of these files can be found in the Review the template section.

Note

The steps below assume that the "azuredeploy.json" and "azuredeploy.parameters.json" file are in the directory from which you are running the commands. If the files are in another directory, you must adjust the file paths accordingly.

Next, create an Azure resource group.

A resource group is a logical container into which Azure resources are deployed and managed. Use the az group create command to create a resource group named myResourceGroup in the eastus location.

az group create --name "myResourceGroup" --location "EastUS"

Finally, use the Azure CLI az deployment group create command to deploy your ARM template.

az deployment group create --resource-group "MyResourceGroup" --name myPHSMDeployment --template-file "azuredeploy.json"

When prompted, supply the following values for the parameters:

resourceName: myPaymentHSM
vnetName: myVNet
vnetAddressPrefix: 10.0.0.0/16
hsmSubnetName: mySubnet
hsmSubnetPrefix: 10.0.0.0/24

In this example, you use the Azure PowerShell to deploy an ARM template to create an Azure payment HSM.

First, save the "azuredeploy.json" and "azuredeploy.parameters.json" files locally, for use in the next step. The contents of these files can be found in the Review the template section.

Note

Next, create an Azure resource group.

A resource group is a logical container into which Azure resources are deployed and managed. Use the Azure PowerShell New-AzResourceGroup cmdlet to create a resource group named myResourceGroup in the eastus location.

New-AzResourceGroup -Name "myResourceGroup" -Location "EastUS"

Now, set the following variables for use in the deploy step:

$deploymentName = "myPHSMDeployment"
$resourceGroupName = "myResourceGroup"
$templateFilePath = "azuredeploy.json" 
$templateParametersPath = "azuredeploy.parameters.json" 
$resourceName = "myPaymentHSM"
$vnetName = "myVNet" 
$vnetAddressPrefix = "10.0.0.0/16" 
$subnetName = "mySubnet" 
$subnetPrefix = "10.0.0.0/24"

Finally, use the Azure PowerShell New-AzResourceGroupDeployment cmdlet to deploy your ARM template.

New-AzResourceGroupDeployment -Name $deploymentName -ResourceGroupName $resourceGroupName -TemplateFile $templateFilePath -TemplateParameterFile $templateParametersPath -resourceName $resourceName -vnetName $vnetName -vnetAddressPrefix $vnetAddressPrefix -hsmSubnetName $subnetName -hsmSubnetPrefix $subnetPrefix

Validate the deployment

Azure CLI
Azure PowerShell

You can verify that the payment HSM was created with the Azure CLI az dedicated-hsm list command. The output is easier to read if you format the results as a table:

az dedicated-hsm list -o table

You can verify that the payment HSM was created with the Azure PowerShell Get-AzDedicatedHsm cmdlet.

Get-AzDedicatedHsm

You should see the name of your newly created payment HSM.

Clean up resources

Azure CLI
Azure PowerShell

Other quickstarts and tutorials in this collection build upon this quickstart. If you plan to continue on to work with subsequent quickstarts and tutorials, you may wish to leave these resources in place.

When no longer needed, you can use the Azure CLI az group delete command to remove the resource group and all related resources:

az group delete --name "myResourceGroup"

Other quickstarts and tutorials in this collection build upon this quickstart. If you plan to continue on to work with other quickstarts and tutorials, you may want to leave these resources in place.

When no longer needed, you can use the Azure PowerShell Remove-AzResourceGroup cmdlet to remove the resource group and all related resources.

Remove-AzResourceGroup -Name "myResourceGroup"

Next steps

In this quickstart, you deployed an Azure Resource Manager template to create a payment HSM, verified the deployment, and deleted the payment HSM. To learn more about Azure Payment HSM and how to integrate it with your applications, continue on to the articles below.

Read an Overview of Payment HSM
Find out how to get started with Azure Payment HSM
See some common deployment scenarios
Learn about Certification and compliance
Read the frequently asked questions

Share via