Update RDS certificates template

Azure Public Test Date Azure Public Test Result

Azure US Gov Last Test Date Azure US Gov Last Test Result

Best Practice Check Cred Scan Check

Deploy To Azure Deploy To Azure US Gov Visualize

This Template allows you configure certificates in an RDS deployment. Remote Desktop Services require certificaties for server authentication, single sign-on (SSO), and to secure RDP connections. For a good overview of certificates use in RDS see Configuring RDS 2012 Certificates and SSO and How to Create a (Mostly) Seamless Logon Experience For Your Remote Desktop Services Environment by RDS MVP Toby Phipps.

The Template makes use of a single SSL certificate. The certificate's Subject Name must match external DNS name of RD Gateway server in the deployment. The certificate with the private key (in .PFX format) must be stored in Azure Key Vault. For information on managing certificates with Azure Key Vault see: Get started with Azure Key Vault certificates and Manage certificates via Azure Key Vault.


  1. Template is intended to run against an existing RDS deployment. The deployment can be created using one of RDS QuickStart templates (Basic RDS Deployment Template, or RDS Deployment using existing VNET and AD, etc.).

  2. A certificate with the private key needs to be created (or acquired from CA) and imported to Azure Key Vault in tenant's subscription (see Get started with Azure Key Vault). Certificate's Subject Name should match external DNS name of the RDS Gateway server.

    For example, to import an existing certificate stored as a .pfx file on your local hard drive run the following PowerShell:

     $vaultName = "myVault"
     $certNameInVault = "certificate"    # cert name in vault, has to be '^[0-9a-zA-Z-]+$' pattern (digits, letters or dashes only, no spaces)
     $pfxFilePath = "c:\certificate.pfx"
     $password = "B@kedPotat0"           # password that was used to secure the pfx file at the time of export
     Import-AzureKeyVaultCertificate -vaultname $vaultName -name $certNameInVault -filepath $pfxFilePath -password ($password | convertto-securestring -asplaintext -force)

    Mark down 1) key vault name, and 2) certificate name in vault from this step - these will need to be supplied as input parameters to the Template.

  3. A Service Principal account needs to be created with permissions to access certificates in the Key Vault (see Use Azure PowerShell to create a service principal to access resources).

    Sample powershell (alternatively you see Scripts\New-ServicePrincipal.ps1):

     $appPassword = "R@bberDuck"
     $uri = "https://www.contoso.com/script"   #  a valid formatted URL, not validated for single-tenant deployments
     $vaultName = "myVault"                    #  same key vault name as in step #1 above
     $app = New-AzureRmADApplication -DisplayName "script" -HomePage $uri -IdentifierUris $uri -password $appPassword
     $sp = New-AzureRmADServicePrincipal -ApplicationId $app.ApplicationId
     Set-AzureRmKeyVaultAccessPolicy -vaultname $vaultName -serviceprincipalname $sp.ApplicationId -permissionstosecrets get

    Note: Certificates stored in Key Vault as secrets with content type 'application/x-pkcs12', this is why Set-AzureRmKeyVaultAccessPolivy cmdlet grants -PremissionsToSecrets (rather than -PermissionsToCertificates).

    You will need 1) application id ($app.ApplicationId), and 2) the password from above step supplied as input parameters to the Template. You will also need your tenant Id. To get tenant Id run the following powershell:

     $tenantId = (Get-AzureRmSubscription).TenantId | select -Unique

Running the Template

Template applies same certificate to all 4 roles in the deployment: { RDGateway | RDWebAccess | RDRedirector | RDPublishing }.

Template performs the following steps:

  • downloads certificate from the key vault using Service Principal credentials;
  • invokes Set-RDCertificate cmdlet to apply the certificate for each of the roles;
  • calls Set-RDClientAccessName to update Client Access Name on RD Connection Broker to match the certificate.

Tags: Microsoft.Compute/virtualMachines/extensions, CustomScriptExtension