Skip to content

enforce-sign-in-updates #21393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 18, 2024
Merged

enforce-sign-in-updates #21393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d29b966
enforce-sign-in-updates
aevesdocker Nov 11, 2024
e31cbb3
edits
aevesdocker Nov 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/manuals/security/for-admins/enforce-sign-in/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ security features](/manuals/security/for-admins/hardened-desktop/_index.md) for

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" >}}
- [Configuration profiles method (Mac only)](methods.md#configuration-profiles-method-mac-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)

Expand Down
101 changes: 95 additions & 6 deletions content/manuals/security/for-admins/enforce-sign-in/methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ To enforce sign-in for Docker Desktop on Windows, you can configure a registry k
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.
> As of Docker Desktop version 4.36 and later, you can add more than one organization. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails.
3. Use your organization's name, all lowercase as string data.
4. Restart Docker Desktop.
5. When Docker Desktop restarts, verify that the **Sign in required!** prompt appears.
Expand All @@ -43,11 +43,84 @@ The following example outlines how to deploy a registry key to enforce sign-in o
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).
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 names).
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.

## Configuration profiles method (Mac only)

> [!NOTE]
>
> The configuration profiles method is in [Early Access](/manuals/release-lifecycle.md)
> and is available with Docker Desktop version 4.36 and later.

Configuration profiles are a feature of macOS that let you distribute
configuration information to the Macs you manage. It is the safest method to
enforce sign-in on macOS because the installed configuration profiles are
protected by Apples' System Integrity Protection (SIP) and therefore can't be
tampered with by the users.

1. Save the following XML file with the extension `.mobileconfig`, for example
`docker.mobileconfig`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array>
<dict>
<key>PayloadType</key>
<string>com.docker.config</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadIdentifier</key>
<string>com.docker.config</string>
<key>PayloadUUID</key>
<string>eed295b0-a650-40b0-9dda-90efb12be3c7</string>
<key>PayloadDisplayName</key>
<string>Docker Desktop Configuration</string>
<key>PayloadDescription</key>
<string>Configuration profile to manage Docker Desktop settings.</string>
<key>PayloadOrganization</key>
<string>Your Company Name</string>
<key>allowedOrgs</key>
<string>first_org;second_org</string>
</dict>
</array>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadIdentifier</key>
<string>com.yourcompany.docker.config</string>
<key>PayloadUUID</key>
<string>0deedb64-7dc9-46e5-b6bf-69d64a9561ce</string>
<key>PayloadDisplayName</key>
<string>Docker Desktop Config Profile</string>
<key>PayloadDescription</key>
<string>Config profile to enforce Docker Desktop settings for allowed organizations.</string>
<key>PayloadOrganization</key>
<string>Your Company Name</string>
</dict>
</plist>
```

2. Change the placeholders `com.yourcompany.docker.config` and `Your Company Name` to the name of your company.

3. Add your organization name. The names of the allowed organizations are stored in the `allowedOrgs`
property. It can contain either the name of a single organization or a list of organization names,
separated by a semicolon:

```xml
<key>allowedOrgs</key>
<string>first_org;second_org</string>
```

4. Use a MDM solution to distribute your modified `.mobileconfig` file to your macOS clients.

## plist method (Mac only)

> [!NOTE]
Expand All @@ -66,14 +139,15 @@ To enforce sign-in for Docker Desktop on macOS, you can use a `plist` file that
<dict>
<key>allowedOrgs</key>
<array>
<string>myorg</string>
<string>myorg1</string>
<string>myorg2</string>
</array>
</dict>
</plist>
```
> [!IMPORTANT]
>
> Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails.
> As of Docker Desktop version 4.36 and later, you can add more than one organization. With Docker Desktop version 4.35 and earlier, sign-in enforcement silently fails if you add more than one organization.

3. Modify the file permissions to ensure the file cannot be edited by any non-administrator users.
4. Restart Docker Desktop.
Expand Down Expand Up @@ -140,12 +214,12 @@ details, see [Manage members](/admin/organization/members/).

```json
{
"allowedOrgs": ["myorg"]
"allowedOrgs": ["myorg1", "myorg2"]
}
```
> [!IMPORTANT]
>
> Only one entry for `allowedOrgs` is currently supported. If you add more than one value, sign-in enforcement silently fails.
> As of Docker Desktop version 4.36 and later, you can add more than one organization. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails.

4. Verify that sign-in is enforced.

Expand Down Expand Up @@ -182,6 +256,9 @@ If you're using the Windows Command Prompt:
```console
C:\Users\Admin> "Docker Desktop Installer.exe" install --allowed-org=myorg
```
> [!IMPORTANT]
>
> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails.

{{< /tab >}}
{{< tab name="Mac" >}}
Expand Down Expand Up @@ -231,6 +308,10 @@ Path Owner Access
registry.json BUILTIN\Administrators NT AUTHORITY\SYSTEM Allow FullControl...
```

> [!IMPORTANT]
>
> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails.

{{< /tab >}}
{{< tab name="Mac" >}}

Expand Down Expand Up @@ -264,6 +345,10 @@ $ sudo ls -l "/Library/Application Support/com.docker.docker/registry.json"
-rw-r--r-- 1 root admin 26 Jul 27 22:01 /Library/Application Support/com.docker.docker/registry.json
```

> [!IMPORTANT]
>
> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails.

{{< /tab >}}
{{< tab name="Linux" >}}

Expand Down Expand Up @@ -297,6 +382,10 @@ $ sudo ls -l /usr/share/docker-desktop/registry/registry.json
-rw-r--r-- 1 root root 26 Jul 27 22:01 /usr/share/docker-desktop/registry/registry.json
```

> [!IMPORTANT]
>
> As of Docker Desktop version 4.36 and later, you can add more than one organization to a single `registry.json` file. With Docker Desktop version 4.35 and earlier, if you add more than one organization sign-in enforcement silently fails.

{{< /tab >}}
{{< /tabs >}}

Expand Down
18 changes: 11 additions & 7 deletions layouts/shortcodes/admin-registry-access.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,17 @@
>
> When enabled, the Docker Hub registry is set by default, however you can also restrict this registry for your developers.

4. Select **Add registry** and enter your registry details in the applicable fields, and then select **Create** to add the registry to your list.
4. Select **Add registry** and enter your registry details in the applicable fields, and then select **Create** to add the registry to your list. There is no limit on the number of registries you can add.
5. Verify that the registry appears in your list and select **Save changes**.

> [!NOTE]
>
> Once you add a registry, it can take up to 24 hours for the changes to be enforced on your developers’ machines. If you want to apply the changes sooner, you must force a Docker logout on your developers’ machine and have the developers re-authenticate for Docker Desktop. Also, there is no limit on the number of registries you can add. See the Caveats section below to learn more about limitations when using this feature.
Once you add a registry, it can take up to 24 hours for the changes to be enforced on your developers’ machines.

> [!TIP]
>
> Since RAM sets policies about where content can be fetched from, the [ADD](/reference/dockerfile/#add) instruction of the Dockerfile, when the parameter of the ADD instruction is a URL, is also subject to registry restrictions. It's recommended that you add the domains of URL parameters to the list of allowed registry addresses under the Registry Access Management settings of your organization.
If you want to apply the changes sooner, you must force a Docker signout on your developers’ machine and have the developers re-authenticate for Docker Desktop. See the [Caveats](#caveats) section below to learn more about limitations when using this feature.

> [!IMPORTANT]
>
> Starting with Docker Desktop version 4.36, you can enforce sign-in for multiple organizations. If a developer belongs to multiple organizations with different RAM policies, only the RAM policy for the first organization listed in the `registry.json` file, `.plist` file, or registry key is enforced.

> [!TIP]
>
> Since RAM sets policies about where content can be fetched from, the [ADD](/reference/dockerfile/#add) instruction of the Dockerfile, when the parameter of the ADD instruction is a URL, is also subject to registry restrictions. It's recommended that you add the domains of URL parameters to the list of allowed registry addresses under the Registry Access Management settings of your organization.