mirror of https://github.com/docker/docs.git
hub: update enforce sign-in (#18306)
* update enforce sign in --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com> Co-authored-by: Stephanie Aurelio <133041642+stephaurelio@users.noreply.github.com>
This commit is contained in:
Craig Osterhout
GitHub
parent
d7e8a0cfd1
commit
108259a920
|
|
@ -5,29 +5,231 @@ keywords: authentication, registry.json, configure,
|
|||
title: 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.
|
||||
By default, members of your organization can use Docker Desktop without signing
|
||||
in. When users don’t sign in as a member of your organization, they don’t
|
||||
receive the [benefits of your organization’s
|
||||
subscription](../subscription/details.md) and they can circumvent [Docker’s
|
||||
security features](../desktop/hardened-desktop/_index.md) for your organization.
|
||||
|
||||
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.
|
||||
To ensure members of your organization always sign in, you can deploy a
|
||||
`registry.json` configuration file to the machines of your users.
|
||||
|
||||
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.
|
||||
## How is sign-in enforced?
|
||||
|
||||
Deploying a `registry.json` file and forcing users to authenticate is not required, but offers the following benefits:
|
||||
When Docker Desktop starts and it detects a `registry.json` file, the
|
||||
following occurs:
|
||||
|
||||
- Allows administrators to configure features such as [Image Access Management](image-access-management.md) 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](download-rate-limit.md).
|
||||
- Blocks users from accessing Docker Desktop until they are added to a specific organization.
|
||||
- The following **Sign in required!** prompt appears requiring the user to sign
|
||||
in as a member of your organization to use Docker Desktop. 
|
||||
- When a user signs in to an account that isn’t a member of your organization,
|
||||
they will be automatically signed out and can’t use Docker Desktop. The user
|
||||
can select **Sign in** and try again.
|
||||
- When a user signs in to an account that is a member of your organization, they
|
||||
can use Docker Desktop.
|
||||
- When a user signs out, the **Sign in required!** prompt appears and they can
|
||||
no longer use Docker Desktop.
|
||||
|
||||
{{< include "configure-registry-json.md" >}}
|
||||
> **Enforcing Single Sign-On (SSO)**
|
||||
>
|
||||
> Enforcing sign-in to Docker Desktop isn't the same as enforcing SSO. To ensure
|
||||
> that your users always sign in using their SSO credentials, you must also
|
||||
> enforce SSO. For more details, see [Single Sign-On
|
||||
> overview](../single-sign-on/_index.md).
|
||||
|
||||
|
||||
## Create a registry.json file to enforce sign-in
|
||||
|
||||
1. Ensure that the user is a member of your organization in Docker. For more
|
||||
details, see [Manage members](https://docs.docker.com/docker-hub/members/).
|
||||
|
||||
2. Create the `registry.json` file.
|
||||
|
||||
Based on the user's operating system, create a file named `registry.json` 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 |
|
||||
|
||||
3. Specify your organization in the `registry.json` file.
|
||||
|
||||
Open the `registry.json` file in a text editor and add 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.
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"allowedOrgs": ["myorg"]
|
||||
}
|
||||
```
|
||||
|
||||
4. Verify that sign-in is enforced.
|
||||
|
||||
Start Docker Desktop on the user’s machine and verify that the **Sign in
|
||||
required!** prompt appears.
|
||||
|
||||
## Alternative methods to create a registry.json file
|
||||
|
||||
You can also use the following alternative methods to create a `registry.json` file.
|
||||
|
||||
### Download a registry.json file from Docker Hub
|
||||
|
||||
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, use the following steps.
|
||||
|
||||
1. Sign in to [Docker Hub](http://hub.docker.com/) as an organization owner.
|
||||
|
||||
2. Go to **Organizations** > ***Your Organization*** > **Settings**.
|
||||
|
||||
3. Select **Enforce Sign-in** and continue with the on-screen instructions for
|
||||
Windows, Mac, or Linux.
|
||||
|
||||
### Create a registry.json file when installing Docker Desktop
|
||||
|
||||
To create a `registry.json` file when installing Docker Desktop, use the following instructions based on your user's operating system.
|
||||
|
||||
{{< tabs >}}
|
||||
{{< tab name="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:
|
||||
|
||||
```powershell
|
||||
PS> Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg'
|
||||
```
|
||||
|
||||
If you're using the Windows Command Prompt:
|
||||
|
||||
```console
|
||||
C:\Users\Admin> "Docker Desktop Installer.exe" install --allowed-org=myorg
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< tab name="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.
|
||||
|
||||
```console
|
||||
$ sudo hdiutil attach Docker.dmg
|
||||
$ sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg
|
||||
$ sudo hdiutil detach /Volumes/Docker
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
### Create a registry.json file using the command line
|
||||
|
||||
To create a `registry.json` using the command line, use the following instructions based on your user's operating system.
|
||||
|
||||
{{< tabs >}}
|
||||
{{< tab name="Windows" >}}
|
||||
|
||||
To use the CLI to 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.
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```console
|
||||
PS C:\ProgramData\DockerDesktop> Get-Acl .\registry.json
|
||||
|
||||
|
||||
Directory: C:\ProgramData\DockerDesktop
|
||||
|
||||
|
||||
Path Owner Access
|
||||
---- ----- ------
|
||||
registry.json BUILTIN\Administrators NT AUTHORITY\SYSTEM Allow FullControl...
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< tab name="Mac" >}}
|
||||
|
||||
To use the CLI to 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.
|
||||
|
||||
```console
|
||||
$ 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:
|
||||
|
||||
```console
|
||||
$ 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`):
|
||||
|
||||
```console
|
||||
$ 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
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< tab name="Linux" >}}
|
||||
|
||||
To use the CLI to 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.
|
||||
|
||||
```console
|
||||
$ 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:
|
||||
|
||||
```console
|
||||
$ 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`):
|
||||
|
||||
```console
|
||||
$ 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
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
## 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.
|
||||
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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 138 KiB |
|
|
@ -1,165 +0,0 @@
|
|||
## 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.
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
1. Log in to [Docker Hub](http://hub.docker.com) as an organization owner.
|
||||
2. Go to **Organizations** > **_Your Organization_** > **Settings**.
|
||||
3. 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.
|
||||
|
||||
{{< tabs >}}
|
||||
{{< tab name="Windows" >}}
|
||||
|
||||
### 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:
|
||||
|
||||
```powershell
|
||||
PS> Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg'
|
||||
```
|
||||
|
||||
If you're using the Windows Command Prompt:
|
||||
|
||||
```console
|
||||
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.
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```console
|
||||
PS C:\ProgramData\DockerDesktop> Get-Acl .\registry.json
|
||||
|
||||
|
||||
Directory: C:\ProgramData\DockerDesktop
|
||||
|
||||
|
||||
Path Owner Access
|
||||
---- ----- ------
|
||||
registry.json BUILTIN\Administrators NT AUTHORITY\SYSTEM Allow FullControl...
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< tab name="Mac" >}}
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
```console
|
||||
$ 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.
|
||||
|
||||
```console
|
||||
$ 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:
|
||||
|
||||
```console
|
||||
$ 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`):
|
||||
|
||||
```console
|
||||
$ 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
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< tab name="Linux" >}}
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
```console
|
||||
$ 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:
|
||||
|
||||
```console
|
||||
$ 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`):
|
||||
|
||||
```console
|
||||
$ 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
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
|
@ -51,4 +51,14 @@ However, if you **enforce** SSO:
|
|||
|
||||
* Service Account domain email addresses must be unaliased and enabled in their IdP
|
||||
* Username/password and personal access token will still work (but only if they exist, which they won't for new accounts)
|
||||
* Those who know the IdP credentials can sign in as that Service Account through SSO on Hub and create or change the personal access token for that service account.
|
||||
* Those who know the IdP credentials can sign in as that Service Account through SSO on Hub and create or change the personal access token for that service account.
|
||||
|
||||
### Is enforcing Single Sign-On the same as enforcing sign-in to Docker Desktop?
|
||||
|
||||
No. They are different features that you can use separately or together.
|
||||
|
||||
Enforcing SSO ensures that users sign in using their SSO credentials instead of their Docker ID. One of the benefits is that SSO enables you to better manage user credentials.
|
||||
|
||||
Enforcing sign-in to Docker Desktop ensures that users always sign in to an
|
||||
account that's a member of your organization. The benefits are that your organization's security settings are always applied to the user's session and your users always receive the benefits of your subscription. For more details, see [Enforce sign-in for Desktop](../docker-hub/configure-sign-in.md).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue