(#1057) Add connection string info for CCM 0.13.0

vexx32 · vexx32 · commit c9be14567137 · 2024-09-19T11:40:53.000-04:00
Added a notice to the Database/Service/Web setup pages for CCM informing
users about the change to CCM's connection strings, with information on
what to do if they want a _completely_ secure connection to the SQL
Server instance.
diff --git a/src/components/docs/CentralManagementSecureConnectionStrings.mdx b/src/components/docs/CentralManagementSecureConnectionStrings.mdx
@@ -0,0 +1,14 @@
+---
+
+---
+
+import Callout from '@choco/components/Callout.astro';
+
+<Callout type="warning">
+    As of Chocolatey Central Management v0.13.0, the SQL connection mode has changed to secure-by-default. By default, all connection strings will assume `Encrypt=true;` and attempt a connection to the SQL Server over SSL. If you wish to disable this, you must pass a complete connection string to the `/ConnectionString` package parameter that contains an explicit `Encrypt=false;` parameter.
+
+    To accommodate this new default, the package installation will automatically add the `TrustServerCertificate=True` parameter to the connection string it constructs or receives if the initial connection to the SQL server fails without it.
+
+    If you would like to ensure a completely secure SQL connection, you must [install a trusted SSL Certificate on the SQL Server instance](https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/manage-certificates?view=sql-server-ver16) before installing, upgrading, or reinstalling Chocolatey Central Management packages.
+    If you have already installed v0.13.0 or later versions of Chocolatey Central Management, you will need to explicitly pass the SQL connection package parameters when upgrading or reinstalling in order to ensure the connection is established in a fully secure mode.
+</Callout>
diff --git a/src/content/docs/en-us/central-management/setup/database.mdx b/src/content/docs/en-us/central-management/setup/database.mdx
@@ -10,6 +10,7 @@ import Xref from '@components/Xref.astro';
 import TabsPane from '@choco/components/tabs/TabsPane.astro';
 import TabsPaneContainer from '@choco/components/tabs/TabsPaneContainer.astro';
 import TabsTabContainer from '@choco/components/tabs/TabsTabContainer.astro';
+import CentralManagementSecureConnectionStrings from '@components/docs/CentralManagementSecureConnectionStrings.mdx';
 
 At the end of this, we should have a fully ready to go SQL Server:
 
@@ -165,7 +166,7 @@ The Chocolatey Central Management database package will add or update a database
 
 ### Package Parameters
 
-* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. Defaults to default or explicit values for `/SqlServiceInstance` and `/Database`, along with Integrated Security (`Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True;`). The account should have `db_owner` access to the database ([database owner](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles)).
+* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. By default, this value is constructed from the default or explicit values for `/SqlServiceInstance` and `/Database`, and uses Integrated Security (with all default values, this value will look like the following: `Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;`). The account should have [`db_owner`](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles) access to the database.
 * `/SqlServerInstance:` - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with `/ConnectionString`. Uses `/Database` (below) to build a connection string. Defaults to `<LOCAL COMPUTER FQDN NAME>`.
 * `/Database:` - Name of the SQL Server database to use. Alternative to passing full connection string with `/ConnectionString`. Uses `/SqlServerInstance` (above) to build a connection string. Defaults to `ChocolateyManagement`.
 * `/SkipDatabasePermissionCheck` - By default, a check will be completed to ensure that the installing user has access to create a new database, based on the provided/computed connection string. If this check isn't required, for example, the database has already been created or permissions will error, this step can be skipped using this parameter. Available with CCM v0.2.0+.
@@ -176,6 +177,8 @@ The Chocolatey Central Management database package will add or update a database
 
 ### Database Authentication Scenarios
 
+<CentralManagementSecureConnectionStrings />
+
 * <Xref title="Scenario 1 - Windows Authentication to Local SQL Server" value="ccm-database" anchor="scenario-one" />
 * <Xref title="Scenario 2 - Active Directory Authentication to Remote SQL Server" value="ccm-database" anchor="scenario-two" />
 * <Xref title="Scenario 3 - SQL Server Authentication to Local SQL Server" value="ccm-database" anchor="scenario-three" />
@@ -241,9 +244,9 @@ export const tabs1 = [
         </Callout>
 
         <Callout type="warning">
-            **Installs**: Please ensure the user running the package installation is able to create databases unless you also pass `/SkipDatabasePermissionCheck` (in that case you simply need `db_owner` to the database being managed if it was pre-created).
-        
-            **Upgrades**: Please ensure the user running the package installation has been granted `db_owner` access to an existing database.
+            **Installation**: Please either ensure the user running the package installation is able to create databases or pass `/SkipDatabasePermissionCheck`, if you have `db_owner` permission to the pre-created database.
+
+            **Upgrade**: Please ensure the user running the package installation has been granted `db_owner` access to the existing database.
         </Callout>
     </TabsPane>
     <TabsPane content={tabs1[2]}>
@@ -291,9 +294,9 @@ export const tabs1 = [
         </Callout>
 
         <Callout type="warning">
-            **Installs**: Please ensure the login credentials provided are able to create databases unless you also pass `/SkipDatabasePermissionCheck` (in that case you simply need `db_owner` to the database being managed if it was pre-created).
-        
-            **Upgrades**: Please ensure the login credentials provided have been given `db_owner` access to an existing database.
+            **Installation**: Please either ensure the user running the package installation is able to create databases or pass `/SkipDatabasePermissionCheck`, if you have `db_owner` permission to the pre-created database.
+
+            **Upgrade**: Please ensure the user running the package installation has been granted `db_owner` access to the existing database.
         </Callout>
     </TabsPane>
 </TabsPaneContainer>
@@ -419,12 +422,12 @@ Chocolatey Central Management has specific compatibility requirements with quite
 
 ### What is the minimum required configuration for the appsettings.json file?
 
-As of Chocolatey Central Management v0.6.2, the default settings in the `appsettings.json` for the database package are:
+As of Chocolatey Central Management v0.13.0, the default settings in the `appsettings.json` for the database package are:
 
 ```json
 {
   "ConnectionStrings": {
-    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   }
 }
 ```
diff --git a/src/content/docs/en-us/central-management/setup/service.mdx b/src/content/docs/en-us/central-management/setup/service.mdx
@@ -10,6 +10,7 @@ import Xref from '@components/Xref.astro';
 import TabsPane from '@choco/components/tabs/TabsPane.astro';
 import TabsPaneContainer from '@choco/components/tabs/TabsPaneContainer.astro';
 import TabsTabContainer from '@choco/components/tabs/TabsTabContainer.astro';
+import CentralManagementSecureConnectionStrings from '@components/docs/CentralManagementSecureConnectionStrings.mdx';
 
 This is the service that the agents (`chocolatey-agent`) communicates with. You could install one or more of these depending on the size of your environment (not multiple on one machine though). The FQDN and certificate used determine what the URL will be for the agents to check into Chocolatey Central Management.
 
@@ -72,7 +73,7 @@ Note items with "`:`" mean a value should be provided. Items without are simply
 * `/PortNumber:` - The port the Chocolatey Management Service will listen on. This will automatically create a rule to open the firewall on the port specified. Defaults to `24020`.
 * `/CertificateDnsName:` - The DNS name of the self-signed certificate that is generated if no existing certificate thumbprint is provided using the `/CertificateThumbprint` parameter (below). Defaults to `<LOCAL COMPUTER FQDN NAME>`.
 * `/CertificateThumbprint:` - Provide the thumbprint of an existing certificate (already installed in `LocalMachine\TrustedPeople` certificate store) to use for secure communication with clients. Defaults to a new self-signed SSL certificate on first installation / reuses existing on upgrades.
-* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. Defaults to default or explicit values for `/SqlServiceInstance` and `/Database`, along with Integrated Security (`Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True;`). The account should have `db_datareader`/`db_datawriter` access to the database ([data reader / data writer](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles)).
+* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. By default, this value is constructed from the default or explicit values for `/SqlServiceInstance` and `/Database`, and uses Integrated Security (with all default values, this value will look like the following: `Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;`). The account should have [`db_datareader`/`db_datawriter`](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles) access to the database.
 * `/SqlServerInstance:` - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with `/ConnectionString`. Uses `/Database` (below) to build a connection string. Defaults to `<LOCAL COMPUTER FQDN NAME>`.
 * `/Database:` - Name of the SQL Server database to use. Alternative to passing full connection string with `/ConnectionString`. Uses `/SqlServerInstance` (above) to build a connection string. Defaults to `ChocolateyManagement`.
 
@@ -128,6 +129,8 @@ When Chocolatey manages the password for a local Administrator, it creates a ver
 
 ### Database Authentication Scenarios
 
+<CentralManagementSecureConnectionStrings />
+
 * <Xref title="Scenario 1 - Windows Authentication to Local SQL Server" value="ccm-service" anchor="scenario-one" />
 * <Xref title="Scenario 2 - Active Directory Authentication to Remote SQL Server" value="ccm-service" anchor="scenario-two" />
 * <Xref title="Scenario 3 - SQL Server Authentication to Local SQL Server" value="ccm-service" anchor="scenario-three" />
@@ -252,12 +255,12 @@ This situation can occur with any version of Chocolatey Central Management up to
 
 ### What is the minimum required configuration for the `appsettings.json` file?
 
-As of Chocolatey Central Management v0.6.2, the default configuration values in the `appsettings.json` for the Chocolatey Central Management service are:
+As of Chocolatey Central Management v0.13.0, the default configuration values in the `appsettings.json` for the Chocolatey Central Management service are:
 
 ```json
 {
   "ConnectionStrings": {
-    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   },
   "CertificateThumbprint": "<THUMBPRINT_OF_CERTIFICATE_FOUND_DURING_INSTALLATION>"
 }
@@ -412,7 +415,7 @@ It depends. You can simply go to the `appsettings.json` file and adjust the conn
 ```json
 {
   "ConnectionStrings": {
-        "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+        "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   }
 }
 ```
@@ -468,12 +471,13 @@ You may also receive a differently-worded error if the certificate used by the C
 Starting in Chocolatey Central Management v0.6.2, the Chocolatey Central Management Service package will attempt to select an appropriate certificate during installation, and store the thumbprint in the `appsettings.json` file.
 You can also specify the thumbprint for the certificate to use as the `/CertificateThumbprint` package parameter during installation or upgrade.
 
-If you need to change the certificate you're using after installation, you can modify the entry in the `appsettings.json` file for the Chocolatey Central Management service, shown below.
+If you need to change the certificate you're using after installation, you can modify the entry in the `appsettings.json` file for the Chocolatey Central Management service.
+Below is a sample of what the `appsettings.json` file looks like by default as of Chocolatey Central Management v0.13.0.
 
 ```json
 {
   "ConnectionStrings": {
-    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   },
   "CertificateThumbprint": "<THUMBPRINT_OF_CERTIFICATE_FOUND_DURING_INSTALLATION>"
 }
diff --git a/src/content/docs/en-us/central-management/setup/website.mdx b/src/content/docs/en-us/central-management/setup/website.mdx
@@ -11,6 +11,7 @@ import IisWsusChocolatey from '@components/docs/IisWsusChocolatey.mdx';
 import TabsPane from '@choco/components/tabs/TabsPane.astro';
 import TabsPaneContainer from '@choco/components/tabs/TabsPaneContainer.astro';
 import TabsTabContainer from '@choco/components/tabs/TabsTabContainer.astro';
+import CentralManagementSecureConnectionStrings from '@components/docs/CentralManagementSecureConnectionStrings.mdx';
 
 This is the Chocolatey Central Management website that gives an API and a web layer to centrally manage information about your environment and manage endpoints with deployment tasks.
 
@@ -59,7 +60,7 @@ Note items with "`:`" mean a value should be provided. Items without are simply
     </Callout>
 * `/Password:` - Password for the user. Defaults to a Windows autogenerated secure password for the IIS AppPool.
 * `/EnterPassword` -  Receive the password at runtime as a secure string. Requires input at runtime whe installing/upgrading the package.
-* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. Defaults to default or explicit values for `/SqlServiceInstance` and `/Database`, along with Integrated Security (`Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True;`). The account should have `db_datareader`/`db_datawriter` access to the database ([data reader / data writer](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles)).
+* `/ConnectionString:` - The SQL Server database connection string to be used to connect to the Chocolatey Central Management database. By default, this value is constructed from the default or explicit values for `/SqlServiceInstance` and `/Database`, and uses Integrated Security (with all default values, this value will look like the following: `Server=<LOCAL COMPUTER FQDN NAME>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;`). The account should have [`db_datareader`/`db_datawriter`](https://docs.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles#fixed-database-roles) access to the database.
 * `/SqlServerInstance:` - Instance name of the SQL Server database to connect to. Alternative to passing full connection string with `/ConnectionString`. Uses `/Database` (below) to build a connection string. Defaults to `<LOCAL COMPUTER FQDN NAME>`.
 * `/Database:` - Name of the SQL Server database to use. Alternative to passing full connection string with `/ConnectionString`. Uses `/SqlServerInstance` (above) to build a connection string. Defaults to `ChocolateyManagement`.
 
@@ -91,6 +92,8 @@ This includes (but may not be limited to):
 
 ### Database Authentication Scenarios
 
+<CentralManagementSecureConnectionStrings />
+
 * <Xref title="Scenario 1 - Windows Authentication to Local SQL Server" value="ccm-website" anchor="scenario-one" />
 * <Xref title="Scenario 2 - Active Directory Authentication to Remote SQL Server" value="ccm-website" anchor="scenario-two" />
 * <Xref title="Scenario 3 - SQL Server Authentication to Local SQL Server" value="ccm-website" anchor="scenario-three" />
@@ -272,7 +275,7 @@ Here is a copy of items that can be set. They are not required to be encrypted.
 ```json
 {
   "ConnectionStrings": {
-        "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+        "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   },
   "App": {
     "WebSiteRootAddress": "http://<FQDN_OR_BINDING_HERE>"
@@ -311,7 +314,7 @@ As of Chocolatey Central Management v0.6.2, the default settings in the `appsett
 ```json
 {
   "ConnectionStrings": {
-    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   },
   "App": {
     "WebSiteRootAddress": "http://<FQDN_OR_BINDING_HERE>"
@@ -351,7 +354,7 @@ It depends. You can simply go to the `appsettings.json` file and adjust the conn
 ```json
 {
   "ConnectionStrings": {
-    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True;"
+    "Default": "Server=<HOST_NAME_OF_MACHINE_BEING_INSTALLED_ONTO>; Database=ChocolateyManagement; Trusted_Connection=True; TrustServerCertificate=True;"
   },
   "App": {
     "WebSiteRootAddress": "http://<FQDN_OR_BINDING_HERE>"
