Configure registry.json to enforce sign in

Estimated reading time: 5 minutes

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 and deploy it to the users’ machines as part of the installation process.

After you deploy a registry.json file to a user’s machine, it prompts the user to sign into Docker Desktop. 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 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

When creating a registry.json file, ensure that the developer is a member of at least one organization in Docker Hub. If the registry.json file matches at least one organization the developer is a member of, they can sign in to Docker Desktop and access all their organizations.

Windows

On Windows, you can run a command in a terminal to install Docker Desktop, or you can download Docker Desktop and manually create your registry.json file.

Run the following command in a terminal to install Docker Desktop:

C:\Users\Admin> "Docker Desktop Installer.exe" install

If you’re using PowerShell, you should run it as:

PS> Start-Process '.\win\build\Docker Desktop Installer.exe' -Wait install

If using the Windows Command Prompt:

C:\Users\Admin> start /w "" "Docker Desktop Installer.exe" install

The install command accepts the following flag:

--allowed-org=<org name>

This requires the user to sign in and be part of the specified Docker Hub organization when running the application. For example:

C:\Users\Admin> "Docker Desktop Installer.exe" install --allowed-org=acmeinc

To manually create a registry.json file:

Open Windows PowerShell and select Run as Administrator.
Type the following command cd /ProgramData/DockerDesktop/
Type notepad registry.json and enter the name of the Docker Hub organization that the developer belongs to in the allowedOrgs key and click Save. For example:
```
 {
     "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 individual developer, only by the administrator.

Mac

On macOS, you can run a command in a terminal to install Docker Desktop, or you can download Docker Desktop and manually create your registry.json file.

Download Docker.dmg and run the following commands in a terminal to install Docker Desktop in the Applications folder:

$ sudo hdiutil attach Docker.dmg
$ sudo /Volumes/Docker/Docker.app/Contents/MacOS/install
$ sudo hdiutil detach /Volumes/Docker

The install command accepts the following flags:

--allowed-org=<org name>

This requires the user to sign in and be part of the specified Docker Hub organization when running the application. For example:

$ sudo hdiutil attach Docker.dmg --allowed-org=acmeinc

To manually create a registry.json file on macOS, you must create a file at /Library/Application Support/com.docker.docker/registry.json with file permissions that ensure that the developer using Docker Desktop cannot remove or edit the file (that is, only the system administrator can write to the file). The file must be of type JSON and contain the name of the Docker Hub organization names in the allowedOrgs key.

To create your registry.json file:

Navigate to VS Code or any text editor of your choice.
Enter the name of the Docker Hub organization that the developer belongs to in the allowedOrgs key and save it in your Documents. For example:
```
 {
     "allowedOrgs": ["myorg"]
 }
```
Open a new terminal and type the following command:
```
 $ sudo mkdir -p /Library/Application\ Support/com.docker.docker
```
If prompted, type your password associated with your local computer.

Type the following command:

 $ sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json

This creates the registry.json file at /Library/Application Support/com.docker.docker/registry.json and includes the organization information the user belongs to. Make sure this file can’t be edited by the individual developer, only by the administrator.

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.

authentication, registry.json, configure