Enforce sign-in for Desktop
By default, members of your organization can use Docker Desktop on their machines without signing in to any Docker account. To ensure that a user signs in to a Docker account that is a member of your organization and that the
organization’s settings apply to the user’s session, you can use a registry.json
file.
The registry.json
file is a configuration file that allows administrators to specify the Docker organization the user must belong to and ensure that the organization’s settings apply to the user’s session. The Docker Desktop installer can create this file on the users’ machines as part of the installation process.
After a registry.json
file is configured on a user’s machine, Docker Desktop prompts the user to sign in. If a user doesn’t sign in, or tries to sign in using a different organization, other than the organization listed in the registry.json
file, they will be denied access to Docker Desktop.
Deploying a registry.json
file and forcing users to authenticate is not required, but offers the following benefits:
- Allows administrators to configure features such as
Image Access Management which allows team members to:
- Only have access to Trusted Content on Docker Hub
- Pull only from the specified categories of images
- Authenticated users get a higher pull rate limit compared to anonymous users. For example, if you are authenticated, you get 200 pulls per 6 hour period, compared to 100 pulls per 6 hour period per IP address for anonymous users. For more information, see Download rate limit.
- Blocks users from accessing Docker Desktop until they are added to a specific organization.
Create a registry.json file
Before creating a registry.json
file, ensure that the user is a member of
at least one organization in Docker Hub. If the registry.json
file matches at
least one organization the user is a member of, they can sign in to Docker
Desktop and access all their organizations.
Based on the user's operating system, you must create a registry.json
file at the following location and make sure the file can't be edited by the user:
Platform | Location |
---|---|
Windows | /ProgramData/DockerDesktop/registry.json |
Mac | /Library/Application Support/com.docker.docker/registry.json |
Linux | /usr/share/docker-desktop/registry/registry.json |
The registry.json
file must contain the following contents, where myorg
is replaced with your organization's name. The file contents are case-sensitive and you must use lowercase letters for your organization's name.
{
"allowedOrgs": ["myorg"]
}
In Docker Hub, you can download the registry.json
file for your organization or copy the specific commands to create the file for your organization. To download the file or copy the commands from Docker Hub:
- Log in to Docker Hubopen_in_new as an organization owner.
- Go to Organizations > Your Organization > Settings.
- Select Enforce Sign-in and continue with the on-screen instructions for Windows, Mac, or Linux.
Alternatively, you can use the following methods to create a registry.json
file based on the user's operating system.
Windows
On Windows, you can use the following methods to create a registry.json
file.
Create registry.json when installing Docker Desktop on Windows
To automatically create a registry.json
file when installing Docker Desktop, download Docker Desktop Installer.exe
and run one of the following commands from the directory containing Docker Desktop Installer.exe
. Replace myorg
with your organization's name and you must use lowercase letters for your organization's name.
If you're using PowerShell:
PS> Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg'
If you're using the Windows Command Prompt:
C:\Users\Admin> "Docker Desktop Installer.exe" install --allowed-org=myorg
Create registry.json manually on Windows
To manually create a registry.json
file, run the following PowerShell command as an Admin and replace myorg
with your organization's name. The file contents are case-sensitive and you must use lowercase letters for your organization's name.
PS> Set-Content /ProgramData/DockerDesktop/registry.json '{"allowedOrgs":["myorg"]}'
This creates the registry.json
file at C:\ProgramData\DockerDesktop\registry.json
and includes the organization information the user belongs to. Make sure this file can't be edited by the user, only by the administrator:
PS C:\ProgramData\DockerDesktop> Get-Acl .\registry.json
Directory: C:\ProgramData\DockerDesktop
Path Owner Access
---- ----- ------
registry.json BUILTIN\Administrators NT AUTHORITY\SYSTEM Allow FullControl...
Mac
On Mac, you can use the following methods to create a registry.json
file.
Create registry.json when installing Docker Desktop on Mac
To automatically create a registry.json file when installing Docker Desktop, download Docker.dmg
and run the following commands in a terminal from the directory containing Docker.dmg
. Replace myorg
with your organization's name and you must use lowercase letters for your organization's name.
$ sudo hdiutil attach Docker.dmg
$ sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg
$ sudo hdiutil detach /Volumes/Docker
Create registry.json manually on Mac
To manually create a registry.json
file, run the following commands in a terminal
and replace myorg
with your organization's name. The file contents are case-sensitive and you must use lowercase letters for your organization's name.
$ sudo mkdir -p "/Library/Application Support/com.docker.docker"
$ echo '{"allowedOrgs":["myorg"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json"
This creates (or updates, if the file already exists) the registry.json
file
at /Library/Application Support/com.docker.docker/registry.json
and includes
the organization information the user belongs to. Make sure the file has the
expected content and can't be edited by the user, only by the administrator.
Verify that the content of the file contains the correct information:
$ sudo cat "/Library/Application Support/com.docker.docker/registry.json"
{"allowedOrgs":["myorg"]}
Verify that the file has the expected permissions (-rw-r--r--
) and ownership
(root
and admin
):
$ 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
Linux
On Linux, you can use the following methods to create a registry.json
file.
Create registry.json manually on Linux
To manually create a registry.json
file, run the following commands in a terminal
and replace myorg
with your organization's name. The file contents are case-sensitive and you must use lowercase letters for your organization's name.
$ sudo mkdir -p /usr/share/docker-desktop/registry
$ echo '{"allowedOrgs":["myorg"]}' | sudo tee /usr/share/docker-desktop/registry/registry.json
This creates (or updates, if the file already exists) the registry.json
file
at /usr/share/docker-desktop/registry/registry.json
and includes
the organization information to which the user belongs. Make sure the file has the
expected content and can't be edited by the user, only by root.
Verify that the content of the file contains the correct information:
$ sudo cat /usr/share/docker-desktop/registry/registry.json
{"allowedOrgs":["myorg"]}
Verify that the file has the expected permissions (-rw-r--r--
) and ownership
(root
):
$ 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
Deploy registry.json to multiple devices
The previous instructions explain how to create and deploy a registry.json file to a single device. To automatically deploy the registry.json to multiple devices, you must use a third-party solution, such as a mobile device management solution. You can use the previous instructions along with your third-party solution to remotely deploy the registry.json file, or remotely install Docker Desktop with the registry.json file. For more details, see the documentation of your third-party solution.
Verify the changes
After you’ve created the registry.json
file and deployed it onto the users’ machines, you can verify whether the changes have taken effect by asking users to start Docker Desktop.
If the configuration is successful, Docker Desktop prompts the user to authenticate using the organization credentials on start. If the user fails to authenticate, they will see an error message, and they will be denied access to Docker Desktop.