Configure a S2S VPN Gateway certificate authentication connection - Azure CLI

This article shows you how to use Azure CLI to create a site-to-site (S2S) VPN gateway connection between your on-premises network and an Azure virtual network using X.509 certificate-based authentication. Certificate authentication provides stronger security compared to preshared keys (PSK) for VPN connections.

Site-to-site certificate authentication relies on both inbound and outbound certificates to establish secure VPN tunnels. The certificates are securely stored in Azure Key Vault, and each VPN gateway accesses its certificates through a User-Assigned Managed Identity. For more information about the certificates and how the certificate flow works, see About site-to-site VPN connections with certificate authentication.

In this article, you generate the necessary certificates, create the required Azure resources, and configure the site-to-site VPN connection by using Azure CLI.

Before you begin

To complete the steps in this article, ensure you have the following prerequisites:

• An Azure account with an active subscription. If you don't have one, create one for free.
• Azure CLI installed locally or Azure Cloud Shell. For more information, see Install the Azure CLI.
• Familiarity with IP address ranges in your on-premises network configuration.
• A compatible VPN device and someone who can configure it. For more information about compatible VPN devices, see About VPN devices.
• An externally facing public IPv4 address for your on-premises VPN device.
• Ensure that the subnets of your on-premises network don't overlap with the virtual network subnets you want to connect to.

Generate the digital certificates

First, generate the self-signed root CA certificates and the leaf certificates required for VPN authentication. The root CA certificate establishes the trust chain and is used to sign the leaf certificates.

You have two options:

• Use the same root certificate to sign the leaf certificates for both the Azure VPN gateway and the on-premises device.
• Use separate root certificates, one to sign the leaf certificates for the Azure VPN gateway, and another to sign the leaf certificates for the on-premises VPN device.

In the following examples, two root certificates are used: one root certificate signs the leaf certificate used for outbound authentication from Azure to on-premises, and the other root certificate is used to sign the leaf certificates for the on-premises device.

Create self-signed root CA certificates

Use OpenSSL to create self-signed root certificates. The following example creates a self-signed root certificate named VPNRootCA1, which is automatically stored in the local folder certs.

Run the following commands from a bash terminal to create the root certificate for the Azure VPN gateway.

# Define the root certificate subject for Azure VPN
azureRootcertSubject1='VPNRootCA1'

# Define the local folder to store the digital certificates
pathFiles="$(pwd)"
certPath="$pathFiles/certs/"
echo "folder to store digital certificates: $certPath"

# Create a local folder ./certs/
mkdir -p "$certPath"

# Generate the private key for the Azure VPN gateway root certificate
openssl genrsa -out "$certPath${azureRootcertSubject1}.key" 2048

# Generate the self-signed root certificate for the Azure VPN gateway
openssl req -x509 -new -nodes \
    -key "$certPath${azureRootcertSubject1}.key" \
    -sha256 \
    -days 3650 \
    -out "$certPath${azureRootcertSubject1}.cer" \
    -subj "/CN=$azureRootcertSubject1" \
    -extensions v3_ca \
    -config <(cat <<EOF
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_ca
[req_distinguished_name]
[v3_ca]
basicConstraints = critical, CA:TRUE, pathlen:4
keyUsage = critical, keyCertSign, cRLSign
EOF
)

Run the following commands to create the root certificate for the on-premises VPN device.

# Define the root certificate subject for the on-premises VPN device
onpremRootcertSubject1='VPNRootCA2'
echo "Creating Root Certificate: $onpremRootcertSubject1"

# Generate the private key for the on-premises root certificate
openssl genrsa -out "$certPath${onpremRootcertSubject1}.key" 2048

# Generate the self-signed root certificate for the on-premises VPN device
openssl req -x509 -new -nodes \
    -key "$certPath${onpremRootcertSubject1}.key" \
    -sha256 \
    -days 3650 \
    -out "$certPath${onpremRootcertSubject1}.cer" \
    -subj "/CN=$onpremRootcertSubject1" \
    -extensions v3_ca \
    -config <(cat <<EOF
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_ca
[req_distinguished_name]
[v3_ca]
basicConstraints = critical, CA:TRUE, pathlen:4
keyUsage = critical, keyCertSign, cRLSign
EOF
)
echo "Root certificate $onpremRootcertSubject1 created"

To generate leaf certificates, leave the bash terminal open and proceed with the next steps.

Generate leaf certificates signed by the root CA certificates

Generate leaf certificates signed by the root certificates. Use these certificates for site-to-site VPN authentication. The following examples use OpenSSL to generate outbound and inbound leaf certificates. When you create the certificates, the process automatically stores them in ./certs on your Linux computer.

Create outbound certificate for the VPN gateway

azureLeafcertSubject1='s2s-cert1'
echo "$(date) - start creation leaf cert: $azureLeafcertSubject1"

# Generate the private key
openssl genrsa -out "$certPath${azureLeafcertSubject1}.key" 2048

# Generate the certificate signing request (CSR)
openssl req -new \
    -key "$certPath${azureLeafcertSubject1}.key" \
    -out "$certPath${azureLeafcertSubject1}.csr" \
    -subj "/CN=$azureLeafcertSubject1"

# Sign the leaf certificate for the Azure VPN gateway with Root CA 1
openssl x509 -req \
    -in "$certPath${azureLeafcertSubject1}.csr" \
    -CA "$certPath${azureRootcertSubject1}.cer" \
    -CAkey "$certPath${azureRootcertSubject1}.key" \
    -CAcreateserial \
    -out "$certPath${azureLeafcertSubject1}.cer" \
    -days 3650 \
    -sha256 \
    -extfile <(cat <<EOF
extendedKeyUsage = clientAuth, serverAuth
EOF
)
echo "$(date) - Leaf cert: $azureLeafcertSubject1 created"

Create outbound certificate for the on-premises device

onpremLeafcertSubject1='s2s-cert2'

# Generate the private key
openssl genrsa -out "$certPath${onpremLeafcertSubject1}.key" 2048

# Generate the certificate signing request (CSR)
openssl req -new \
   -key "$certPath${onpremLeafcertSubject1}.key" \
   -out "$certPath${onpremLeafcertSubject1}.csr" \
   -subj "/CN=$onpremLeafcertSubject1"

# Sign the leaf certificate with Root CA 2, used for the on-premises VPN device
openssl x509 -req \
   -in "$certPath${onpremLeafcertSubject1}.csr" \
   -CA "$certPath${onpremRootcertSubject1}.cer" \
   -CAkey "$certPath${onpremRootcertSubject1}.key" \
   -CAcreateserial \
   -out "$certPath${onpremLeafcertSubject1}.cer" \
   -days 3650 \
   -sha256 \
   -extfile <(cat <<EOF
extendedKeyUsage = clientAuth, serverAuth
EOF
)

Export the certificates

Export the root certificates in Base64 format (.cer) and the leaf certificates in PKCS#12 format (.pfx).

pathFiles="$(pwd)"
certPath="$pathFiles/certs/"
certPassword="12345"

# Export the Azure leaf certificate and its private key to a .pfx file
openssl pkcs12 -export \
    -out "$certPath${azureLeafcertSubject1}.pfx" \
    -inkey "$certPath${azureLeafcertSubject1}.key" \
    -in "$certPath${azureLeafcertSubject1}.cer" \
    -certfile "$certPath${azureRootcertSubject1}.cer" \
    -passout "pass:$certPassword"

Declare Azure environment variables

The next sections refer to the variables defined in the following code block. Update the variable values to match your environment before running the script.

# Resource group name and location for the deployment of Azure resources
rgName="s2s-cert-azcli"
location='eastus'

# Variables for the virtual network
vnet1Name='vnet1'
vnet1Address='10.1.0.0/16'
gw1SubnetAddress='10.1.0.0/24'

# VPN gateway name
gw1Name='gw1'
gw1ConfigName='gw1-config'

Create virtual networks and gateway subnets

Create a resource group to contain the resources for this deployment. You can either create a new resource group or select one that you already created.

# Create a resource group
az group create --name "$rgName" --location "$location"

# Add tags for organization (optional)
az group update --name "$rgName" --tags usage="s2s-digitalcertificates" --output none

Create the virtual network with a gateway subnet. The gateway subnet must be named GatewaySubnet and should be /27 or larger.

# Create the virtual network
az network vnet create \
    --resource-group "$rgName" \
    --name "$vnet1Name" \
    --address-prefix "$vnet1Address" \
    --location "$location"

# Add the GatewaySubnet
az network vnet subnet create \
    --resource-group "$rgName" \
    --vnet-name "$vnet1Name" \
    --name "GatewaySubnet" \
    --address-prefix "$gw1SubnetAddress"

Create a user-assigned managed identity

This configuration requires a managed identity. VPN gateways use user-assigned managed identities to securely access certificates stored in Azure Key Vault. For more information about managed identities, see What are managed identities for Azure resources.

When creating the managed identity name, use something intuitive, such as gw1-s2s-kv or vpngwy-managed. You need the name for Key Vault configuration steps. The resource group doesn't have to be the same as the resource group used for your VPN gateway.

# Create a user-assigned managed identity for the VPN gateway to access the Azure Key Vault
gw1UserIdentityName='gw1-s2s-kv'
az identity create --resource-group "$rgName" --name "$gw1UserIdentityName" --location "$location"

A user-assigned managed identity name doesn't need to be globally unique across subscriptions. It only needs to be unique within the resource group where you create it.

Create a Key Vault and configure RBAC permissions

This configuration requires Azure Key Vault. Create a Key Vault to store the certificates and configure RBAC permissions for secure access. For more information about Azure Key Vault, see About Azure Key Vault.

# Generate a globally unique Azure Key Vault name.
# Key Vault names must be unique across all Azure regions and must not exceed 24 characters.
suffix="ALFANUMERIC_VALUE"
keyVault1Name="kv-$suffix"

# Delete the Key Vault if it's in the soft-deleted state, to avoid failure
az keyvault purge --name "$keyVault1Name" --location "$location"

# Create the Key Vault - Azure RBAC is the default access control model for newly created vaults
az keyvault create --name "$keyVault1Name" --resource-group "$rgName" --location "$location"

Assign RBAC roles to managed identities

Grant the managed identities the necessary permissions to access certificates in Key Vault by using Azure RBAC.

# Define the RBAC role IDs
secretsUserRoleId="4633458b-17de-408a-b874-0445c86b69e6"    # built-in role "Key Vault Secrets User"
certUserRoleId="db79e9a7-68ee-4b58-9aeb-b90e7c24fcba"       # built-in role "Key Vault Certificate User"
certOfficerRoleId="a4417e6f-fecd-4de8-b567-7b0420556985"    # built-in role "Key Vault Certificates Officer" (for full certificate management)

keyVaultResourceId=$(az keyvault show --name "$keyVault1Name" --resource-group "$rgName" --query id -o tsv)

# Get the Microsoft Entra service principal object ID of the managed identity
gw1UserIdentityPrincipalId=$(az identity show --resource-group "$rgName" --name "$gw1UserIdentityName" --query principalId -o tsv)

# Assign RBAC roles to the user-assigned managed identity to access the Key Vault
az role assignment create --assignee-object-id "$gw1UserIdentityPrincipalId" \
    --assignee-principal-type ServicePrincipal \
    --role "$certUserRoleId" \
    --scope "$keyVaultResourceId"

az role assignment create --assignee-object-id "$gw1UserIdentityPrincipalId" \
    --assignee-principal-type ServicePrincipal \
    --role "$secretsUserRoleId" \
    --scope "$keyVaultResourceId"

# Assign the Key Vault Certificates Officer role to the current user (required to import certificates)
currentUser=$(az account show --query user.name -o tsv)
currentUserObjectId=$(az ad user show --id "$currentUser" --query id -o tsv)

az role assignment create --assignee-object-id "$currentUserObjectId" \
    --assignee-principal-type User \
    --role "$certOfficerRoleId" \
    --scope "$keyVaultResourceId"

RBAC permission changes don't take effect immediately. As a best practice, allow roughly two minutes for the updated role assignments to propagate before validating that the permissions reached the user-assigned managed identity. If RBAC hasn't yet propagated, the next steps might fail.

Import certificates to Key Vault

Upload the outbound leaf certificate (with the private key) to Azure Key Vault. The certificate file must be in .pfx format.

pathFiles="$(pwd)"
certPath="$pathFiles/certs/"
azureLeafcertSubject1='s2s-cert1'
cert1FilePath="$certPath${azureLeafcertSubject1}.pfx"
certPassword="12345"

# Name assigned to the certificate object stored in Azure Key Vault for the VPN gateway
gw1OutboundCertName='gw1-cert'

az keyvault certificate import \
    --vault-name "$keyVault1Name" \
    --name "$gw1OutboundCertName" \
    --file "$cert1FilePath" \
    --password "$certPassword"

Create public IP addresses for the VPN gateway

Create zone-redundant Standard SKU public IP addresses for the VPN gateway. The VPN gateway is configured in active-active mode, so two public IP addresses are required.

# Create public IP 1 for Gateway 1
gw1pubIP1Name="${gw1Name}pip1"
az network public-ip create \
    --resource-group "$rgName" \
    --name "$gw1pubIP1Name" \
    --location "$location" \
    --allocation-method Static \
    --sku Standard \
    --tier Regional \
    --zone 1 2 3

# Create public IP 2 for Gateway 1
gw1pubIP2Name="${gw1Name}pip2"
az network public-ip create \
    --resource-group "$rgName" \
    --name "$gw1pubIP2Name" \
    --location "$location" \
    --allocation-method Static \
    --sku Standard \
    --tier Regional \
    --zone 1 2 3

Create a VPN gateway

Create a VPN gateway by using the user-assigned managed identity for Key Vault access.

# Create the Azure VPN gateway in active-active mode
az network vnet-gateway create \
    --resource-group "$rgName" \
    --name "$gw1Name" \
    --location "$location" \
    --public-ip-address "$gw1pubIP1Name" "$gw1pubIP2Name" \
    --vnet "$vnet1Name" \
    --gateway-type Vpn \
    --vpn-type RouteBased \
    --sku VpnGw2AZ \
    --vpn-gateway-generation Generation2

# Get the user-assigned managed identity created earlier
gw1UserIdentityId=$(az identity show \
  --resource-group "$rgName" \
  --name "$gw1UserIdentityName" \
  --query id -o tsv)

# Attach the user-assigned managed identity to the existing Azure VPN gateway
echo "$(date) - updating vpn gateway with managed identity"
az network vnet-gateway identity assign \
    --resource-group "$rgName" \
    --name "$gw1Name" \
    --user-assigned "$gw1UserIdentityId"

# Verify the user-assigned managed identity is associated with the VPN gateway
az network vnet-gateway identity show \
  --resource-group "$rgName" \
  --name "$gw1Name" \
  --query userAssignedIdentities \
  -o json

You can check the VPN gateway provisioning state by using the following command.

az network vnet-gateway show \
  --resource-group "$rgName" \
  --name "$gw1Name" \
  --query provisioningState \
  -o tsv

At the end of the deployment, the command returns Succeeded. Proceed with the next step only when the VPN gateway deployment succeeds.

Create local network gateways

The local network gateway is a specific object that represents your on-premises location (the site) for routing purposes. You give the site a name by which Azure can refer to it, and then specify the IP address of the on-premises VPN device to which you create a connection. You also specify the IP address prefixes that are routed through the VPN gateway to the VPN device. The address prefixes you specify are the prefixes located on your on-premises network. If your on-premises network changes or you need to change the public IP address for the VPN device, you can easily update the values later.

Configuration considerations:

• FQDN support: If you have a dynamic public IP address, you can use a constant DNS name with a Dynamic DNS service to point to your current public IP address. Your Azure VPN gateway resolves the FQDN to determine the public IP address to connect to.
• Single IP address: VPN Gateway supports only one IPv4 address for each FQDN. If the domain name resolves to multiple IP addresses, VPN Gateway uses the first IP address returned by the DNS servers. Microsoft recommends that your FQDN always resolve to a single IPv4 address. IPv6 isn't supported.
• DNS cache: VPN Gateway maintains a DNS cache that's refreshed every 5 minutes. The gateway tries to resolve the FQDNs for disconnected tunnels only. Resetting the gateway also triggers FQDN resolution.
• Multiple connections: Although VPN Gateway supports multiple connections to different local network gateways with different FQDNs, all FQDNs must resolve to different IP addresses.

Create local network gateways to represent the on-premises network site. Each local network gateway specifies the public IP address and address prefixes of the remote on-premises site.

# Public IP addresses of the on-premises VPN device
site1publicIP1="PUBLIC_IP_ADDRESS_1_ON_PREMISES_DEVICE"
site1publicIP2="PUBLIC_IP_ADDRESS_2_ON_PREMISES_DEVICE"
onpremAddressPrefix="10.2.0.0/16"

# Create the local network gateway for Site1
# The remote peer is the first on-premises public IP: $site1publicIP1
localNetGwSite11Name='localNetSite11'
az network local-gateway create \
    --resource-group "$rgName" \
    --name "$localNetGwSite11Name" \
    --location "$location" \
    --local-address-prefixes "$onpremAddressPrefix" \
    --gateway-ip-address "$site1publicIP1"

# Create the local network gateway for Site1
# The remote peer is the second on-premises public IP: $site1publicIP2
localNetGwSite12Name='localNetSite12'
az network local-gateway create \
    --resource-group "$rgName" \
    --name "$localNetGwSite12Name" \
    --location "$location" \
    --local-address-prefixes "$onpremAddressPrefix" \
    --gateway-ip-address "$site1publicIP2"

Configure your on-premises VPN device

Site-to-site connections to an on-premises network require a VPN device. When you configure your VPN device, you need the following values:

• Certificate: You need the certificate data used for authentication. This certificate is also used as the inbound certificate when creating the VPN connection.
• Public IP address values for your virtual network gateway: To find the public IP address for your VPN gateway VM instance using the Azure portal, go to your virtual network gateway and look under Settings > Properties. If you have an active-active mode gateway (recommended), make sure to set up tunnels to each VPN gateway instance. Both tunnels are part of the same connection. Active-active mode VPN gateways have two public IP addresses, one for each gateway VM instance.

Depending on the VPN device that you have, you might be able to download a VPN device configuration script. For more information, see Download VPN device configuration scripts. See the following table for VPN device configuration resources.

Create VPN connections with certificate authentication

Create the VPN connections using certificate authentication. Each connection uses the outbound certificate from Azure Key Vault and validates inbound connections against the remote site's root certificate chain.

Prepare outbound certificate authentication information for the VPN gateway

Use the following commands to get the reference to the outbound certificate stored in Azure Key Vault.

# Get outbound certificate information from Key Vault for the Azure VPN gateway connections
gw1OutboundCertUrl=$(az keyvault certificate show --vault-name "$keyVault1Name" \
  --name "$gw1OutboundCertName" --query id -o tsv)

The gw1OutboundCertUrl variable contains the path to the outbound certificate in Azure Key Vault. To check the value, use the following command.

echo $gw1OutboundCertUrl

The path is specific to the certificate and looks like: https://your-keyvault.vault.azure.net/certificates/certificate-name/<certificate-value>.

Prepare inbound certificate information for the VPN gateway

The following steps assume that you export the root certificate and store it on the local computer in the folder specified by the certPath variable, with the name VPNRootCA2.cer (Base64-encoded). This certificate is the on-premises root certificate generated earlier in Create self-signed root CA certificates. Use the certificate information to verify the incoming inbound certificate in the VPN gateway. It doesn't contain private keys.

pathFiles="$(pwd)"
certPath="$pathFiles/certs"

onpremLeafcertSubject1=$(openssl x509 -in "$certPath/s2s-cert2.cer" -noout -subject | sed -E 's/^subject= ?CN=//')

# Read the inbound certificate chain file for the Azure VPN gateway.
# This is the Root CA certificate in Base64 format for the on-premises VPN device.
inboundCert2Path="$certPath/VPNRootCA2.cer"
inboundCert2Base64=$(grep -v "BEGIN CERTIFICATE" "$inboundCert2Path" | grep -v "END CERTIFICATE" | tr -d '\n\r')

You should always have at least two certificates in the inbound certificate section when using intermediate CAs.

At this stage, assume that you already created the on-premises device's leaf certificate and that you can retrieve the certificate's subject name. On the on-premises device, extract the Common Name (CN) from the outbound leaf certificate. In the example workflow, the CN is onprem-s2s-1, but you should verify the CN value used in your own environment.

Don't include the CN= prefix in the variable value.

Create certificate authentication objects

# Create the certificate authentication object in JSON format for the Azure VPN gateway
# Gateway 1 uses its own certificate for outbound, and trusts Root CA 2 for inbound
certAuthJson="{\"outboundAuthCertificate\":\"$gw1OutboundCertUrl\",\"inboundAuthCertificateChain\":[\"$inboundCert2Base64\"],\"inboundAuthCertificateSubjectName\":\"$onpremLeafcertSubject1\"}"

Create the VPN connections

Deploy two connections to connect two site-to-site tunnels from the VPN gateway to the on-premises device.

# Create connection 1 from Gateway1 to site1
gw1Connection11Name='Connection11'
az network vpn-connection create \
    --resource-group "$rgName" \
    --name "$gw1Connection11Name" \
    --location "$location" \
    --vnet-gateway1 "$gw1Name" \
    --local-gateway2 "$localNetGwSite11Name" \
    --auth-type Certificate \
    --cert-auth "$certAuthJson" \
    --routing-weight 3

# Create connection 2 from Gateway1 to site1
gw1Connection12Name='Connection12'
az network vpn-connection create \
    --resource-group "$rgName" \
    --name "$gw1Connection12Name" \
    --location "$location" \
    --vnet-gateway1 "$gw1Name" \
    --local-gateway2 "$localNetGwSite12Name" \
    --auth-type Certificate \
    --cert-auth "$certAuthJson" \
    --routing-weight 3

Verify the VPN connection

After you create the connections, verify the VPN gateway setting.

echo "$(date) - checking vpn connection: $gw1Connection11Name"
vpnConnection11=$(az network vpn-connection show --resource-group "$rgName" --name "$gw1Connection11Name")
echo "$gw1Name - connection name......: $(echo "$vpnConnection11" | jq -r '.name')"
echo "$gw1Name - connection type......: $(echo "$vpnConnection11" | jq -r '.connectionType')"
echo "$gw1Name - authentication type..: $(echo "$vpnConnection11" | jq -r '.authenticationType')"
echo "$gw1Name - connection status....: $(echo "$vpnConnection11" | jq -r '.connectionStatus')"

echo "$(date) - checking vpn connection: $gw1Connection12Name"
vpnConnection12=$(az network vpn-connection show --resource-group "$rgName" --name "$gw1Connection12Name")
echo "$gw1Name - connection name......: $(echo "$vpnConnection12" | jq -r '.name')"
echo "$gw1Name - connection type......: $(echo "$vpnConnection12" | jq -r '.connectionType')"
echo "$gw1Name - authentication type..: $(echo "$vpnConnection12" | jq -r '.authenticationType')"
echo "$gw1Name - connection status....: $(echo "$vpnConnection12" | jq -r '.connectionStatus')"

When the VPN tunnels are successfully established, the connection status shows as Connected.

You can also verify the connection in the Azure portal:

1. Go to your virtual network gateway in the portal.
2. Select Connections in the left pane.
3. Verify the connection status shows Connected.

Next steps

After your connection is complete, you can configure additional VPN Gateway settings. For more information, see the following articles:

• About VPN Gateway configuration settings
• Configure BGP for VPN Gateway
• About highly available VPN gateway connections
• About Key Vault
• Azure Key Vault RBAC guide

Related content

• Tutorial: Create a site-to-site VPN connection in the Azure portal
• About cryptographic requirements and Azure VPN gateways
• Configure a S2S VPN Gateway certificate authentication connection - PowerShell
• Generate and export certificates for point-to-site using PowerShell