Configure MACsec on ExpressRoute Direct ports

This article helps you configure MACsec to secure the connections between your edge routers and Microsoft's edge routers using PowerShell.

Before you begin

Before you start configuration, confirm the following:

Working with Azure PowerShell

The steps and examples in this article use Azure PowerShell Az modules. To install the Az modules locally on your computer, see Install Azure PowerShell. To learn more about the new Az module, see Introducing the new Azure PowerShell Az module. PowerShell cmdlets are updated frequently. If you are not running the latest version, the values specified in the instructions may fail. To find the installed versions of PowerShell on your system, use the Get-Module -ListAvailable Az cmdlet.

You can use Azure Cloud Shell to run most PowerShell cmdlets and CLI commands, instead of installing Azure PowerShell or CLI locally. Azure Cloud Shell is a free interactive shell that has common Azure tools preinstalled and is configured to use with your account. To run any code contained in this article on Azure Cloud Shell, open a Cloud Shell session, use the Copy button on a code block to copy the code, and paste it into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS. Pasted text is not automatically executed, press Enter to run code.

There are a few ways to launch the Cloud Shell:

Option Link
Click Try It in the upper right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser.
Click the Cloud Shell button on the menu in the upper right of the Azure portal. Cloud Shell in the portal

Sign in and select the right subscription

To start the configuration, sign in to your Azure account and select the subscription that you want to use.

If you are using the Azure Cloud Shell, you sign in to your Azure account automatically after clicking 'Try it'. To sign in locally, open your PowerShell console with elevated privileges and run the cmdlet to connect.


If you have more than one subscription, get a list of your Azure subscriptions.


Specify the subscription that you want to use.

Select-AzSubscription -SubscriptionName "Name of subscription"

Create Azure Key Vault, MACsec secrets, and user identity

  1. Create a Key Vault instance to store MACsec secrets in a new resource group.

    New-AzResourceGroup -Name "your_resource_group" -Location "resource_location"
    $keyVault = New-AzKeyVault -Name "your_key_vault_name" -ResourceGroupName "your_resource_group" -Location "resource_location" -SoftDeleteRetentionInDays 90

    If you already have a Key Vault or a resource group, you can reuse them. However, it's critical that you enable the soft-delete feature on your existing Key Vault. If soft-delete isn't enabled, run the following commands to enable it:

    ($resource = Get-AzResource -ResourceId (Get-AzKeyVault -VaultName "your_existing_keyvault").ResourceId).Properties | Add-Member -MemberType "NoteProperty" -Name "enableSoftDelete" -Value "true"
    Set-AzResource -resourceid $resource.ResourceId -Properties $resource.Properties


    The Key Vault shouldn't be behind a private endpoint because communication to the ExpressRoute management plane is required.

  2. Create a user identity.

    $identity = New-AzUserAssignedIdentity  -Name "identity_name" -Location "resource_location" -ResourceGroupName "your_resource_group"

    If New-AzUserAssignedIdentity isn't recognized as a valid PowerShell cmdlet, install the following module (in Administrator mode) and rerun the above command.

    Install-Module -Name Az.ManagedServiceIdentity
  3. Create a connectivity association key (CAK) and a connectivity association key name (CKN) and store them in the Key Vault.

    $CAK = ConvertTo-SecureString "your_key" -AsPlainText -Force
    $CKN = ConvertTo-SecureString "your_key_name" -AsPlainText -Force
    $MACsecCAKSecret = Set-AzKeyVaultSecret -VaultName "your_key_vault_name" -Name "CAK_name" -SecretValue $CAK
    $MACsecCKNSecret = Set-AzKeyVaultSecret -VaultName "your_key_vault_name" -Name "CKN_name" -SecretValue $CKN


    CKN must be an even-length string up to 64 hexadecimal digits (0-9, A-F).

    CAK length depends on cipher suite specified:

    • For GcmAes128, the CAK must be an even-length string up to 32 hexadecimal digits (0-9, A-F).
    • For GcmAes256, the CAK must be an even-length string up to 64 hexadecimal digits (0-9, A-F).
  4. Assign the GET permission to the user identity.

    Set-AzKeyVaultAccessPolicy -VaultName "your_key_vault_name" -PermissionsToSecrets get -ObjectId $identity.PrincipalId

    Now this identity can get the secrets, for example CAK and CKN, from the Key Vault.

  5. Set this user identity to be used by ExpressRoute.

    $erIdentity = New-AzExpressRoutePortIdentity -UserAssignedIdentityId $identity.Id

Configure MACsec on ExpressRoute Direct ports

To enable MACsec

Each ExpressRoute Direct instance has two physical ports. You can choose to enable MACsec on both ports at the same time or enable MACsec one port at a time. Doing it one port at time by switching traffic to an active port while servicing the other port can help minimize the interruption if your ExpressRoute Direct is already in service.


You can configure both XPN and Non-XPN ciphers:

  • GcmAes128
  • GcmAes256
  • GcmAesXpn128
  • GcmAesXpn256
  1. Set MACsec secrets and cipher and associate the user identity with the port so that the ExpressRoute management code can access the MACsec secrets if needed.

    $erDirect = Get-AzExpressRoutePort -ResourceGroupName "your_resource_group" -Name "your_direct_port_name"
    $erDirect.Links[0]. MacSecConfig.CknSecretIdentifier = $MacSecCKNSecret.Id
    $erDirect.Links[0]. MacSecConfig.CakSecretIdentifier = $MacSecCAKSecret.Id
    $erDirect.Links[0]. MacSecConfig.Cipher = "GcmAes256"
    $erDirect.Links[1]. MacSecConfig.CknSecretIdentifier = $MacSecCKNSecret.Id
    $erDirect.Links[1]. MacSecConfig.CakSecretIdentifier = $MacSecCAKSecret.Id
    $erDirect.Links[1]. MacSecConfig.Cipher = "GcmAes256"
    $erDirect.identity = $erIdentity
    Set-AzExpressRoutePort -ExpressRoutePort $erDirect
  2. (Optional) If the ports are in Administrative Down state you can run the following commands to bring up the ports.

    $erDirect = Get-AzExpressRoutePort -ResourceGroupName "your_resource_group" -Name "your_direct_port_name"
    $erDirect.Links[0].AdminState = "Enabled"
    $erDirect.Links[1].AdminState = "Enabled"
    Set-AzExpressRoutePort -ExpressRoutePort $erDirect

    MACsec is now enabled on the ExpressRoute Direct ports on Microsoft side. If you haven't configured it on your edge devices, you can proceed to configure them with the same MACsec secrets and cipher.

  3. (Optional) You can enable Secure Channel Identifier (SCI) on the ports.

    $erDirect = Get-AzExpressRoutePort -ResourceGroupName "your_resource_group" -Name "your_direct_port_name"
    $erDirect.Links[0].MacSecConfig.SciState = "Enabled"
    $erDirect.Links[1].MacSecConfig.SciState = "Enabled"
    Set-AzExpressRoutePort -ExpressRoutePort $erDirect

    SCI is now enabled on the ExpressRoute Direct ports.

To disable MACsec

If MACsec is no longer desired on your ExpressRoute Direct instance, you can run the following commands to disable it.

$erDirect = Get-AzExpressRoutePort -ResourceGroupName "your_resource_group" -Name "your_direct_port_name"
$erDirect.Links[0]. MacSecConfig.CknSecretIdentifier = $null
$erDirect.Links[0]. MacSecConfig.CakSecretIdentifier = $null
$erDirect.Links[1]. MacSecConfig.CknSecretIdentifier = $null
$erDirect.Links[1]. MacSecConfig.CakSecretIdentifier = $null
$erDirect.identity = $null
Set-AzExpressRoutePort -ExpressRoutePort $erDirect

MACsec is now disabled on the ExpressRoute Direct ports on the Microsoft side.

Test connectivity

After you configure MACsec (including MACsec key update) on your ExpressRoute Direct ports, check if the BGP sessions of the circuits are up and running. If you don't have any circuit on the ports yet, create one first and set up Azure Private Peering or Microsoft Peering of the circuit. If MACsec gets misconfigured, including MACsec key mismatch, between your network devices and Microsoft's network devices, you won't see ARP resolution at layer 2 or BGP establishment at layer 3. If everything is configured properly, you should see the BGP routes advertised correctly in both directions and your application data flow accordingly over ExpressRoute.

Next steps