• You want to lock down access to your key vault so that only your application or a short list of designated hosts can connect to your key vault
• You have an application running in your Azure virtual network (VNET) and this VNET is completely locked down for all inbound and outbound traffic. Your application still needs to connect to key vault to either fetch secrets or certificates or use cryptographic keys.
• You are using a key vault to store encryption keys used by Storage or Data Lake Store for service side encryption and you want to lock down access to this key vault from public internet.

As usual, we value your input so please take a moment to send us private feedback and/or visit our forum.

• Optional but highly recommended: Enable key vault logging to see detailed access logs. This will help you in diagnostics when firewalls and virtual network rules prevent access to a key vault.
• Enable 'service endpoints for key vault' for target virtual network(s) and subnet(s)
• Set firewalls and virtual network rules for a key vault to restrict access to that key vault from specific virtual network(s), subnet(s) and IPv4 address ranges.
• A maximum 127 VNET rules and 127 IPv4 rules are allowed.

• Visit Azure Portal
• Use existing key vault or create new key vault as necessary.
• Visit the key vault blade for which you want to set firewalls and virtual network rules.
  • Azure Portal dashboard -> All Services -> click on 'Key vaults' under 'Security' section (you need to scroll down) -> Click on the key vault name.
• Click on 'Firewalls and virtual networks'. Note: You'll only see this item listed if you use the above Azure Portal URI.

• Click on 'Selected networks' under 'Allow access from:'

• To add existing virtual networks to firewalls and virtual network rules, click '+ Add existing virtual networks'.
• In the new blade that pops up, select the subscription, virtual network(s), and subnet(s) that you want to allow access to this key vault. If the virtual network(s) and subnet(s) you select do not have service endpoints enabled you'll a message as shown below. Click 'Enable' after confirming that you want to enable service endpoints for the listed the virtual network(s) and subnet(s). It may take up to 15 minutes to take effect.

• You can also add new virtual network(s) and subnet(s) and then enable service endpoints for the newly created virtual network(s) and subnet(s), by clicking '+ Add new virtual network' and following prompts.
• Under 'IP Networks' you can add IPv4 address ranges by typing IPv4 address ranges in CIDR (Classless Inter-domain Routing) notation or individual IP addresses.

• IP network rules are only allowed for public IP addresses. IP address ranges reserved for private networks (as defined in RFC 1918) are not allowed in IP rules. Private networks include addresses that start with *10.**, *172.16.**, and *192.168.**. Note: Only IPv4 addresses are supported at this time.
• If this key vault needs to be accessible by any trusted Microsoft services, click 'Yes' in the 'Exception' section. Following trusted Microsoft services are covered with this option.

• Install Azure CLI 2.0 and Login.
• Install keyvault-preview extension. You must install the keyvault-preview extension to use the VNET Service Endpoints for Key Vault.

az extension add --name keyvault-preview

• List available virtual network rules, if you have not set any rules for this key vault, the list will be empty.

az keyvault network-rule list --resource-group myresourcegroup --name mykeyvault

• Enable Service Endpoint for Key Vault on an existing Virtual Network and subnet

az network vnet subnet update --resource-group "myresourcegroup" --vnet-name "myvnet" --name "mysubnet" --service-endpoints "Microsoft.KeyVault"

• Add a network rule for a virtual network and subnet

subnetid=$(az network vnet subnet show --resource-group "myresourcegroup" --vnet-name "myvnet" --name "mysubnet" --query id --output tsv)
az keyvault network-rule add --resource-group "demo9311" --name "demo9311premium" --subnet $subnetid

• Add IP address range to allow traffic from

az keyvault network-rule add --resource-group "myresourcegroup" --name "mykeyvault" --ip-address "191.10.18.0/24"

• If this key vault needs to be accessible by any trusted services, set 'bypass' to AzureServices

az keyvault update --resource-group "myresourcegroup" --name "mykeyvault" --bypass AzureServices

• Now the final and important step, turn the network rules ON by setting the default action to 'Deny'

az keyvault update --resource-group "myresourcegroup" --name "mekeyvault" --default-action Deny

• Install the latest Azure PowerShell and Login.
• Install preview version of AzureRM.KeyVault module
• List available virtual network rules, if you have not set any rules for this key vault, the list will be empty.

(Get-AzureRmKeyVault -VaultName "mykeyvault").NetworkAcls

• Enable Service Endpoint for Key Vault on an existing Virtual Network and subnet

Get-AzureRmVirtualNetwork -ResourceGroupName "myresourcegroup" -Name "myvnet" | Set-AzureRmVirtualNetworkSubnetConfig -Name "mysubnet" -AddressPrefix "10.1.1.0/24" -ServiceEndpoint "Microsoft.KeyVault" | Set-AzureRmVirtualNetwork

• Add a network rule for a virtual network and subnet

$subnet = Get-AzureRmVirtualNetwork -ResourceGroupName "myresourcegroup" -Name "myvnet" | Get-AzureRmVirtualNetworkSubnetConfig -Name "mysubnet"
Add-AzureRmKeyVaultNetworkRule -VaultName "mykeyvault" -VirtualNetworkResourceId $subnet.Id

• Add IP address range to allow traffic from

Add-AzureRmKeyVaultNetworkRule -VaultName "mykeyvault" -IpAddressRange "16.17.18.0/24"

• If this key vault needs to be accessible by any trusted services, set 'bypass' to AzureServices

Update-AzureRmKeyVaultNetworkRuleSet -VaultName "mykeyvault" -Bypass AzureServices

• Now the final and important step, turn the network rules ON by setting the default action to 'Deny'

Update-AzureRmKeyVaultNetworkRuleSet -VaultName "mykeyvault" -DefaultAction Deny

Note: The relevant key vault access policies must be set to allow the corresponding services to get access to key vault. IMPORTANT: Once firewall rules are in effect, all Key Vault data plane operations can ONLY be performed when caller  requests originate from allowed virtual network(s) or IPV4 address ranges. This also applies to accessing key vault from Azure portal. While a user can browser to a key vault from Azure portal, they may not be able to list keys/secrets/certificates if their client machine is not in the allowed list. This also affects the 'Key Vault Picker' by other Azure services. Users may be able to see list of key vaults but not list keys, if firewall rules prevent their client machine.

• Managed Service Identity (MSI) enabled Azure services that use Key Vault in the context of service side encryption at rest with customer managed key do not work when firewall rules are in effect. E.g. Azure Storage encryption with customer managed key, Azure Data Lake Store encryption with customer managed key, Azure SQL TDE with bring your own key. This limitation will be removed in a future release.
• For App Services only ASE (App Service Environment) instances are supported. This limitation will be addressed in a future release.

• Azure Virtual Network Service Endpoints
• Azure CLI 2.0 keyvault-preview extension documentation
• Azure Key Vault REST API preview Reference Documentation 

• • In Azure CLI you would use az keyvault key backup --file <FileName> --name <NameOfTheKeyStoredInKeyVault> --vault-name <VaultName> The parameters --file, --name and --vault-name are required. --file is the local file path in which to store the key backup --name is the Name of the key stored in Azure Key Vault --vault-name is the Name of the Key Vault the key is stored in For more about this command please read documentationNow to restore the key you would use az keyvault key restore --file <FileName> --vault-name <VaultName> --file is the local backup from which to restore the key --vault-name is the name of the vault you would want to restore to. Similarly the command for Secret backup is az keyvault key backup --file <FileName> --name <NameOfTheKeyStoredInKeyVault> --vault-name <VaultName>
  • In Powershell to Back up a key with an automatically generated file name you would use Example 1: PS C:\Users\username\> Backup-AzureKeyVaultKey -VaultName 'MyKeyVault' -Name 'MyKey' This command retrieves the key named MyKey from the key vault named MyKeyVault and saves a backup of that key to a file that is automatically named for you, and displays the file name.Example 2: Back up a key to a specified file name PS C:\> Backup-AzureKeyVaultKey -VaultName 'MyKeyVault' -Name 'MyKey' -OutputFile 'C:\Backup.blob' This command retrieves the key named MyKey from the key vaultnamed MyKeyVault and saves a backup of that key to a file named Backup.blob. Example 3: Back up a previously retrieved key to a specified file name, overwriting the destination file without prompting. PS C:\> $key = Get-AzureKeyVaultKey -VaultName 'MyKeyVault' -Name 'MyKey' PS C:\> Backup-AzureKeyVaultKey -Key $key -OutputFile 'C:\Backup.blob' -Force This command creates a backup of the key named $key.Name in the vault named $key.VaultName to a file named Backup.blob, silently overwriting the file if it exists already. To learn more about how to back up a certificate using Powershell please take a look at these AzureKeyVaultCertificate For backing up a secret visit - BackupAzureKeyVaultSecret For backing up a Managed Storage Account key visit - BackupManagedStorageAccount
  • If you want to use the REST API then you would use this HTTP command POST {vaultBaseUrl}/keys/{key-name}/backup?api-version=2016-10-01 where the vaultBaseUrl is the full URI of the vault. For example https://myvault.vault.azure.netkey-name is the name of the key and api-version is the Client API version. And to backup a secret you would use POST {vaultBaseUrl}/secrets/{secret-name}/backup?api-version=2016-10-01

• You could also download a backup using Azure Portal

1. Keys and Certificates
2. Key Vault REST API Reference
3. .NET SDK Documentation
4. Java SDK Documentation
5. Python SDK Documentation
6. Node.JS SDK Documentation

• You can create new vaults with soft-delete enabled. You can also turn on soft-delete for existing vaults.
• For vaults with soft-delete enabled, when a vault/key/secret is deleted, it simply goes into a ‘deleted state’ and remains in that state unless user takes an action.
• Two actions are possible:
  • You can ‘recover’ the vault/key/secret. In that case the vault/key/secret will be recovered and will appear exactly as it was before deletion, including all versions, tags and other metadata.
  • You can 'purge' the vault/key/secret, such that it will be permanently deleted with no recovery possible.
• If none of the above action is taken while the vault/key/secret is in deleted state for 90 days, it will be permanently deleted at the end of 90 day window.

($resource = Get-AzureRmResource -ResourceId (Get-AzureRmKeyVault -VaultName ContosoVault).ResourceId).Properties | Add-Member -MemberType NoteProperty -Name enableSoftDelete -Value 'True'
Set-AzureRmResource -resourceid $resource.ResourceId -Properties $resource.Properties

New-AzureRmKeyVault -VaultName ContosoVault -ResourceGroupName ContosoRG -Location westus -EnableSoftDelete

Remove-AzureRmKeyVault -VaultName ContosoVault

PS C:\> Get-AzureRmKeyVault -InRemovedState
Vault Name           : ContosoVault
Location             : westus
Id                   : /subscriptions/xxx/providers/Microsoft.KeyVault/locations/westus/deletedVaults/ContosoVault
Resource ID          : /subscriptions/xxx/resourceGroups/ContosoVault/providers/Microsoft.KeyVault/vaults/ContosoVault
Deletion Date        : 5/9/2017 12:14:14 AM
Scheduled Purge Date : 8/7/2017 12:14:14 AM
Tags                 :

Undo-AzureRmKeyVaultRemoval -VaultName ContosoVault -ResourceGroupName ContosoRG-Location westus

Remove-AzureRmKeyVault -VaultName ContosoVault -InRemovedState -Location westus

Remove-AzureKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey

Get-AzureKeyVaultKey -VaultName ContosoVault -InRemovedState
Vault Name           : ContosoVault
Name                 : ContosoFirstKey
Id                   : https://ContosoVault.vault.azure.net:443/keys/ContosoFirstKey
Deleted Date         : 2/14/2017 8:20:52 PM
Scheduled Purge Date : 5/15/2017 8:20:52 PM
Enabled              : True
Expires              :
Not Before           :
Created              : 2/14/2017 8:16:07 PM
Updated              : 2/14/2017 8:16:07 PM
Tags                 :

Undo-AzureKeyVaultKeyRemoval -VaultName ContosoVault -Name ContosoFirstKey

Remove-AzureKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey -InRemovedState

Set-AzureRmKeyVaultAccessPolicy -VaultName ContosoVault -UserPrincipalName user@contoso.com -PermissionsToKeys get,create,delete,list,update,import,backup,restore,recover,purge

Remove-AzureKeyVaultSecret -VaultName ContosoVault -name SQLPassword

Get-AzureKeyVaultSecret -VaultName ContosoVault -InRemovedState

Undo-AzureKeyVaultSecretRemoval -VaultName ContosoVault -Name SQLPAssword

Remove-AzureKeyVaultSecret -VaultName ContosoVault -InRemovedState -name SQLPassword

What is changing

• CN = Microsoft IT TLS CA 1 [2,4,5]
• OU = Microsoft IT
• O = Microsoft Corporation
• L = Redmond
• S = Washington
• C = US

Will this affect me

1. If you have an application, browser or service that calls one or more Azure services and your application explicitly verifies who issued the TLS certificates for those Azure services. This is called static certificate pinning.
2. If you have set firewall rules to allow outbound calls to only specific CRL download and/or OCSP verification locations.

1. If you have the source code of the application in question then search for thumbprint with this value “‎97 ef f3 02 86 77 89 4b dd 4f 9a c5 3f 78 9b ee 5d f4 ad 86” or “94 8e 16 52 58 62 40 d4 53 28 7a b6 9c ae b8 f2 f4 f0 21 17”. If there is a match your application will be impacted.
2. If you purchased the application, then check with the application vendor.

FAQ

How does Azure Key Vault help?

1. You can now create your certificate and key in your key vault. So you get access logs from the get-go.
2. As with earlier solutions, Azure Key Vault will renew your certificate automatically where possible. It will also notify you, in case there are manual follow-ups required to complete the renewal. This reduces the chances of an outage in your cloud app.
3. There is no restriction on how you use the certificates. You can use them anywhere, even outside Azure.
4. You now have a choice of certificate authorities to get your certificate from. We have started with DigiCert, and GlobalSign, and will add D-Trust shortly. We will continue to add other CAs; please check back again in a few months. This enables our international customers to get certificates from the CA required by their local regulations, and enables enterprises to get certificates from the CA that they already have an account with.
5. Through these certificate authorities, you can get Organization Validation (OV) or Extended Validation (EV) certificates, which provide higher level of trust compared to domain validated certificates that prove just the ownership of the domain.
6. Some organizations, especially enterprises, have a central team that manages domains for the organization, and/or a central billing account with CAs. This team is often separate from the teams that deploy apps with TLS certificates. Both parties must participate in getting a TLS certificate. Our API accommodates this workflow.
7. For higher assurance you can ask Azure Key Vault to generate your key in HSMs. (This choice involves trade-offs. See the FAQ below to decide if this is the right choice for your scenario.)
8. You get to manage all your application secrets – these certificates as well as connection strings, passwords, storage keys etc – in one place, your key vault(s). The first step in reducing mistakes in handling secrets is to know what secrets you have. Centralizing their management helps with that.
9. And finally, because your certificate are in a key vault, you inherit all the other benefits Azure Key Vault offers, covered in earlier posts on this blog -- distribute certificates using the built-in support in Azure VMs, VM scale sets, Web Apps (App Services), Service Fabric clusters/apps; get usage logs, analytics, and alerts via Azure Application Insights and Operations Management Suite etc

1. You have a web app built on the Azure App Services platform. Your app needs an OV/EV TLS server certificate, and you need to keep it refreshed before it expires. You generate your certificate in a key vault and connect your web app with it. Azure Key Vault automatically renews it. The App Services platform automatically picks up new certificates to keep your web app up at all times.
2. You have an app that runs across hundreds of Azure VMs and needs a client authentication certificate. If you embed the certificate into your VM image you not only run the risk of theft at rest, but also every time you need to update the certificate you need to update the image and redeploy hundreds of VMs. Instead you generate your client authentication certificate (perhaps a self-signed certificate) in a single key vault, register it wherever you need to, and then push the certificate into your 500 VMs at runtime.
3. You decide to take your cloud app through SOC / PCI / FedRAMP / ISO certification. The auditor asks you to show evidence that you roll your TLS certificates (and other app secrets) regularly, evidence that you know where that certificate goes, and evidence that you know who has access. You generate all this evidence from your key vault.

• Your cloud app stores data provided by your customers, and that includes certificates. You are on the hook to just store them securely, not to manage them. In this case store them with the rest of your customer data in Azure Storage/SQL or other general purpose storage, with encryption turned on. Let your customer manage the lifecycle of their certificates as they may have their own requirements for secrets management.
• Your cloud app has several thousand users, and your cloud app generates and distributes Wi-Fi certificates to those users’ devices. Such certificates are not part of your app configuration and aren’t “app secrets”. Issue them from a CA designated for that use, and store them in a general purpose store with encryption turned on. Key Vault is for “app secrets”.

Let’s look at one of these use cases end-to-end:

Quick overview of the steps required

1. Create an app with Azure App Service and configure it with a vanity domain.
2. Create a key vault and a certificate object in it.

• Import an existing valid certificate into your key vault.
• Create a self-signed certificate for testing purposes.
• Create a key pair and certificate signing request (CSR) within your key vault and manually take this CSR to any public CA of your choice and get it signed.
• Create a key pair and certificate signing request (CSR) within your key vault, and have Azure Key Vault request a certificate from a supported public CA Few things to note and take an action before selecting the last option:.
  • Create an account with the public CA that supports programmatic enrollment via Azure Key Vault. Skip this step if you already have an account.
  • Submit the domains for which you or your organization will request certificates. The CA validates this ahead of time so that when it is time for you to request a certificate the turnaround is quick (2-3 seconds). Periodically ensure you keep this up-to-date.
  • Your CA bills you per your account plan. The operations you do with Azure Key Vault are billed with your Azure subscription bill.
1. Configure your app to the certificate URI in Azure Key Vault and perform the SSL binding.
2. As long as your information with the public CA is up-to-date renewal requires no action from you. Azure Key Vault fetches the new certificate before your old one expires. The Azure App service platform picks up the renewed certificate automatically and does the SSL re-binding.

Here are more details on each step:

1. Create an app with Azure App Service and configure it with a vanity domain You can create and deploy Web Apps using ARM templates or through UI. The following links describe how to do this:
   • https://azure.microsoft.com/en-us/documentation/services/app-service/web/
   • https://blogs.msdn.microsoft.com/appserviceteam/2016/05/24/deploying-azure-web-app-certificate-through-key-vault/
2. Create a key vault and a certificate in that key vault There are four options available here as mentioned above. Look at the next blog post ‘Getting Started with Azure Key Vault Certificate’ on how to do each of these four options. We will look at the most interesting one which is to request a certificate programmatically from one of the supported public CA’s. In this option you need an account with one of the supported CAs, and you need a credential from that account for the domains for which you will request a certificate. In some organizations a central team manages domains and billing, so we made our flow generic to accommodate this.We will cover a flow with PowerShell; but similar functionality is also available via the cross-platform command line interface or our SDKs and REST API. Go to PowerShell, login to Azure account, set the correct subscription context, and create a key vault. If you have never created a key vault with PowerShell please follow ‘Get started with Azure Key Vault tutorial’.

   #Set this to the name of the key vault that you just created
   $vaultName = "contosoKV"

   Azure Key Vault goes on behalf of the user to enroll for certificates from one of the above issuers. In this process Issuer needs to authenticate the entity requesting the certificate and also authorize to issue the requested certificate. Each Issuer requires different set of information to do so and this needs to be set once in the key vault. If you select DigiCert to be your certificate authority or Issuer to issue certificates then go through these one-time setup steps to configure DigiCert as one of the Issuer in your vault. Note: Customer will need to have an existing account or go here to create one with DigiCert and get domains pre-vetted

   #Create an organization for the issuer
   $orgIdentifier = "111111"   
   $org = New-AzureKeyVaultCertificateOrganizationDetails -Id $orgIdentifier
   
   $apiKey = "111111111" 
   $secureApiKey = ConvertTo-SecureString $apiKey -AsPlainText -Force
   $accountId = "1111111"
   $issuerName = "digiCert01"
    
   #Set the relation with the Public CA (DigiCert) for cert issuance
   Set-AzureKeyVaultCertificateIssuer -VaultName $vaultName -IssuerName $issuerName -IssuerProvider DigiCert -AccountId $accountId -ApiKey $secureApiKey -OrganizationDetails $org
   

   If you select GlobalSign to be your Issuer then go through these one-time setup steps to configure GlobalSign as one of the Issuer in your vault. Note: Customer will need to have an existing account or go here to create one with GlobalSign and get your domains pre-vetted

   #Create an administrator for the issuer (GlobalSign needs to receive Administrator details in the certificate request)
   $firstName = "Patti"
   $lastName = "Fuller"
   $phoneNumber = "4250000000"
   $emailAddress = "patti. fuller@contoso.com"
   $admin = New-AzureKeyVaultCertificateAdministratorDetails -FirstName $firstName -LastName $lastName -PhoneNumber $phoneNumber -EmailAddress $emailAddress
   
   #Create an organization for the issuer
   $org = New-AzureKeyVaultCertificateOrganizationDetails -AdministratorDetails $admin
   
   #Set the relation with the Public CA (GlobalSign) for cert issuance
   $apiKey = "Passw0rd!"
   $secureApiKey = ConvertTo-SecureString $apiKey -AsPlainText -Force
   $accountId = "PAR1000_kvissuer"
   $issuerName = "globalsign01"
   
   Set-AzureKeyVaultCertificateIssuer -VaultName $vaultName -IssuerName $issuerName -IssuerProvider GlobalSign -AccountId $accountId -ApiKey $secureApiKey -OrganizationDetails $org
   

   Create a certificate policy. This is a template that defines what needs to be in the certificate (SubjectName, SAN etc.), when to renew the certificate, and which CA to get it issued from.

   $policy = New-AzureKeyVaultCertificatePolicy -SecretContentType application/x-pkcs12 -SubjectName "CN=contoso.com" -ValidityInMonths 12 -IssuerName $issuerName -RenewAtNumberOfDaysBeforeExpiry 60
   

   Kick off the enrollment process

   $certificateName = "CertTrial" #Name of the certificate object in your key vault; not related to subject name
   Add-AzureKeyVaultCertificate -VaultName $vaultName -CertificateName $certificateName -CertificatePolicy $policy
   

   Since this is a remote call, it may take time. Check the enrollment process status periodically.

   Get-AzureKeyVaultCertificateOperation $vaultName $certificateName

   Status will be completed once certificate enrollment has completed

   Get-AzureKeyVaultCertificateOperation $vaultName $certificateName

   Retrieve the certificate details

   Get-AzureKeyVaultCertificate $vaultName $certificateName

3. Configure your app to use the certificate from your key vault for SSL Once the certificate is enrolled and stored within your key vault, the developer uses the steps on the following page to deploy the certificate to your web app and perform SSL binding. https://azure.microsoft.com/en-us/documentation/templates/201-web-app-certificate-from-key-vault/ Observe that all you can continue to use the same deployment scripts you had earlier with Azure Key Vault. That is because for every Azure Key Vault Certificate, there is a corresponding secret and a key is created. Hence, if you delete the secret and create a certificate with the same name which will create a corresponding secret of the same name. The scripts would work as intended. Certificate endpoint only returns the public portion of the certificate. Secret endpoint provides the access to private key of the certificate. This also enables Contoso to give only the application to have private key access i.e. the secret endpoint and the developer/operators could have access to the public information i.e. certificates endpoint which also just the management endpoint to add and remove certificates.
4. Certificate renewal When it is close to the expiry time of the certificate, Azure Key Vault attempts to renew the certificate from the public CA. It also sends an email to the contacts listed in the certificate object before and after the renewal. The Azure App Services platform periodically polls your key vault to check if there is an updated certificate. If it finds one it reads the new one and rebinds SSL/TLS for your app. Voila! You didn’t have to do anything to roll over the web app to use the renewed certificate.

5. Wrapping Up:

   The certificates feature of Azure Key Vault provides lifetime monitoring of strongly validated SSL certificates along with private key protection in an enterprise environment where domain owner and app developer are different entities. It is a win-win approach from security as well as ease perspective. The Azure Key Vault SDKs in C#, Java, Node.JS as well as Azure CLI and Azure PowerShell have been updated with APIs/commands for the new certificates feature. The new .Net SDK is in preview. The CLI and PowerShell are generally available.

   FAQs

   Where is my favorite CA? We do understand that every enterprise has slightly different requirements which leads them to select a Certificate Authority. Azure Key Vault is working to get the popular CAs added. Drop us a note if you have any specific CA in mind. You can create the CSR (certificate signing request) within Azure Key Vault and then manually take it to their choice of CA, get it signed and then merge it back into your key vault. Azure Key Vault will still monitor the lifetime of your certificates and send an email reminder before expiry of your certificate to avoid disruption of service. Auto-renewal will be skipped until we natively integrate the CA into our workflow. Keep checking our blog as we may announce your favorite CAs in near future. How is this different from Apps Service Certificate support for GoDaddy? In the App Service Certificate scenario the focus is very similar to common industry wide solution of solving enrolling for SSL certificates in minutes based on the assumption that the domain owner and app developer are the same entities and Domain Validated certificates are good enough for the web apps. This release complements it. Our initial focus is on OV and EV SSL certificates. We will merge these into one workflow in the future. Will there be any charge for Key Vault certificates? Please check with your Certificate Authority regarding what they charge for certificates. In addition Azure Key Vault charges a transaction fee as listed here. How soon are certificates issued via Azure Key Vault? The certificates are generally issued within 2 to 3 seconds of the certificate request as long as your information with the CA is up-to-date. The domains which are included in the certificates have to be pre-vetted by the Public CAs which takes 2 to 3days, so we recommend you do this ahead of time. Can I request certificates other than SSL? Azure Key Vault certificate policy can be used to set the relevant EKUs and accordingly create a certificate signing request and get it signed by a CA or self-sign it. Currently the scenario has been mainly optimized for SSL certificates. Can I get certificates for multiple domain names (SAN certificates)? Azure Key Vault certificate policy can be set to include SAN (DNS names) and accordingly send it to the CA. Is the key that backs my certificate bound to HSMs in the Key Vault service? When generating your CSR, you have the option to specify that the key pair be generated as non-exportable and generated inside an HSM. If you do this then you cannot distribute your certificate and private key to your app nodes as illustrated in the end-to-end flow example above. Instead you must use software that can terminate TLS with a remote key in a key vault, such as Brocade’s Virtual Traffic Manager. Your app will be subject to throttling limits on Azure Key Vault. Use this option when isolation of your key is more important than scalability of your application or the latency of your TLS transactions.

   Terminology

   Public CA (Certificate Authority) Certificate authority or certification authority (CA) is a trusted entity that issues digital certificates. Major browsers and devices include the CAs that they trust. Domain Validated Certificate These are SSL/TLS certificates contain domain names which are confirmed via email sent to the domain owner listed in the domain registration database (WHOIS). There are also other ways to confirm the domain ownership. e.g. owner can prove ownership by uploading a file on the website. Either method confirms that the party requesting the certificate is in control of the domain. Organization Validation certificates (OV): CA will rigorously verify the actual organization that is attempting to get the certificate and also that the organization rightfully owns the domain. The organization’s name is also listed in the certificate, giving added trust that both the website and the company are reputable. OV certificates are used by enterprises, governments, and other entities to provide an extra layer of confidence to their online visitors. Extended Validation certificates (EV) Extended validation certificates are the certificates where highest level of validation was conducted by a Certificate Authority to ensure the domains in the certificates are owned by the organization requesting the certificate. It uses the highest standards of assurance to establish the legitimacy of online entities and confirm their authenticity and ownership of the domains in question. High visibility consumer websites use EV certificates. Browsers show trust in these using indicators such as a green bar. Comments are disabled, head over to the Azure Key Vault forum to discuss about this blog

Use this tutorial to help you get started with Azure Key Vault Certificates to store and manage x.509 certificates in Azure. It walks you through the process of using Azure PowerShell to create a certificate self-signed or signed by supported certificate authority, import a certificate and retrieve the certificate with or without private key to use it with an Azure application.

As usual, we value your input so please take a moment to join our advisory board, send us private feedback,and/or visit our forum.

Prerequisites

To complete this tutorial, you must have the following:

• An existing key vault that you have been using.
• A pfx file stored on your hard drive.
• Azure PowerShell, minimum version of 2.1.0.

  To install Azure PowerShell and associate it with your Azure subscription, see How to install and configure Azure PowerShell. If you have already installed Azure PowerShell and do not know the version, from the Azure PowerShell console, type (Get-Module azure -ListAvailable).Version.

This tutorial is designed for Azure PowerShell beginners who understand the basic concepts, such as modules, cmdlets, and sessions but it also assumes that you are familiar with Azure Key Vault and have gone through Get started with Azure Key Vault.

Connect to your subscriptions

Start an Azure PowerShell session and sign in to your Azure account with the following command:

Login-AzureRmAccount

In the pop-up browser window, enter your Azure account user name and password. Azure PowerShell will get all the subscriptions that are associated with this account and by default, uses the first one. If you have multiple subscriptions, you might have to specify a specific one that was used to create your Azure Key Vault. Type the following to see the subscriptions for your account:

Get-AzureRmSubscription

Set-AzureRmContext -SubscriptionId <subscription ID>

For more information about configuring Azure PowerShell, see How to install and configure Azure PowerShell.

Set the key vault

In our first getting started tutorial, our key vault name was ContosoKeyVault, so we'll continue to use that name and store the details into a variable named vaultName and also set the name for certificate created in the end as ContosoFirstCertificate

$vaultName = 'ContosoKeyVault'
$certificateName = 'ContosoFirstCertificate'

Permission to certificates

A newly created Key Vault by default has following permissions set for the creator of the vault:

A vault which was created before the introduction of certificates won’t have any permissions. And in this exercise we are using a previously created key vault and hence, the user would need to set explicit permissions. Type following to give permissions for all operations:

Set-AzureRmKeyVaultAccessPolicy -VaultName $vaultName -UserPrincipalName ‘patti.fuller@contoso.com' -PermissionsToCertificates all

PermissionsToCertificates can also be set selectively by allowing only certain operations on the certificates. The list of operations on which permissions can be set are ‘Get, Delete, List, Create, Import, ManageContacts, GetIssuers, ListIssuers, SetIssuers and ‘all’.

Create certificate

Import an existing certificate to key vault

To import an existing certificate, you must have the certificate in a .PFX or PEM file format. If necessary, export an installed certificate with the private key (.PFX format) and a strong password, and save your certificate to your C:\ drive in a file named clientcert.pfx that you want to upload to Azure Key Vault. Type the following to set the variable securepfxpwd for a password of 123 for the .PFX file:

$securepfxpwd = ConvertTo-SecureString –String '123' –AsPlainText –Force

Then type the following to import the certificate from the .PFX file, which imports the certificate and monitors the lifetime of the certificate in the Key Vault service:

$cer = Import-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName -FilePath 'c:\clientcert.pfx' -Password $securepfxpwd

You can now reference this certificate that you created or uploaded to Azure Key Vault, by using its URI. Use https://ContosoKeyVault.vault.azure.net/certificates/ContosoFirstCertificate to always get the current version, and use https://ContosoKeyVault.vault.azure.net/certificates/ContosoFirstCertificate/24bb21dacfad4f178e3d00e9dd54c034 to get this specific version. If you want to retrieve the pfx back i.e. the private key of the certificate then you use https://ContosoKeyVault.vault.azure.net/secrets/ContosoFirstCertificate to get the current version and use https://ContosoKeyVault.vault.azure.net/secrets/ContosoFirstCertificate/24bb21dacfad4f178e3d00e9dd54c034

Create a self-signed certificate in key vault

$policy = New-AzureKeyVaultCertificatePolicy   -SubjectName "CN=www.contoso.com"   -IssuerName Self   -ValidityInMonths 12

Add-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName -CertificatePolicy $policy 

Enroll programmatically from Public CA (Certificate Authority)

Azure Key Vault supports enrollment of certificates from Public CA such as DigiCert, and GlobalSign. Azure Key Vault goes on behalf of the user to enroll for certificates from one of the above issuers. In this process Issuer needs to authenticate the entity requesting the certificate and also authorize to receive the requested certificate. Each Issuer requires different set of information to do so and this needs to be set once in the Key Vault.

#Create an organization for the issuer
$orgIdentifier = "111111"   
$org = New-AzureKeyVaultCertificateOrganizationDetails -Id $orgIdentifier

$apiKey = "111111111" 
$secureApiKey = ConvertTo-SecureString $apiKey -AsPlainText -Force
$accountId = "1111111"
$issuerName = "digiCert01"
 
#Set the relation with the Public CA (DigiCert) for cert issuance
Set-AzureKeyVaultCertificateIssuer -VaultName $vaultName -IssuerName $issuerName -IssuerProvider DigiCert -AccountId $accountId -ApiKey $secureApiKey -OrganizationDetails $org

#Create an administrator for the issuer (GlobalSign needs to receive Administrator details in the certificate request)
$firstName = "Patti"
$lastName = "Fuller"
$phoneNumber = "4250000000"
$emailAddress = "patti. fuller@contoso.com"
$admin = New-AzureKeyVaultCertificateAdministratorDetails -FirstName $firstName -LastName $lastName -PhoneNumber $phoneNumber -EmailAddress $emailAddress

#Create an organization for the issuer
$org = New-AzureKeyVaultCertificateOrganizationDetails -AdministratorDetails $admin

#Set the relation with the Public CA (GlobalSign) for cert issuance
$apiKey = "Passw0rd!"
$secureApiKey = ConvertTo-SecureString $apiKey -AsPlainText -Force
$accountId = "PAR1000_kvissuer"
$issuerName = "globalsign01"

Set-AzureKeyVaultCertificateIssuer -VaultName $vaultName -IssuerName $issuerName -IssuerProvider GlobalSign -AccountId $accountId -ApiKey $secureApiKey -OrganizationDetails $org

$policy = New-AzureKeyVaultCertificatePolicy -SecretContentType application/x-pkcs12 -SubjectName "CN=contoso.com" -ValidityInMonths 12 -IssuerName $issuerName -RenewAtNumberOfDaysBeforeExpiry 60

Add-AzureKeyVaultCertificate -VaultName $vaultName -CertificateName $certificateName -CertificatePolicy $policy

Get-AzureKeyVaultCertificateOperation -VaultName $vaultName -Name $certificateName

Get-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName

Create a certificate manually and get signed by a CA

Azure Key Vault supports to create the certificate signing request with private-public key pair and get it signed by any Certificate Authority of your choice. It could be internal enterprise CA or external public CA.

First create the certificate policy. Key Vault will not enroll or renew the certificate from the Issuer on behalf of the user as CA chosen in this scenario is not a supported one and hence the IssuerName is set to Unknown.

$manualPolicy = New-AzureKeyVaultCertificatePolicy -SubjectName "CN=www.contosoHRApp.com" -ValidityInMonths 1  -IssuerName Unknown

$certificateOperation = Add-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName -CertificatePolicy $manualPolicy
$certificateOperation.CertificateSigningRequest

The $certificateOperation.CertificateSigningRequest is the base4 encoded certificate signing request for the certificate. You can take this blob and dump into Issuer’s certificate request website or use tools such as certreq or openssl to get the certificate request signed and complete the process of generating a certificate.

After the certificate request has been signed by the Issuer, you can bring back the signed certificate usually a file with .cer extension and merge it with the initial private-public key created in Azure Key Vault

Import-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName -FilePath C:\test\OutputCertificateFile.cer

Retrieve pfx file & add password back

A typical scenario is that the application would need to pull the pfx of the certificate to the machine where it is going to consume the certificate. Here is an example on how an application can retrieve the pfx from Azure Key Vault to consume it.

$secretName = "TestCert"
$kvSecret = Get-AzureKeyVaultSecret -VaultName $vaultName -Name $secretName
$kvSecretBytes = [System.Convert]::FromBase64String($kvSecret.SecretValueText)
$certCollection = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2Collection
$certCollection.Import($kvSecretBytes,$null,[System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable)
 

#Get the file created
$password = '******'
$protectedCertificateBytes = $certCollection.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Pkcs12, $password)
$pfxPath = [Environment]::GetFolderPath("Desktop") + "\MyCert.pfx"
[System.IO.File]::WriteAllBytes($pfxPath, $protectedCertificateBytes)

$cert = Get-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName
$filePath = [Environment]::GetFolderPath("Desktop") + "\MyCert.cer"
$certBytes = $cert.Certificate.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)
[System.IO.File]::WriteAllBytes($filePath, $certBytes)

Listing all the certificates from the management endpoint

For management purposes, you would want to know the certificates in your key vault and related information about it. You would retrieve these information by running following queries as below:

Get-AzureKeyVaultCertificate –VaultName $vaultName 

Renewal of certificates

Azure Key Vault certificates are auto renewed as per the configured certificate policy. Certificate policy is set to either say how many days before expiry do you want to renew the certificate or at what percentage of the lifetime of the certificate. And the policy also needs to have the Issuer value set to a supported Certificate Authority. In case where Certificate Authority needs authorization and authentication details then those should be set while adding the Issuer to the key vault.

Auto-renewal of certificates can fail due to misconfigured values or it can fail due to lack of funds and at times lack of incomplete vetting of domains. In any of the cases the Azure Key Vault Certificate Contact gets notified with the error message. You can choose to rectify the misconfigured values or add the required funds to your contract so that Azure Key Vault can go ahead and re-attempt the renewal. There will be few instances where Azure key Vault will notify the customer that it is better to manually enroll for the certificate mainly when it is very close to expiry. In such cases, you should go through and add a certificate using one of the above options.

Other Azure PowerShell Cmdlets

Few other commands that you might find useful for managing Azure Key Vault Certificate are:

• Add-AzureKeyVaultCertificateContact -VaultName $vaultName -EmailAddress "patti.fuller@contoso.com” The Add-AzureKeyVaultCertificateContact cmdlet adds a contact to an Azure Key Vault for certificate notifications. The contact receives updates about events such as certificate close to expiry, certificate renewed, and so on. These events are determined by the certificate policy.
• Stop-AzureKeyVaultCertificateOperation -VaultName $vaultName -Name $certificateName –Force This cmdlet cancels the certificate operation in process on the $certificateName object.
• Remove-AzureKeyVaultCertificate -VaultName $vaultName -Name $certificateName Example how to remove a specific certificate.

Next steps

As usual, we value your input so please take a moment to join our advisory board, send us private feedback,and/or visit our forum.

Note: Native application support for Key Vault is available in all public Azure regions. Soon it will also be available in Azure Government, Azure China and Azure Germany.

Registering native client application with Azure Active Directory

Note: If you have not created a new Key Vault in recent months, you may not see the 'Azure Key Vault (AzureKeyVault)' listed as shown. If you encounter such scenario, simply create a new key vault in your subscription, and return to this step. Creation of a new key vault will trigger registration of Azure Key Vault service in your tenant and then it will show up in the list as shown.

/// Get clientID and clientRedirectURI from app.config
var clientId = ConfigurationManager.AppSettings["AuthClientId"];
var clientRedirectURI = ConfigurationManager.AppSettings["AuthClientRedirectURI"];
:
:
/// Get AAD token
var context = new AuthenticationContext(authority, TokenCache.DefaultShared);
var result = await context.AcquireTokenAsync(resource, clientId, new Uri(clientRedirectURI), new PlatformParameters(PromptBehavior.Always));

return result.AccessToken;

As usual, we value your input so please take a moment to join our advisory board, send us private feedback,and/or visit our forum.

• Embedded in the VM image, which means you have to rebuild the image when you update your certificates
• bundled with the application package that gets deployed when the VM is created, which means those certificates also end up in some source code control system, and are accessible by a lot more people
• some script running at startup provisions it by accessing it from a storage account, which means you still need to store the credentials to this storage account with the script

• You need a certificate in .PFX format (See Note 1)
• Create a Key Vault (either using template, or use the simple script below)
• Make sure you have turned on the EnabledForDeployment switch
• Upload the certificate as a secret (see the sample script)
• Now grab the template, provide all the parameter values and then deploy the template

Deploying VMs

$vaultName = "contosovault"
$resourceGroup = "contosovaultrg"
$location = "eastus"
$secretName = "servicecert"
$certPassword = "abcd1234"
$fileName = "certforvm.pfx"
# =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
$fileContentBytes = Get-Content $fileName -Encoding Byte
$fileContentEncoded = [System.Convert]::ToBase64String($fileContentBytes)

$jsonObject = @"
{
  "data": "$fileContentEncoded",
  "dataType" :"pfx",
  "password": "$certPassword"
}
"@

$jsonObjectBytes = [System.Text.Encoding]::UTF8.GetBytes($jsonObject)
$jsonEncoded = [System.Convert]::ToBase64String($jsonObjectBytes)

New-AzureRmResourceGroup -Name $resourceGroup -Location $location
New-AzureRmKeyVault -VaultName $vaultName -ResourceGroupName $resourceGroup -Location $location -sku standard -EnabledForDeployment

$secret = ConvertTo-SecureString -String $jsonEncoded -AsPlainText –Force
Set-AzureKeyVaultSecret -VaultName "contosovault" -Name "servicecert" -SecretValue $secret

ResourceGroupName : contosovaultrg
Location          : eastus
ProvisioningState : Succeeded
Tags              :
ResourceId        : /subscriptions/4b2eb912-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/contosovaultrg

Vault Name                       : contosovault
Resource Group Name              : contosovaultrg
Location                         : eastus
Resource ID                      : /subscriptions/4b2eb912-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/contosovaultrg/providers/Microsoft.KeyVault/vaults/contosovault
Vault URI                        : https://contosovault.vault.azure.net
Tenant ID                        : 72f988bf-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SKU                              : standard
Enabled For Deployment?          : True
Enabled For Template Deployment? : False
Enabled For Disk Encryption?     : False
Access Policies                  :
                                   Tenant ID                :   72f988bf-xxxx-xxxx-xxxx-xxxxxxxxxxxx
                                   Object ID                :   50be469a-d7eb-4b26-a2d4-b092cebf0c80
                                   Application ID           :
                                   Display Name             :   Derick Developer (derick@contoso.com)
                                   Permissions to Keys      :   get, create, delete, list, update, import, backup,
                                   restore
                                   Permissions to Secrets   :   all


Tags                             :

Vault Name   : contosovault
Name         : servicecert
Version      : 359804b000ee42febab8a0bb030e200e
Id           : https://contosovault.vault.azure.net:443/secrets/servicecert/359804b000ee42febab8a0bb030e200e
Enabled      : True
Expires      :
Not Before   :
Created      : 9/14/2016 7:39:42 PM
Updated      : 9/14/2016 7:39:42 PM
Content Type :
Tags         :

Updating certificates

$subId = (Get-AzureRmContext).Subscription.SubscriptionId
$vm = Get-AzureRmVM -ResourceGroupName contosovaultrg -Name contosovm
$SourceVaultId = (Get-AzureRmKeyVault -VaultName contosovault).ResourceId
$certStore = "My";
$certUrl = (Get-AzureKeyVaultSecret -VaultName contosovault -Name servicecert).Id;
$vm = Add-AzureRmVMSecret -VM $vm -SourceVaultId $SourceVaultId -CertificateStore $certStore -CertificateUrl $certUrl;
Update-AzureRmVM -ResourceGroupName contosovaultrg -VM $vm

Retiring certificates

Set-AzureKeyVaultSecretAttribute -VaultName contosovault -Name servicecert -Version e3391a126b65414f93f6f9806743a1f7 -Enable 0

Conclusion

• With this new scheme, the certificate can be kept separate from the VM image or the application payload. So we have removed one point of exposure.
• The certificate can also be renewed and uploaded to the Key Vault without having to re-build the VM image or the application deployment package. The application still needs to be supplied with the new URI for this new certificate version though.
• By separating the certificate from the VM or the application payload, we have now reduced the number of personnel that will have direct access to the certificate.
• As an added benefit, you now have one convenient place in key vault to manage all your certificates, including the all the versions that were deployed over time.

Notes

$certificateName = "certforvm"
$thumbprint = (New-SelfSignedCertificate -DnsName $certificateName -CertStoreLocation Cert:\CurrentUser\My -KeySpec KeyExchange).Thumbprint
$cert = (Get-ChildItem -Path cert:\CurrentUser\My\$thumbprint)
$password = Read-Host -Prompt "Please enter the certificate password." -AsSecureString
Export-PfxCertificate -Cert $cert -FilePath ".\$certificateName.pfx" -Password $password

As usual, we value your input so please take a moment to join our advisory board, send us private feedback,and/or visit our forum.