docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updates to enforce sign-in docs

This commit is contained in:
Sarah Sanders 2024-10-28 13:52:07 -07:00
parent a691e88d9f
commit f21f2f81bb
2 changed files with 36 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
content/manuals/security/for-admins/enforce-sign-in/_index.md
View File

@ -16,14 +16,14 @@ receive the [benefits of your organization’s
subscription](../../../subscription/core-subscription/details.md) and they can circumvent [Docker’s
security features](/manuals/security/for-admins/hardened-desktop/_index.md) for your organization.
There are multiple ways you can enforce sign-in, depending on your companies' set up and preferences:
There are multiple methods for enforcing sign-in, depending on your companies' set up and preferences:
- [Registry key method (Windows only)](methods.md#registry-key-method-windows-only){{< badge color=green text="New" >}}
- [`.plist` method (Mac only)](methods.md#plist-method-mac-only){{< badge color=green text="New" >}}
- [`registry.json` method (All)](methods.md#registryjson-method-all)
## How is sign-in enforced?
When Docker Desktop starts and it detects a registry key, a `.plist` file or `registry.json` file, the
When Docker Desktop starts and it detects a registry key, `.plist` file, or `registry.json` file, the
following occurs:
- A **Sign in required!** prompt appears requiring the user to sign
@ -48,4 +48,9 @@ description and benefits when using each feature.
| Enforce sign-in only | Users must sign in before using Docker Desktop. | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. |
| Enforce single sign-on (SSO) only | If users sign in, they must sign in using SSO. | Centralizes authentication and enforces unified policies set by the identity provider. |
| Enforce both | Users must sign in using SSO before using Docker Desktop. | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. Finally, it centralizes authentication and enforces unified policies set by the identity provider. |
| Enforce neither | If users sign in, they can use SSO or their Docker credentials. | Allows users to access Docker Desktop without barriers, but at the cost of reduced security and insights. |
| Enforce neither | If users sign in, they can use SSO or their Docker credentials. | Lets users access Docker Desktop without barriers, but at the cost of reduced security and insights. |
## What's next?
- To enforce sign-in, review the [Methods](/manuals/security/for-admins/enforce-sign-in/methods.md) guide.
- To enforce SSO, review the [Enforce SSO](/manuals/security/for-admins/single-sign-on/connect.md) steps.

60
content/manuals/security/for-admins/enforce-sign-in/methods.md
View File

@ -5,7 +5,7 @@ title: Ways to enforce sign-in for Docker Desktop
linkTitle: Methods
---
This page outlines the different ways you can enforce sign-in for Docker Desktop.
This page outlines the different methods for enforcing sign-in for Docker Desktop.
## Registry key method (Windows only)
@ -13,18 +13,20 @@ This page outlines the different ways you can enforce sign-in for Docker Desktop
>
> The registry key method is available with Docker Desktop version 4.32 and later.
To enforce sign-in for Docker Desktop on Windows, you can configure a registry key that specifies your organization's allowed users. The following steps guide you through creating and deploying the registry key to enforce this policy:
1. Create the registry key. Your new key should look like the following:
```console
```console
$ HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop
```
2. Create a multi-string value `allowedOrgs`.
2. Create a multi-string value `allowedOrgs`.
> [!IMPORTANT]
>
> Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails.
3. As string data use your organization’s name, all lowercase.
3. Use your organization's name, all lowercase as string data.
4. Restart Docker Desktop.
5. Open Docker Desktop and when Docker Desktop starts, verify that the **Sign in required!** prompt appears.
5. When Docker Desktop restarts, verify that the **Sign in required!** prompt appears.
In some cases, a system reboot may be necessary for enforcement to take effect.
@ -34,24 +36,21 @@ In some cases, a system reboot may be necessary for enforcement to take effect.
### Example deployment via Group Policy
The following is only an illustrative example.
There are many ways to deploy the registry key, for example using an MDM solution or with PowerShell scripting. The method you choose is dependent on your organizations infrastructure, security policies, and the administrative rights of the end-users.
The following example outlines how to deploy a registry key to enforce sign-in on Docker Desktop using Group Policy. There are multiple ways to deploy this configuration depending on your organization's infrastructure, security policies, and management tools.
1. Create the registry script. Write a script to create the `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop` key, add the `allowedOrgs` multi-string, and then set the value to your organization’s name.
2. Within Group Policy, create or edit a Group Policy Objective (GPO) that applies to the machines or users you want to target.
3. Within the GPO, navigate to **Computer Configuration** > **Preferences** > **Windows Settings** > **Registry**.
4. Add the registry item. Right-click on the **Registry** node, select **New** > **Registry Item**.
5. Configure the new registry item to match the registry script you created, specifying the action as **Update**. Make sure you input the correct path, value name (`allowedOrgs`), and value data (your organization’s name).
6. Link the GPO to an Organizational Unit (OU) that contains the machines you want to apply this setting to.
7. Test the GPO. Test the GPO on a small set of machines first to ensure it behaves as expected. You can use the `gpupdate /force` command on a test machine to manually refresh its group policy settings and check the registry to confirm the changes.
8. Once verified, you can proceed with broader deployment. Monitor the deployment to ensure the settings are applied correctly across the organization's computers.
3. Within the GPO, navigate to **Computer Configuration** and select **Preferences**.
4. Select **Windows Settings** then **Registry**.
5. To add the registry item, right-click on the **Registry** node, select **New**, and then **Registry Item**.
6. Configure the new registry item to match the registry script you created, specifying the action as **Update**. Make sure you input the correct path, value name (`allowedOrgs`), and value data (your organization’s name).
7. Link the GPO to an Organizational Unit (OU) that contains the machines you want to apply this setting to.
8. Test the GPO on a small set of machines first to ensure it behaves as expected. You can use the `gpupdate /force` command on a test machine to manually refresh its group policy settings and check the registry to confirm the changes.
9. Once verified, you can proceed with broader deployment. Monitor the deployment to ensure the settings are applied correctly across the organization's computers.
## plist method (Mac only)
> [!NOTE]
>
> The registry key method is available with Docker Desktop version 4.32 and later.
To enforce sign-in for Docker Desktop on macOS, you can use a `plist` file that defines the required settings. The following steps guide you through the process of creating and deploying the necessary `plist` file to enforce this policy:
1. Create the file `/Library/Application Support/com.docker.docker/desktop.plist`.
2. Open `desktop.plist` in a text editor and add the following content, where `myorg` is replaced with your organization’s name all lowercase:
@ -73,18 +72,16 @@ There are many ways to deploy the registry key, for example using an MDM solutio
> Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails.
3. Modify the file permissions to ensure the file cannot be edited by any non-administrator users.
4. Restart Docker Desktop.
5. Open Docker Desktop and when Docker Desktop starts, verify that the **Sign in required!** prompt appears.
4. Restart Docker Desktop.
5. When Docker Desktop restarts, verify that the **Sign in required!** prompt appears.
> [!NOTE]
>
> If a `plist` and `registry.json` file both exist, the `plist` file takes precedence.
### Example deployment
### Example deployment
The following is only an illustrative example.
There are many ways to deploy the `.plist` file. The method you choose is dependent on your organizations infrastructure, security policies, and the administrative rights of the end-users.
The following example outlines how to create and distribute the `plist` file to enforce sign-in on Docker Desktop using Group Policy. There are multiple ways to deploy this configuration depending on your organization's infrastructure, security policies, and management tools.
{{< tabs >}}
{{< tab name="MDM" >}}
@ -107,22 +104,21 @@ There are many ways to deploy the `.plist` file. The method you choose is depend
2. Before deploying the script across the organization, test it on a local macOS machine to ensure it behaves as expected. Pay attention to directory paths, permissions, and the successful application of `plist` settings.
3. Ensure that you have the capability to execute scripts remotely on macOS devices. This might involve setting up SSH access or using a remote support tool that supports macOS.
4. Use a method of remote script execution that fits your organization's infrastructure. Options include:
- SSH. If SSH is enabled on the target machines, you can use it to execute the script remotely. This method requires knowledge of the device's IP address and appropriate credentials.
- Remote support tool. For organizations using a remote support tool, you can add the script to a task and execute it across all selected machines.
5. Ensure the script is running as expected on all targeted devices. This might involve checking log files or implementing logging within the script itself to report its success or failure.
- SSH: If SSH is enabled on the target machines, you can use it to execute the script remotely. This method requires knowledge of the device's IP address and appropriate credentials.
- Remote support tool: For organizations using a remote support tool, you can add the script to a task and execute it across all selected machines.
5. Ensure the script is running as expected on all targeted devices. You may have to check log files or implement logging within the script itself to report its success or failure.
{{< /tab >}}
{{< /tabs >}}
## registry.json method (All)
The following instructions explain how to create and deploy a `registry.json` file to a single device. There are many ways to deploy the `registry.json` file. You can follow the example deployments outlined in the `.plist` file section. The method you choose is dependent on your organization's infrastructure, security policies, and the administrative rights of the end-users.
The following instructions explain how to create and deploy a `registry.json` file to a single device. There are many ways to deploy the `registry.json` file. You can follow the example deployments outlined in the `.plist` file section. The method you choose is dependent on your organization's infrastructure, security policies, and the administrative rights of the end-users.
### Option 1: Create a registry.json file to enforce sign-in
1. Ensure that the user is a member of your organization in Docker. For more
1. Ensure the user is a member of your organization in Docker. For more
details, see [Manage members](/admin/organization/members/).
2. Create the `registry.json` file.
Based on the user's operating system, create a file named `registry.json` at the following location and make sure the file can't be edited by the user.
@ -150,8 +146,8 @@ details, see [Manage members](/admin/organization/members/).
4. Verify that sign-in is enforced.
To activate the `registry.json` file, restart Docker Desktop on the user’s machine. When Docker Desktop starts, verify that the **Sign in
required!** prompt appears.
required!** prompt appears.
In some cases, a system reboot may be necessary for the enforcement to take effect.
> [!TIP]