You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn about the Azure Stack Hub PKI certificate requirements for Azure Stack Hub integrated systems.
4
4
author: sethmanheim
5
5
ms.topic: article
6
-
ms.date: 06/07/2021
6
+
ms.date: 08/12/2025
7
7
ms.author: sethm
8
-
ms.reviewer: ppacent
9
8
ms.lastreviewed: 06/07/2021
10
9
11
10
# Intent: As an Azure Stack Hub operator, I want to learn about the Azure Stack Hub PKI certificate requirements.
@@ -22,20 +21,23 @@ Azure Stack Hub has a public infrastructure network using externally accessible
22
21
- Optional certificates required when deploying value-add resource providers.
23
22
24
23
> [!NOTE]
25
-
> Azure Stack Hub by default also uses certificates issued from an internal Active Directory-integrated certificate authority (CA) for authentication between the nodes. To validate the certificate, all Azure Stack Hub infrastructure machines trust the root certificate of the internal CA by means of adding that certificate to their local certificate store. There's no pinning or filtering of certificates in Azure Stack Hub. The SAN of each server certificate is validated against the FQDN of the target. The entire chain of trust is also validated, along with the certificate expiration date (standard TLS server authentication without certificate pinning).
24
+
> By default, Azure Stack Hub also uses certificates issued from an internal Active Directory-integrated certificate authority (CA) for authentication between the nodes. To validate the certificate, all Azure Stack Hub infrastructure machines trust the root certificate of the internal CA by adding that certificate to their local certificate store. There's no pinning or filtering of certificates in Azure Stack Hub. The SAN of each server certificate is validated against the FQDN of the target. The entire chain of trust is also validated, along with the certificate expiration date (standard TLS server authentication without certificate pinning).
26
25
27
26
## Certificate requirements
27
+
28
28
The following list describes the general certificate issuance, security, and formatting requirements:
29
29
30
30
- Certificates must be issued from either an internal certificate authority or a public certificate authority. If a public certificate authority is used, it must be included in the base operating system image as part of the Microsoft Trusted Root Authority Program. For the full list, see [List of Participants - Microsoft Trusted Root Program](/security/trusted-root/participants-list).
31
-
- Your Azure Stack Hub infrastructure must have network access to the certificate authority's Certificate Revocation List (CRL) location published in the certificate. This CRL must be an http endpoint. **Note:** for disconnected deployments, certificates issued by a public certificate authority (CA) are not supported, if the CRL endpoint is not accessible. For more details see [Features that are impaired or unavailable in disconnected deployments](/azure-stack/operator/azure-stack-disconnected-deployment#features-that-are-impaired-or-unavailable-in-disconnected-deployments).
31
+
- Your Azure Stack Hub infrastructure must have network access to the certificate authority's Certificate Revocation List (CRL) location published in the certificate. This CRL must be an http endpoint. For disconnected deployments, if the CRL endpoint is not accessible, certificates issued by a public certificate authority (CA) are not supported. For more information, see [Features that are impaired or unavailable in disconnected deployments](azure-stack-disconnected-deployment.md#features-that-are-impaired-or-unavailable-in-disconnected-deployments).
32
+
32
33
::: moniker range="< azs-1903"
33
34
- When rotating certificates in pre-1903 builds, certificates must be either issued from the same internal certificate authority used to sign certificates provided at deployment or any public certificate authority from above.
34
35
::: moniker-end
36
+
35
37
::: moniker range=">= azs-1903"
36
38
- When rotating certificates for builds 1903 and later, certificates can be issued by any enterprise or public certificate authority.
37
39
::: moniker-end
38
-
-The use of self-signed certificates aren't supported.
40
+
-Self-signed certificates aren't supported.
39
41
- For deployment and rotation, you can either use a single certificate covering all name spaces in the certificate's Subject Name and Subject Alternative Name (SAN). Alternatively, you can use individual certificates for each of the namespaces below that the Azure Stack Hub services you plan to utilize require. Both approaches require using wild cards for endpoints where they're required, such as **KeyVault** and **KeyVaultInternal**.
40
42
- The certificate signature algorithm shouldn't be SHA1.
41
43
- The certificate format must be PFX, as both the public and private keys are required for Azure Stack Hub installation. The private key must have the local machine key attribute set.
@@ -44,77 +46,76 @@ The following list describes the general certificate issuance, security, and for
44
46
- The certificate pfx files must have the values "Server Authentication (1.3.6.1.5.5.7.3.1)" and "Client Authentication (1.3.6.1.5.5.7.3.2)" in the "Enhanced Key Usage" field.
45
47
- The certificate's "Issued to:" field must not be the same as its "Issued by:" field.
46
48
- The passwords to all certificate pfx files must be the same at the time of deployment.
47
-
-Password to the certificate pfx has to be a complex password. Make note of this password because you'll use it as a deployment parameter. The password must meet the following password complexity requirements:
48
-
- A minimum length of eight characters.
49
-
- At least three of the following characters: uppercase letter, lowercase letter, numbers from 0-9, special characters, alphabetical character that's not uppercase or lowercase.
49
+
-The password to the certificate pfx must be a complex password. Make a note of this password, because you use it as a deployment parameter. The password must meet the following password complexity requirements:
50
+
- A minimum length of eight characters.
51
+
- At least three of the following characters: uppercase letter, lowercase letter, numbers from 0-9, special characters, alphabetical character that's not uppercase or lowercase.
50
52
- Ensure that the subject names and subject alternative names in the subject alternative name extension (x509v3_config) match. The subject alternative name field lets you specify additional host names (websites, IP addresses, common names) to be protected by a single SSL certificate.
51
53
52
54
> [!NOTE]
53
55
> Self-signed certificates aren't supported.
54
-
> When deploying Azure Stack Hub in disconnected mode it is recommended to use certificates issued by an enterprise certificate authority. This is important because clients accessing Azure Stack Hub endpoints must be able to contact the certificate revocation list (CRL).
56
+
> When deploying Azure Stack Hub in disconnected mode it's recommended that you use certificates issued by an enterprise certificate authority. This is important because clients accessing Azure Stack Hub endpoints must be able to contact the certificate revocation list (CRL).
55
57
56
58
> [!NOTE]
57
-
> The presence of Intermediary Certificate Authorities in a certificate's chain-of-trusts *is* supported.
59
+
> The presence of Intermediary Certificate Authorities in a certificate's chain-of-trusts is supported.
58
60
59
61
## Mandatory certificates
60
62
61
63
The table in this section describes the Azure Stack Hub public endpoint PKI certificates that are required for both Microsoft Entra ID and AD FS Azure Stack Hub deployments. Certificate requirements are grouped by area, and the namespaces used and the certificates that are required for each namespace. The table also describes the folder in which your solution provider copies the different certificates per public endpoint.
62
64
63
-
Certificates with the appropriate DNS names for each Azure Stack Hub public infrastructure endpoint are required. Each endpoint's DNS name is expressed in the format: *<prefix>.<region>.<fqdn>*.
65
+
Certificates with the appropriate DNS names for each Azure Stack Hub public infrastructure endpoint are required. Each endpoint's DNS name is expressed in the format: `<prefix>.<region>.<fqdn>`.
64
66
65
-
For your deployment, the *\<region\>* and *\<fqdn\>* values must match the region and external domain names that you chose for your Azure Stack Hub system. As an example, if the region is *Redmond* and the external domain name is *contoso.com*, the DNS names will have the format *<prefix>.redmond.contoso.com*. The *<prefix>* values are predesignated by Microsoft to describe the endpoint secured by the certificate. In addition, the *<prefix>* values of the external infrastructure endpoints depend on the Azure Stack Hub service that uses the specific endpoint.
67
+
For your deployment, the `<region>` and `<fqdn>` values must match the region and external domain names that you chose for your Azure Stack Hub system. As an example, if the region is **Redmond** and the external domain name is **contoso.com**, the DNS names have the format `<prefix>.redmond.contoso.com`. The `<prefix>` values are reserved by Microsoft to describe the endpoint secured by the certificate. In addition, the `<prefix>` values of the external infrastructure endpoints depend on the Azure Stack Hub service that uses the specific endpoint.
66
68
67
-
For the production environments, we recommend individual certificates are generated for each endpoint and copied into the corresponding directory. For development environments, certificates can be provided as a single wildcard certificate covering all namespaces in the Subject and Subject Alternative Name (SAN) fields copied into all directories. A single certificate covering all endpoints and services is an insecure posture and hence development-only. Remember, both options require you to use wildcard certificates for endpoints like**acs** and Key Vault where they're required.
69
+
For production environments, we recommend that individual certificates are generated for each endpoint and copied into the corresponding directory. For development environments, certificates can be provided as a single wildcard certificate covering all namespaces in the Subject and Subject Alternative Name (SAN) fields copied into all directories. A single certificate covering all endpoints and services is an insecure posture, and therefore intended only for development. Remember, both options require you to use wildcard certificates for endpoints such as**acs** and Key Vault where they're required.
68
70
69
-
> [!Note]
70
-
> During deployment, you must copy certificates to the deployment folder that matches the identity provider you're deploying against (Microsoft Entra ID or AD FS). If you use a single certificate for all endpoints, you must copy that certificate file into each deployment folder as outlined in the following tables. The folder structure is pre-built in the [deployment virtual machine](deployment-networking.md#the-deployment-vm) and can be found at: C:\CloudDeployment\Setup\Certificates.
71
+
> [!NOTE]
72
+
> During deployment, you must copy certificates to the deployment folder that matches the identity provider you're deploying against (Microsoft Entra ID or AD FS). If you use a single certificate for all endpoints, you must copy that certificate file into each deployment folder as outlined in the following tables. The folder structure is pre-built in the [deployment virtual machine](deployment-networking.md#the-deployment-vm) and can be found at**C:\CloudDeployment\Setup\Certificates**.
71
73
72
74
| Deployment folder | Required certificate subject and subject alternative names (SAN) | Scope (per region) | Subdomain namespace |
| Public Extension Host |*.hosting.\<region>.\<fqdn> (Wildcard SSL Certificates) | Public Extension Host| hosting.\<region>.\<fqdn> |
85
-
86
-
If you deploy Azure Stack Hub using the Microsoft Entra deployment mode, you only need to request the certificates listed in previous table. But, if you deploy Azure Stack Hub using the AD FS deployment mode, you must also request the certificates described in the following table:
76
+
| Public portal|`portal.<region>.<fqdn>`| Portals |`<region>.<fqdn>`|
| Public Extension Host |`*.hosting.<region>.<fqdn>` (Wildcard SSL certificates) | Public extension host|`hosting.<region>.<fqdn>`|
87
+
88
+
If you deploy Azure Stack Hub using the Microsoft Entra deployment mode, you only need to request the certificates listed in the previous table. If you deploy Azure Stack Hub using the AD FS deployment mode, you must also request the certificates described in the following table:
87
89
88
90
|Deployment folder|Required certificate subject and subject alternative names (SAN)|Scope (per region)|Subdomain namespace|
> All the certificates listed in this section must have the same password.
96
97
97
98
## Optional PaaS certificates
98
99
99
-
If you're planning to deploy Azure Stack Hub PaaS services (such as SQL, MySQL, App Service, or Event Hubs) after Azure Stack Hub has been deployed and configured, you must request additional certificates to cover the endpoints of the PaaS services.
100
+
If you plan to deploy Azure Stack Hub PaaS services (such as SQL, MySQL, App Service, or Event Hubs) after Azure Stack Hub is deployed and configured, you must request additional certificates to cover the endpoints of the PaaS services.
100
101
101
102
> [!IMPORTANT]
102
103
> The certificates that you use for resource providers must have the same root authority as those used for the global Azure Stack Hub endpoints.
103
104
104
-
The following table describes the endpoints and certificates required for resource providers. You don't need to copy these certificates to the Azure Stack Hub deployment folder. Instead, you provide these certificates during resource provider installation.
105
+
The following table describes the endpoints and certificates required for resource providers. You don't need to copy these certificates to the Azure Stack Hub deployment folder. Instead, you provide these certificates during resource provider installation:
105
106
106
107
|Scope (per region)|Certificate|Required certificate subject and Subject Alternative Names (SANs)|Subdomain namespace|
|SQL, MySQL|SQL and MySQL|`*.dbadapter.<region>.<fqdn>`<br>(Wildcard SSL Certificate)|`dbadapter.<region>.<fqdn>`|
114
115
115
116
<sup>1</sup> Requires one certificate with multiple wildcard subject alternative names. Multiple wildcard SANs on a single certificate might not be supported by all public certificate authorities.
116
117
117
-
<sup>2</sup> A *.appservice.*<region>.<fqdn>* wildcard certificate can't be used in place of these three certificates (api.appservice.*<region>.<fqdn>*, ftp.appservice.*<region>.<fqdn>*, and sso.appservice.*<region>.<fqdn>*. Appservice explicitly requires the use of separate certificates for these endpoints.
118
+
<sup>2</sup> A `*.appservice.<region>.<fqdn>` wildcard certificate can't be used in place of these three certificates (`api.appservice.<region>.<fqdn>`, `ftp.appservice.<region>.<fqdn>`, and `sso.appservice.<region>.<fqdn>`). Appservice explicitly requires the use of separate certificates for these endpoints.
0 commit comments