This post, written by our partner JFrog, outlines how to work with JFrog Artifactory and Docker Desktop.
Many companies utilize JFrog Artifactory as a Docker and Helm registry but also utilize Docker Desktop strategically to manage their container services.
In this article, we explain how to configure Docker Desktop to work with JFrog Artifactory as your Docker registry to manage the push and pull of container images across your company’s repositories (such as local, remote, and virtual). We also show how JFrog Artifactory, in conjunction with Docker Desktop, gives users fine-grained control over the movement of Docker images across their portfolio.
Before you begin
For this walkthrough, you’ll need to have the following items already set up:
- An active Docker Desktop account through your company
- An active trial or subscription to the JFrog Platform
Linking Docker Desktop with JFrog Artifactory
To get started on your Docker Desktop and JFrog software supply chain platform journey, we will assume that Artifactory is your chosen container registry.
You also may have standardized on Docker Desktop and want to use it as the control plane for moving containers in your organization. To do so, you’ll want to be sure everything is appropriately configured to allow access to Artifactory in the Docker Desktop services.
The Registry Access Management feature in Docker Desktop helps ensure that only permitted repos and repository types (such as Artifactory local, remote, or virtual repos) are appropriately accessible to be managed by Docker Desktop and that you have applied all permissions according to your company’s access rules.
A best practice is not to allow unfettered access to your repos and container images, so let’s make sure Artifactory is correctly set up to connect to your selected Docker Desktop services.
Use the following steps to configure Artifactory as an allowed registry in Docker Hub. (These instructions are also found in the official documentation.) Note that the Registry Access Management feature can manage both cloud and on-premises JFrog Artifactory instances.
- Sign in to your Docker Hub account as an organization owner.
- Select an organization, then navigate to the Settings tab on the Organizations page and select Registry Access Management (Figure 1).
- Select Enabled in Registry Access Management to begin setting the permissions for your Artifactory registry.
- Add Artifactory to your list by selecting Add and entering your registry details in the applicable field. Then select Create.
- Verify that Artifactory appears in your registry list and select Save & Apply.
- You can verify that your changes are saved in the Activity tab. Note that you can add unlimited registries.
Applying access universally
Next, suppose you want to be sure all your developers using Artifactory cannot mistakenly access certain repos or certain pipelines. To do so, you’ll need to apply access rules across your organization in Docker Desktop. Company IT departments can apply these settings to everyone in your organization, or individual developers can configure this manually, depending on your business rules and operational preferences (as shown in the official docs).
Configure registry.json to enforce sign-in
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 is a configuration file that allows administrators to specify the Docker organization the user must belong to. It ensures that your settings apply to the user’s session and can therefore access registries like Artifactory with your company’s rules in place. The Docker Desktop installer reads the `registry.json` for this file on the users’ machines as part of the installation process.
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 an organization other than the one listed in the
registry.json file, they will be denied access to Docker Desktop.
registry.json file and forcing users to authenticate is highly recommended but not required. Forced authentication has 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 of Artifactory have unlimited pulls from Docker Hub and do not have to worry about rate limits
- 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 your operating system, you must create a
registry.json file at the following locations and make sure the file can’t be edited by the user:
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.
In Docker Hub, you can now 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.
Note: For other methods of creating the
registry.json file for your organization based on your operating system, please see the Docker Desktop documentation.
Testing Docker and Artifactory
Now, you need to ensure everything is working properly and that your developers cannot access things they shouldn’t (thereby exposing the business), and that they can also access all the registries they need.
Verify your global changes
After you’ve created the
registry.json file and deployed it onto the users’ machines, you can verify whether the access changes have taken effect by asking users to start Docker Desktop to access Artifactory.
If the configuration is successful, Docker Desktop will prompt 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. And, in this case, they will not be able to access Artifactory as their registry.
Give it a test
A quick way to ensure everything is configured correctly is for developers to attempt to access a repository that is not in the allow list that has just been created. If the system won’t allow access to it, you know you did it right. If developers are able to access a non-listed repository, double-check the steps above to ensure all settings are correct.
You’re done! If you’re successful in your setup, your developers and admins should be shown a screen like that in Figure 2, indicating access to both Docker Hub and chosen JFrog Artifactory repos. Now you can use Docker Desktop features to control your registries smoothly, as well as take advantage of unlimited Docker Hub pulls for JFrog customers.