Configure sign-in enforcement

Table of contents

Subscription: Team Business

For: Administrators

You can enforce sign-in for Docker Desktop using several methods. Choose the method that best fits your organization's infrastructure and security requirements.

Every method below takes one or more organization namespaces, not organization display names. The namespace is the permanent identifier for the organization (for example, the first part of namespace/image:tag). Use lowercase letters only, with no spaces. If you enter the display name instead, users can authenticate successfully and then get signed out with a membership error that cites the value you configured.

Choose your method

Method	Platform
Registry key	Windows only
Configuration profiles	Mac only
`plist` file	Mac only
`registry.json`	All platforms

Tip
For Mac, configuration profiles offer the highest security because they're protected by Apple's System Integrity Protection (SIP).

Windows: Registry key method

To configure the registry key method manually:

Create the registry key:

$ HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop

Create a multi-string value name allowedOrgs.
Use your organization namespaces as string data. You can add multiple namespaces:
- Use lowercase letters only
- Add each namespace on a separate line
- Do not use spaces or commas as separators
Restart Docker Desktop.
Verify the Sign in required! prompt appears in Docker Desktop.

You can also create this key at install time with the MSI installer's ALLOWEDORG property, which accepts multiple organization namespaces separated by semicolons:

msiexec /i "DockerDesktop.msi" /quiet /norestart ALLOWEDORG="myorg1;myorg2"

For more information, see MSI installer.

Deploy the registry key across your organization using Group Policy:

Create a registry script with the following structure:
- Path: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop
- Value name: allowedOrgs (multi-string)
- Value data: Your organization namespaces, one per line, in lowercase only
In Group Policy Management, create or edit a GPO.
Navigate to Computer Configuration > Preferences > Windows Settings > Registry.
Right-click Registry > New > Registry Item.
Configure the registry item:
- Action: Update
- Path: HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop
- Value name: allowedOrgs
- Value data: Your organization namespaces
Link the GPO to the target Organizational Unit.
Test on a small group using gpupdate/force.
Deploy organization-wide after verification.

Mac: Configuration profiles method (recommended)

Configuration profiles provide the most secure enforcement method for Mac, as they're protected by Apple's System Integrity Protection.

The payload is a dictionary of key-values. Docker Desktop supports the following keys:

allowedOrgs: Sets a list of organization namespaces in one single string, where each namespace is in lowercase only and is separated by a semi-colon.
overrideProxyHTTP: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests.
overrideProxyHTTPS: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests.
overrideProxyExclude: Bypasses proxy settings for the specified hosts and domains. Uses a comma-separated list.
overrideProxyPAC: Sets the file path where the PAC file is located. It has precedence over the remote PAC file on the selected proxy.
overrideProxyEmbeddedPAC: Sets the content of an in-memory PAC file. It has precedence over overrideProxyPAC.

Important
allowedOrgs must be a <string>, not an <array>. Docker Desktop only reads string values from a configuration profile, so an array is silently ignored and no enforcement happens. This differs from the .plist method, which does use an array.

Setting at least one of the proxy keys puts Docker Desktop's proxy into manual mode and locks the proxy settings, so developers can't change them.

Create a file named docker.mobileconfig and include the following content:

<?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>
         <key>overrideProxyHTTP</key>
         <string>http://company.proxy:port</string>
         <key>overrideProxyHTTPS</key>
         <string>https://company.proxy:port</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>

Replace placeholders:
- Change com.yourcompany.docker.config to your company identifier
- Replace Your company name under PayloadOrganization with your company or organization display name
- Replace PayloadUUID with a randomly generated UUID
- Update the allowedOrgs value with your organization namespaces (separated by semicolons, lowercase only)
- Replace company.proxy:port with http/https proxy server host(or IP address) and port
Deploy the profile using your MDM solution.
Verify the profile appears in System Settings > General > Device Management under Device (Managed). Ensure the profile is listed with the correct name and settings.

Some MDM solutions let you specify the payload as a plain dictionary of key-value settings without the full .mobileconfig wrapper:

<dict>
   <key>allowedOrgs</key>
   <string>first_org;second_org</string>
   <key>overrideProxyHTTP</key>
   <string>http://company.proxy:port</string>
   <key>overrideProxyHTTPS</key>
   <string>https://company.proxy:port</string>
</dict>

Mac: plist file method

Create the file /Library/Application Support/com.docker.docker/desktop.plist.

Add this content, replacing myorg1 and myorg2 with your organization namespaces and making sure they have lowercase letters only:

<?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>allowedOrgs</key>
      <array>
          <string>myorg1</string>
          <string>myorg2</string>
      </array>
  </dict>
</plist>

Set file permissions to prevent editing by non-administrator users.
Restart Docker Desktop.
Verify the Sign in using your work email address prompt appears in Docker Desktop.

Create and deploy a script for organization-wide distribution:

#!/bin/bash

# Create directory if it doesn't exist
sudo mkdir -p "/Library/Application Support/com.docker.docker"

# Write the plist file
sudo defaults write "/Library/Application Support/com.docker.docker/desktop.plist" allowedOrgs -array "myorg1" "myorg2"

# Set appropriate permissions
sudo chmod 644 "/Library/Application Support/com.docker.docker/desktop.plist"
sudo chown root:admin "/Library/Application Support/com.docker.docker/desktop.plist"

Deploy this script using SSH, remote support tools, or your preferred deployment method.

All platforms: registry.json method

The registry.json method works across all platforms and offers flexible deployment options.

File locations

Create the registry.json file (UTF-8) at the appropriate location:

Platform	Location
Windows	`%ProgramData%\DockerDesktop\registry.json`
Mac	`/Library/Application Support/com.docker.docker/registry.json`
Linux	`/usr/share/docker-desktop/registry/registry.json`

Basic setup

Ensure users are members of your Docker organization.
Create the registry.json file at the appropriate location for your platform.
Add this content, replacing the example values with your organization namespaces and making sure they have lowercase letters only:
{ "allowedOrgs": ["myorg1", "myorg2"] }
Set file permissions to prevent user editing.
Restart Docker Desktop.
Verify the Sign in using your work email address prompt appears in Docker Desktop.

If users have issues starting Docker Desktop after enforcing sign-in, they may need to update to the latest version.

Windows (PowerShell as Administrator)

Set-Content /ProgramData/DockerDesktop/registry.json '{"allowedOrgs":["myorg1","myorg2"]}'

Mac

sudo mkdir -p "/Library/Application Support/com.docker.docker"
echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json"

Linux

sudo mkdir -p /usr/share/docker-desktop/registry
echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee /usr/share/docker-desktop/registry/registry.json

Create the registry.json file during Docker Desktop installation:

Windows

--allowed-org is a flag on the EXE installer. If you deploy with the MSI installer, use the ALLOWEDORG property instead, which creates the registry key.

# PowerShell
Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg'

# Command Prompt
"Docker Desktop Installer.exe" install --allowed-org=myorg1

The --allowed-org flag accepts only one organization namespace. To enforce sign-in for multiple namespaces on Mac, configure the registry.json file after installation.

Important
With Docker Desktop version 4.83 and later, --allowed-org can't be combined with --user, and it can't be used for a Microsoft Store installation. Both are per-user installations and the installer rejects the combination. This matters because the Windows installer selects a per-user installation by default from version 4.83. For per-user installations, configure the registry.json file after installation.

Mac

sudo hdiutil attach Docker.dmg
sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg
sudo hdiutil detach /Volumes/Docker

The --allowed-org flag accepts only one organization namespace. To enforce sign-in for multiple namespaces on Mac, configure the registry.json file after installation.

Method precedence

When more than one configuration method exists on the same machine, Docker Desktop evaluates them in order and stops at the first one that's configured. The order depends on the platform.

Platform	Precedence order
Windows	1. Registry key 2. `registry.json` 3. `admin-settings.json`
Mac	1. Configuration profile 2. `desktop.plist` 3. `registry.json` 4. `admin-settings.json`
Linux	1. `registry.json` 2. `admin-settings.json`

Lower-precedence methods are not consulted once a higher one applies. For example, on a Mac with both a configuration profile and a registry.json file, only the organization namespaces in the configuration profile are enforced.

Deploying an admin-settings.json file enforces sign-in on its own, even if the file contains no organization list. Users who aren't on a Docker Business subscription see the sign-in prompt, and the Docker Engine is held until they sign in.

This differs from the four methods above in two ways:

It doesn't restrict sign-in to particular organizations, so any Docker account satisfies it. Combine it with one of the methods above if you need organization membership enforced.
It's the lowest-precedence method, so any of the methods above overrides it.

If you use Settings Management, account for this when planning your rollout: developers who are signed out will be prompted to sign in as soon as the file reaches their machine and Docker Desktop restarts.

If sign-in enforcement doesn't work:

Verify file locations and permissions
Check that each value is your Docker Hub organization namespace, not the organization display name. Namespaces use lowercase letters only and matching is case-sensitive, so a mismatch signs out every user
If users authenticate successfully and are then signed out with a membership error that cites a display name or mixed-case string, update allowedOrgs, ALLOWEDORG, or --allowed-org to the organization namespace and restart Docker Desktop
Check for stray whitespace in the value. In the Windows registry key, put each namespace on its own line rather than separating them with spaces or commas
Check whether a higher-precedence method is in effect. See Method precedence
Restart Docker Desktop or reboot the system. Docker Desktop doesn't pick up new configuration while running
Confirm users are members of the specified organizations
Update Docker Desktop to the latest version

If enforcement works but developers report that the Docker CLI stopped working, that's expected. See Impact on the Docker CLI.

What can I help you with?

Configure sign-in enforcement