Prepare Azure Stack Hub PKI certificates for deployment or rotation

The certificate files obtained from your certificate authority (CA) of choice must be imported and exported with properties matching Azure Stack Hub's certificate requirements.

Prepare certificates for deployment with Azure Stack Readiness Checker

Use the Azure Stack Hub Readiness Checker tool to import, package and validate certificates ready for deployment or rotation.

Prerequisites

Your system should meet the following prerequisites before packaging PKI certificates for an Azure Stack Hub deployment:

  • Microsoft Azure Stack Hub Readiness Checker
  • Certificates returned from Certificate Authority in a single directory in .cer format (other configurable formats .cert, .sst or .pfx).
  • Windows 10 or Windows Server 2016 or later
  • Use the same system that generated the Certificate Signing Request (unless you're targeting a certificate prepackaged into PFXs).

Generate certificate signing requests for new deployments

Use these steps to package certificates for new Azure Stack Hub PKI certificates:

  1. Install AzsReadinessChecker from a PowerShell prompt (5.1 or above), by running the following cmdlet:

        Install-Module Microsoft.AzureStack.ReadinessChecker
    
  2. Declare the Path where the certificates reside on disk. For example:

        $Path = "$env:USERPROFILE\Documents\AzureStack"
    
  3. Declare the pfxPassword. For example:

        $pfxPassword = Read-Host -AsSecureString -Prompt "PFX Password"
    
  4. Declare the ExportPath where the resulting PFXs will be exported to. For example:

        $ExportPath = "$env:USERPROFILE\Documents\AzureStack"
    
  5. Convert certificates to Azure Stack Hub Certificates. For example:

        ConvertTo-AzsPFX -Path $Path -pfxPassword $pfxPassword -ExportPath $ExportPath
    
  6. Review the output:

    ConvertTo-AzsPFX v1.2005.1286.272 started.
    
    Stage 1: Scanning Certificates
        Path: C:\Users\[*redacted*]\Documents\AzureStack Filter: CER Certificate count: 11
        adminmanagement_east_azurestack_contoso_com_CertRequest_20200710235648.cer
        adminportal_east_azurestack_contoso_com_CertRequest_20200710235645.cer
        management_east_azurestack_contoso_com_CertRequest_20200710235644.cer
        portal_east_azurestack_contoso_com_CertRequest_20200710235646.cer
        wildcard_adminhosting_east_azurestack_contoso_com_CertRequest_20200710235649.cer
        wildcard_adminvault_east_azurestack_contoso_com_CertRequest_20200710235642.cer
        wildcard_blob_east_azurestack_contoso_com_CertRequest_20200710235653.cer
        wildcard_hosting_east_azurestack_contoso_com_CertRequest_20200710235652.cer
        wildcard_queue_east_azurestack_contoso_com_CertRequest_20200710235654.cer
        wildcard_table_east_azurestack_contoso_com_CertRequest_20200710235650.cer
        wildcard_vault_east_azurestack_contoso_com_CertRequest_20200710235647.cer
    
    Detected ExternalFQDN: east.azurestack.contoso.com
    
    Stage 2: Exporting Certificates
        east.azurestack.contoso.com\Deployment\ARM Admin\ARMAdmin.pfx
        east.azurestack.contoso.com\Deployment\Admin Portal\AdminPortal.pfx
        east.azurestack.contoso.com\Deployment\ARM Public\ARMPublic.pfx
        east.azurestack.contoso.com\Deployment\Public Portal\PublicPortal.pfx
        east.azurestack.contoso.com\Deployment\Admin Extension Host\AdminExtensionHost.pfx
        east.azurestack.contoso.com\Deployment\KeyVaultInternal\KeyVaultInternal.pfx
        east.azurestack.contoso.com\Deployment\ACSBlob\ACSBlob.pfx
        east.azurestack.contoso.com\Deployment\Public Extension Host\PublicExtensionHost.pfx
        east.azurestack.contoso.com\Deployment\ACSQueue\ACSQueue.pfx
        east.azurestack.contoso.com\Deployment\ACSTable\ACSTable.pfx
        east.azurestack.contoso.com\Deployment\KeyVault\KeyVault.pfx
    
    Stage 3: Validating Certificates.
    
    Validating east.azurestack.contoso.com-Deployment-AAD certificates in C:\Users\[*redacted*]\Documents\AzureStack\east.azurestack.contoso.com\Deployment 
    
    Testing: KeyVaultInternal\KeyVaultInternal.pfx
    Thumbprint: E86699****************************4617D6
        PFX Encryption: OK
        Expiry Date: OK
        Signature Algorithm: OK
        DNS Names: OK
        Key Usage: OK
        Key Length: OK
        Parse PFX: OK
        Private Key: OK
        Cert Chain: OK
        Chain Order: OK
        Other Certificates: OK
    Testing: ARM Public\ARMPublic.pfx
        ...
    Log location (contains PII): C:\Users\[*redacted*]\AppData\Local\Temp\AzsReadinessChecker\AzsReadinessChecker.log
    ConvertTo-AzsPFX Completed
    

    Note

    For additional usage use Get-help ConvertTo-AzsPFX -Full for further usage such as disabling validation or filtering for different certificate formats.

    Following a successful validation certificates can be presented for Deployment or Rotation without any additional steps.

Prepare certificates for deployment (manual steps)

Use the following steps to prepare and validate the Azure Stack Hub PKI certificates that will be used for deploying a new Azure Stack Hub environment or for rotating secrets in an existing Azure Stack Hub environment.

Import the certificate

  1. Copy the original certificate versions obtained from your CA of choice into a directory on the deployment host.

    Warning

    Don't copy files that have already been imported, exported, or altered in any way from the files provided directly by the CA.

  2. Right-click on the certificate and select Install Certificate or Install PFX, depending on how the certificate was delivered from your CA.

  3. In the Certificate Import Wizard, select Local Machine as the import location. Select Next. On the following screen, select next again.

    Local machine import location for certificate

  4. Choose Place all certificate in the following store and then select Enterprise Trust as the location. Select OK to close the certificate store selection dialog box and then select Next.

    Configure the certificate store for certificate import

    a. If you're importing a PFX, you'll be presented with an additional dialog. On the Private key protection page, enter the password for your certificate files and then enable the Mark this key as exportable. This allows you to back up or transport your keys at a later time option. Select Next.

    Mark key as exportable

  5. Select Finish to complete the import.

Note

After you import a certificate for Azure Stack Hub, the private key of the certificate is stored as a PKCS 12 file (PFX) on clustered storage.

Export the certificate

Open Certificate Manager MMC console and connect to the Local Machine certificate store.

  1. Open the Microsoft Management Console. To open the console in Windows 10, right click on the Start Menu, select Run, then type mmc and press enter.

  2. Select File > Add/Remove Snap-In, then select Certificates and select Add.

    Add Certificates Snap-in in Microsoft Management Console

  3. Select Computer account, then select Next. Select Local computer and then Finish. Select OK to close the Add/Remove Snap-In page.

    Select account for Add Certificates Snap-in in Microsoft Management Console

  4. Browse to Certificates > Enterprise Trust > Certificate location. Verify that you see your certificate on the right.

  5. From the Certificate Manager Console taskbar, select Actions > All Tasks > Export. Select Next.

    Note

    Depending on how many Azure Stack Hub certificates you have, you may need to complete this process more than once.

  6. Select Yes, Export the Private Key, and then click Next.

  7. In the Export File Format section:

    • Select Include all certificates in the certificate if possible.

    • Select Export all Extended Properties.

    • Select Enable certificate privacy.

    • Click Next.

      Certificate export wizard with selected options

  8. Select Password and provide a password for the certificates. Create a password that meets the following password complexity requirements:

    • A minimum length of eight characters.
    • At least three of the following: uppercase letter, lowercase letter, numbers from 0-9, special characters, alphabetical character that's not uppercase or lowercase.

    Make note of this password. You'll use it as a deployment parameter.

  9. Select Next.

  10. Choose a file name and location for the PFX file to export. Select Next.

  11. Select Finish.

Next steps

Validate PKI certificates