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:
- You understand ExpressRoute Direct provisioning workflows.
- You've created an ExpressRoute Direct port resource.
- If you want to run PowerShell locally, verify that the latest version of Azure PowerShell is installed on your computer.
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. |  |
| Open Cloud Shell in your browser. |  |
| Click the Cloud Shell button on the menu in the upper right of the Azure 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.
Connect-AzAccount
If you have more than one subscription, get a list of your Azure subscriptions.
Get-AzSubscription
Specify the subscription that you want to use.
Select-AzSubscription -SubscriptionName "Name of subscription"
1. Create Azure Key Vault, MACsec secrets, and user identity
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 90If you already have a key vault or a resource group, you can reuse them. However, it is critical that you enable the soft-delete feature on your existing key vault. If soft-delete is not enabled, you can use 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.PropertiesNote
The Key Vault shouldn't be behind a private endpoint because communicate to the ExpressRoute management plane is required.
Create a user identity.
$identity = New-AzUserAssignedIdentity -Name "identity_name" -Location "resource_location" -ResourceGroupName "your_resource_group"If New-AzUserAssignedIdentity is not recognized as a valid PowerShell cmdlet, install the following module (in Administrator mode) and rerun the above command.
Install-Module -Name Az.ManagedServiceIdentityCreate 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 $CKNNote
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).
Assign the GET permission to the user identity.
Set-AzKeyVaultAccessPolicy -VaultName "your_key_vault_name" -PermissionsToSecrets get -ObjectId $identity.PrincipalIdNow this identity can get the secrets, for example CAK and CKN, from the key vault.
Set this user identity to be used by ExpressRoute.
$erIdentity = New-AzExpressRoutePortIdentity -UserAssignedIdentityId $identity.Id
2. 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 on 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.
Note
You can configure both XPN and Non-XPN ciphers:
- GcmAes128
- GcmAes256
- GcmAesXpn128
- GcmAesXpn256
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(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 $erDirectAt this point, MACsec is 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.
(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 $erDirectAt this point, SCI is 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
At this point, MACsec is 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, please create one first and set up Azure Private Peering or Microsoft Peering of the circuit. If MACsec is misconfigured, including MACsec key mismatch, between your network devices and Microsoft's network devices, you won't see ARP resolution at layer 2 and 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
Feedback
Submit and view feedback for