security: add settings reference (docker#22625)

## Description
- Add a settings reference for a source of truth for Settings Management
and Docker Desktop settings
- Improved other Settings Management docs to link to reference and make
steps simpler
- Added hardened security recommendations to reference

*Ignore vale error*

## Related issues or tickets
https://docker.atlassian.net/browse/ENGDOCS-2581

## Reviews
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

---------

Co-authored-by: Craig Osterhout <[email protected]>

Author: sarahsanders-docker

content/manuals/security/for-admins/hardened-desktop/settings-management/_index.md

@@ -12,70 +12,73 @@ weight: 10
 
 {{< summary-bar feature_name="Hardened Docker Desktop" >}}
 
-Settings Management helps you control key Docker Desktop settings, like proxies and network configurations, on your developers' machines within your organization.
-
-For an extra layer of security, you can also use Settings Management to enable and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md), which prevents containers from modifying any Settings Management configurations.
+Settings Management lets administrators configure and enforce Docker Desktop
+settings across ennd-user machines. It helps maintain consistent configurations
+and enhances security within your organization.
 
 ## Who is it for?
 
-- For organizations that want to configure Docker Desktop to be within their organization's centralized control.
-- For organizations that want to create a standardized Docker Desktop environment at scale.
-- For Docker Business customers who want to confidently manage their use of Docker Desktop within tightly regulated environments.
+Settings Management is designed for organizations that:
+
+- Require centralized control over Docker Desktop configurations.
+- Aim to standardize Docker Desktop environments across teams.
+- Operate in regulated environments and need to enforce compliance.
 
-## How does it work?
+This feature is available with a Docker Business subscription.
 
-You can configure several Docker Desktop settings using either:
+## How it works
 
- - An `admin-settings.json` file. This file is located on the Docker Desktop host and can only be accessed by developers with root or administrator privileges.
- - Creating a settings policy in the Docker Admin Console.
+Administrators can define settings using one of the following methods:
 
-Settings that are defined by an administrator override any previous values set by developers and ensure that these cannot be modified.
+- [Admin Console](/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md): Create and assign settings policies through the
+Docker Admin Console.
+- [`admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md): Place a configuration file on the
+user's machine to enforce settings.
 
-## What features can I configure with Settings Management?
+Enforced settings override user-defined configurations and can't be modified
+by developers.
 
-Using the `admin-settings.json` file, you can:
+## Configurable settings
 
-- Turn on and lock in [Enhanced Container Isolation](../enhanced-container-isolation/_index.md)
-- Configure HTTP proxies
-- Configure network settings
-- Configure Kubernetes settings
-- Enforce the use of WSL 2 based engine or Hyper-V
-- Enforce the use of Rosetta for x86_64/amd64 emulation on Apple Silicon
-- Configure Docker Engine
-- Turn off Docker Desktop's ability to checks for updates
-- Turn off Docker Extensions
-- Turn off Docker Scout SBOM indexing
-- Turn off beta and experimental features
-- Turn off Docker AI ([Ask Gordon](/manuals/ai/gordon/_index.md))
-- Turn off Docker Desktop's onboarding survey
-- Control whether developers can use the Docker terminal
-- Control the file sharing implementation for your developers on macOS
-- Specify which paths your developers can add file shares to
-- Configure Air-gapped containers
+Settings Management supports a broad range of Docker Desktop features,
+including proxies, network configurations, and container isolation.
 
-For more details on the syntax and options, see [Configure Settings Management](configure-json-file.md).
+For a full list of settings you can enforce, see the [Settings reference](/manuals/security/for-admins/hardened-desktop/settings-management/settings-reference.md).
 
-## How do I set up and enforce Settings Management?
+## Set up Settings Management
 
-You first need to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to ensure that all Docker Desktop developers authenticate with your organization. Since the Settings Management feature requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in.
+1. [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to
+ensure all developers authenticate with your organization.
+2. Choose a configuration method:
+    - Use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json`.
+    - Manually create and configure the [`admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md).
+    - Create a settings policy in the [Docker Admin Console](configure-admin-console.md).
 
-Next, you must either:
- - Manually [create and configure the `admin-settings.json` file](configure-json-file.md), or use the `--admin-settings` installer flag on [macOS](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line) or [Windows](/manuals/desktop/setup/install/windows-install.md#install-from-the-command-line) to automatically create the `admin-settings.json` and save it in the correct location.
- - Fill out the **Settings policy** creation form in the [Docker Admin Console](configure-admin-console.md).
+After configuration, developers receive the enforced setting when they:
 
-Once this is done, Docker Desktop developers receive the changed settings when they either:
-- Quit, re-launch, and sign in to Docker Desktop
-- Launch and sign in to Docker Desktop for the first time
+- Quit and relaunch Docker Desktop, then sign in.
+- Launch and sign in to Docker Desktop for the first time.
 
-To avoid disrupting your developers' workflows, Docker doesn't automatically require that developers re-launch and re-authenticate once a change has been made.
+> [!NOTE]
+>
+> Docker Desktop does not automatically prompt users to restart or re-authenticate
+after a settings change.
 
-## What do developers see when the settings are enforced?
+## Developer experience
 
-Enforced settings appear grayed out in Docker Desktop. They can't be edited via the Docker Desktop Dashboard, CLI, or `settings-store.json` (or `settings.json` for Docker Desktop 4.34 and earlier).
+When settings are enforced:
 
-In addition, if Enhanced Container Isolation is enforced, developers can't use privileged containers or similar techniques to modify enforced settings within the Docker Desktop Linux VM. For example, they can't reconfigure proxy and networking, or Docker Engine.
+- Options appear grayed out in Docker Desktop and can't be modified via the
+Dashboard, CLI, or configuration files.
+- If Enhanced Container Isolation is enabled, developers can't use privileged
+containers or similar methods to alter enforced settings within the Docker
+Desktop Linux VM.
 
 ## What's next?
 
-- [Configure Settings Management with a `.json` file](configure-json-file.md)
+- [Configure Settings Management with the `admin-settings.json` file](configure-json-file.md)
 - [Configure Settings Management with the Docker Admin Console](configure-admin-console.md)
+
+## Learn more
+
+To see how each Docker Desktop setting maps across the Docker Dashboard, `admin-settings.json` file, and Admin Console, see the [Settings reference](settings-reference.md).

content/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md

@@ -8,68 +8,78 @@ weight: 20
 
 {{< summary-bar feature_name="Admin Console" >}}
 
-This page contains information for administrators on how to configure Settings Management with the Docker Admin Console. You can specify and lock configuration parameters to create a standardized Docker Desktop environment across your Docker company or organization.
+This page explains how administrators can use the Docker Admin Console to create
+and apply settings policies for Docker Desktop. These policies help standardize
+and secure Docker Desktop environments across your organization.
 
 ## Prerequisites
 
-- [Download and install Docker Desktop 4.36.0 or later](/manuals/desktop/release-notes.md).
+- [Install Docker Desktop 4.36.0 or later](/manuals/desktop/release-notes.md).
 - [Verify your domain](/manuals/security/for-admins/single-sign-on/configure.md#step-one-add-and-verify-your-domain).
-- [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). The Settings Management feature requires a Docker Business
-subscription, therefore your Docker Desktop users must authenticate to your
-organization for configurations to take effect.
+- [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to
+ensure users authenticate to your organization.
+- A Docker Business subscription is required.
+
+> [!IMPORTANT]
+>
+> You must add users to your verified domain for settings to take effect.
 
 ## Create a settings policy
 
-1. Within the [Docker Admin Console](https://app.docker.com/admin) navigate to the company or organization you want to define a settings policy for.
-2. Under the **Docker Desktop** section, select **Settings Management**.
+1. Go to the [Docker Admin Console](https://app.docker.com/admin) and select
+your organization.
+2. Under **Docker Desktop**, select **Settings Management**.
 3. Select **Create a settings policy**.
-4. Give your settings policy a name and an optional description.
+4. Provide a name and optional description.
 
-   > [!TIP]
-   >
-   > If you have already configured Settings Management with an `admin-settings.json` file for an organization, you can upload it using the **Upload existing settings** button which then automatically populates the form for you.
-   >
-   > Settings policies deployed via the Docker Admin Console take precedence over manually deployed `admin-settings.json` files.
+      > [!TIP]
+      >
+      > You can upload an existing `admin-settings.json` file to pre-fill the form.
+      Admin Console policies override local `admin-settings.json` files.
 
-5. Assign the setting policy to all your users within the company or organization, or specific users.
+5. Choose who the policy applies to:
+   - All users
+   - Specific users
 
-   > [!NOTE]
-   >
-   > If a settings policy is assigned to all users, it sets the policy as the global default policy. You can only have one global settings policy at a time.
-   > If a user already has a user-specific settings policy assigned, the user-specific policy takes precedence over a global policy.
+      > [!NOTE]
+      >
+      > User-specific policies override the global default. Test your policy with
+      a few users before rolling it out globally.
 
-   > [!TIP]
-   >
-   > Before setting a global settings policy, it is recommended that you first test it as a user-specific policy to make sure you're happy with the changes before proceeding.
+6. Configure the state for each setting:
+   - **User-defined**: Users can change the setting.
+   - **Always enabled**: Setting is on and locked.
+   - **Enabled**: Setting is on but can be changed.
+   - **Always disabled**: Setting is off and locked.
+   - **Disabled**: Setting is off but can be changed.
 
-6. Configure the settings for the policy. Go through each setting and select your chosen setting state. You can choose:
-   - **User-defined**. Your developers are able to control and change this setting.
-   - **Always enabled**. This means the setting is turned on and your users won't be able to edit this setting from Docker Desktop or the CLI.
-   - **Enabled**. The setting is turned on and users can edit this setting from Docker Desktop or the CLI.
-   - **Always disabled**. This means the setting is turned off and your users won't be able to edit this setting from Docker Desktop or the CLI.
-   - **Disabled**. The setting is turned off and users can edit this setting from Docker Desktop or the CLI.
-7. Select **Create**
+      > [!TIP]
+      >
+      > For a complete list of available settings, their supported platforms, and which configuration methods they work with, see the [Settings reference](settings-reference.md).
 
-For the settings policy to take effect:
-- On a new install, users need to launch Docker Desktop and authenticate to their organization.
-- On an existing install, users need to quit Docker Desktop through the Docker menu, and then re-launch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect.
+7. Select **Create**.
 
-  > [!IMPORTANT]
-  >
-  > Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop.
+To apply the policy:
 
-To avoid disrupting your users' workflows, Docker doesn't automatically require that users re-launch once a change has been made.
+- New installs: Launch Docker Desktop and sign in.
+- Existing installs: Fully quit and relaunch Docker Desktop.
 
-> [!NOTE]
+> [!IMPORTANT]
 >
-> Settings are synced to Docker Desktop and the CLI when a user is signed in and starts Docker Desktop, and then every 60 minutes.
+> Restarting from the Docker Desktop menu isn't enough. Users must fully quit
+and relaunch Docker Desktop.
+
+Docker Desktop checks for policy updates at launch and every 60 minutes. To roll
+back a policy, either delete it or set individual settings to **User-defined**.
+
+## Manage policies
 
-If your settings policy needs to be rolled back, either delete the policy or edit the policy to set individual settings to **User-defined**.
+From the **Actions** menu on the **Settings Management** page, you can:
 
-## Settings policy actions
+- Edit or delete an existing settings policy
+- Export a settings policy as an `admin-settings.json` file
+- Promote a user-specific policy to be the new global default
 
-From the **Actions** menu on the **Settings Management** page in the Docker Admin Console, you can:
+## Learn more
 
-- Edit or delete an existing settings policy.
-- Export a settings policy as an `admin-settings.json` file.
-- Promote a policy that is applied to a select group of users, to be the new global default policy for all users.
+To see how each Docker Desktop setting maps across the Docker Dashboard, `admin-settings.json` file, and Admin Console, see the [Settings reference](settings-reference.md).