Image Access Management
Image Access Management is a new feature that is a part of the Docker Business subscription. This feature allows Organization owners to control which types of images (Docker Official Images, Docker Verified Publisher Images, Community images) their developers can pull from Docker Hub.
For example, a developer, who is part of an organization, building a new containerized application could accidentally use an untrusted, community image as a component of their application. This image could be malicious and pose a security risk to the company. Using Image Access Management, the Organization owner could ensure that the developer can only access trusted content like Docker Official Images, Docker Verified Publisher Images, or the Organization’s own images, preventing such a risk.
Configure Image Access Management permissions
The following video walks you through the process of configuring Image Access Management permissions.
Detailed instructions
To configure Image Access Management permissions, perform the following steps:
- Log into your Docker Hub account as an organization administrator.
-
Select an organization, and navigate to the Settings tab on the Organizations page and click Org Permissions.
- Enable Image Access Management to set the permissions for the following categories of images you can manage:
- Organization Images: When Image Access Management is enabled, images from your organization are always allowed. These images can be public or private created by members within your organization.
- Docker Official Images: A curated set of Docker repositories hosted on Hub. They provide OS repositories, best practices for Dockerfiles, drop-in solutions, and applies security updates on time.
- Docker Verified Publisher Images: published by Docker partners that are part of the Verified Publisher program and are qualified to be included in the developer secure supply chain. You can set permissions to Allowed or Restricted.
- Community Images: Images are always disabled when Image Access Management is enabled. These images are not trusted because various Docker Hub users contribute them and pose security risks.
Note
Image Access Management is set to Disabled by default. However, member(s) of the
owners
Team in your Organization have access to all images regardless of the settings. - Select the category restrictions for your images by clicking Allowed.
- Once the restrictions are applied, your members can view the Org permissions page in a read-only format.
Enforce authentication
To ensure that each org member uses images in a safe and secure environment, you can perform the following steps below to enforce sign-in under your organization. To do this:
- Download the latest version of Docker Desktop, and then
- Create a
registry.json
file.
Download Docker Desktop 4.0 or a later release.
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 Hub 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
Verify the restrictions
To confirm that the restrictions are successful, have each org member pull an image onto their local computer after signing into Docker Desktop. If they are unable to sign in, they will receive an error message.
For example, if you enable Image Access Management, your members can pull an Organization Image, Docker Official Image, or Verified Publisher Image onto their local machine. If you disable the restrictions, your members can pull any image, including Community Images.