From 7987f057cdf39db8153e49526bb8f1ef78f34061 Mon Sep 17 00:00:00 2001 From: Burak Berk Keskin Date: Wed, 12 Nov 2025 20:41:56 +0300 Subject: [PATCH 1/2] add SAN warnings for SSL certs --- .../configuration/ssl-configuration.md | 7 ++++++ .../ssl-configuration.md | 25 +++++++++++++++++++ .../pre-installation-checklist.md | 2 ++ 3 files changed, 34 insertions(+) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md index 434fb76c7..91e559799 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md @@ -18,6 +18,13 @@ By default, the Helm chart is configured for HTTP without an SSL certificate. If Appcircle must be installed with HTTPS from the initial installation. If you initially installed Appcircle with HTTP, you will need to [uninstall](/self-hosted-appcircle/install-server/helm-chart/uninstallation) it and then reinstall it with HTTPS. ::: +:::warning +Ensure that each [required domain name](/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes#1-domain-name) is included in the Subject Alternative Name (SAN) extension of your SSL certificate, either listed individually or using a wildcard (e.g., `*.appcircle.spacetech.com`). + +- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. + +::: + You have two options for configuring SSL certificates: 1. **Trial Purposes**: Define the SSL certificate directly in the `values.yaml` by following [this section](#define-the-ssl-certificate-in-valuesyaml). diff --git a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md index 9f73be16e..64c6036a5 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md @@ -104,6 +104,14 @@ Refer to [reset configuration](/self-hosted-appcircle/install-server/linux-packa ::: +:::warning + +Ensure that each [required domain name](/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md#configure-the-dns-settings) is included in the Subject Alternative Name (SAN) extension of your SSL certificate, either listed individually or using a wildcard (e.g., `*.appcircle.spacetech.com`). + +- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. + +::: + Set your private key and public certificate to `nginx` environment variables in `global.yaml` as below. ```yaml @@ -426,6 +434,14 @@ storeWeb: The `storeWeb.customDomain.port` must be `443` if the `enabledTls` option is set to `true`. ::: +:::warning + +Ensure that the Enterprise App Store custom domain (`apps.spacetech.com` in our sample scenario) is included in the Subject Alternative Name (SAN) extension of your SSL certificate. + +- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. + +::: + @@ -578,6 +594,15 @@ If you don't have the `testerWeb` section defined in the `global.yaml` file, yo If you have a `testerWeb` section previously defined in the `global.yaml` file for some reason, you should update that section with the `customDomain` settings below instead of adding a new one. ::: +:::warning + +Ensure that the custom Testing Distribution domain (`dist.spacetech.com` in our sample scenario) is included in the Subject Alternative Name (SAN) extension of your SSL certificate. + +- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. + +::: + + Date: Wed, 12 Nov 2025 20:52:26 +0300 Subject: [PATCH 2/2] add sample command to check SAN --- .../configuration/ssl-configuration.md | 2 +- .../ssl-configuration.md | 38 ++++++++++++++----- .../pre-installation-checklist.md | 7 +++- 3 files changed, 35 insertions(+), 12 deletions(-) diff --git a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md index 91e559799..e8b4624dd 100644 --- a/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md +++ b/docs/self-hosted-appcircle/install-server/helm-chart/configuration/ssl-configuration.md @@ -21,7 +21,7 @@ Appcircle must be installed with HTTPS from the initial installation. If you ini :::warning Ensure that each [required domain name](/self-hosted-appcircle/install-server/helm-chart/installation/kubernetes#1-domain-name) is included in the Subject Alternative Name (SAN) extension of your SSL certificate, either listed individually or using a wildcard (e.g., `*.appcircle.spacetech.com`). -- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. +- :warning: **Do not use** wildcard domains in the Common Name (CN). Wildcards must be specified only in the SAN extension as per SSL best practices. ::: diff --git a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md index 64c6036a5..5297757c3 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/configure-server/integrations-and-access/ssl-configuration.md @@ -108,7 +108,13 @@ Refer to [reset configuration](/self-hosted-appcircle/install-server/linux-packa Ensure that each [required domain name](/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md#configure-the-dns-settings) is included in the Subject Alternative Name (SAN) extension of your SSL certificate, either listed individually or using a wildcard (e.g., `*.appcircle.spacetech.com`). -- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. +- :warning: **Do not use** wildcard domains in the Common Name (CN). Wildcards must be specified only in the SAN extension as per SSL best practices. + +- If you saved the SSL certificate as a file, you can check the Subject Alternative Name (SAN) extension of the certificate by running the following command. If the output does not contain the required domain names, you need to update the SSL certificate. + + ```bash + openssl x509 -in appcircle-tls.crt -text -noout | grep -A 1 "X509v3 Subject Alternative Name" + ``` ::: @@ -381,6 +387,20 @@ Let's assume we want to use `apps.spacetech.com` as custom domain for our sample Custom domain HTTPS settings are similar to the main domain conceptually. After enabling HTTPS for the main domain, it won't be hard to enable HTTPS for the Enterprise App Store custom domain. +:::warning + +Ensure that the Enterprise App Store custom domain (`apps.spacetech.com` in our sample scenario) is included in the Subject Alternative Name (SAN) extension of your SSL certificate. + +- :warning: **Do not use** wildcard domains in the Common Name (CN). Wildcards must be specified only in the SAN extension as per SSL best practices. + +- If you saved the SSL certificate as a file, you can check the Subject Alternative Name (SAN) extension of the certificate by running the following command. If the output does not contain the required domain names, you need to update the SSL certificate. + + ```bash + openssl x509 -in appcircle-tls.crt -text -noout | grep -A 1 "X509v3 Subject Alternative Name" + ``` + +::: + Configure the `storeWeb` section in your `global.yaml` as follows: @@ -598,7 +610,13 @@ If you have a `testerWeb` section previously defined in the `global.yaml` file f Ensure that the custom Testing Distribution domain (`dist.spacetech.com` in our sample scenario) is included in the Subject Alternative Name (SAN) extension of your SSL certificate. -- :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. +- :warning: **Do not use** wildcard domains in the Common Name (CN). Wildcards must be specified only in the SAN extension as per SSL best practices. + +- If you saved the SSL certificate as a file, you can check the Subject Alternative Name (SAN) extension of the certificate by running the following command. If the output does not contain the required domain names, you need to update the SSL certificate. + + ```bash + openssl x509 -in appcircle-tls.crt -text -noout | grep -A 1 "X509v3 Subject Alternative Name" + ``` ::: diff --git a/docs/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md b/docs/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md index 0db4ed74b..ec5e43281 100644 --- a/docs/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md +++ b/docs/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md @@ -138,7 +138,12 @@ You can see details in the [DNS Settings](/self-hosted-appcircle/install-server/ - [ ] Obtain the root CA certificate of your company. - [ ] Obtain the intermediate CA certificate of your company if it exists. - [ ] Ensure that each [required domain name](/self-hosted-appcircle/install-server/linux-package/installation/pre-installation-checklist.md#configure-the-dns-settings) is included in the Subject Alternative Name (SAN) extension of your SSL certificate, either listed individually or using a wildcard (e.g., `*.appcircle.spacetech.com`). - - :warning: **Do not use** wildcard domains in the Common Name (CN); wildcards must be specified only in the SAN extension as per SSL best practices. + - :warning: **Do not use** wildcard domains in the Common Name (CN). Wildcards must be specified only in the SAN extension as per SSL best practices. + - If you saved the SSL certificate as a file, you can check the Subject Alternative Name (SAN) extension of the certificate by running the following command. If the output does not contain the required domain names, you need to update the SSL certificate. + + ```bash + openssl x509 -in appcircle-tls.crt -text -noout | grep -A 1 "X509v3 Subject Alternative Name" + ``` ### Obtain the SMTP Settings