Skip to content

Commit 3135c23

Browse files
sarahsanders-dockersarahsanders-docker
committed
draft: account association
1 parent 52ac823 commit 3135c23

File tree

2 files changed

+326
-0
lines changed

2 files changed

+326
-0
lines changed

‎content/manuals/security/for-admins/unassociated-machines.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Manage unassociated machines
3+
description: Learn how to manage unassociated machines using the Docker Admin Console
4+
keywords: unassociated machines, insights, manage users, enforce sign-in
5+
weight: 56
6+
---
7+
8+
Docker administrators can identify, view, and manage Docker Desktop machines
9+
that should be associated with their organization but aren't currently linked
10+
to user accounts. This self-service capability helps you understand Docker
11+
Desktop usage across your organization and streamline user onboarding without
12+
IT involvement.
13+
14+
## Prerequisites
15+
16+
- Docker Business subscription
17+
- Organization owner access to your Docker organization
18+
19+
## About unassociated machines
20+
21+
Docker Desktop machines in your organization may be:
22+
23+
- Associated: The user has signed in to Docker Desktop and is a member of
24+
your organization
25+
- Unassociated: Docker has identified machines likely belonging to your
26+
organization based on usage patterns, but the users haven't signed in or
27+
joined your organization
28+
29+
## How Docker identifies unassociated machines
30+
31+
Docker uses telemetry data to identify which machines belong to your
32+
organization:
33+
34+
- Private registry usage: Machines accessing your organization's private
35+
container registries
36+
- Domain matching: Users signed in with email domains associated with your
37+
organization
38+
- Registry patterns: Analysis of container registry access patterns that
39+
indicate organizational usage
40+
41+
## View unassociated machines
42+
43+
### In the Insights dashboard
44+
45+
The Insights dashboard shows high-level metrics for both associated and
46+
unassociated machines:
47+
48+
1. Navigate to your organization in Docker Hub.
49+
2. Go to the Insights tab.
50+
3. View the summary of:
51+
- Total active users (associated + unassociated)
52+
- Associated organization members
53+
- Unassociated machines detected
54+
55+
> [!NOTE]
56+
>
57+
> Full Insights dashboard features become available when you enable
58+
sign-in enforcement for your organization.
59+
60+
For more information, see [Insights](/manuals/admin/organization/insights.md).
61+
62+
### In the machines management view
63+
64+
To see detailed information about unassociated machines:
65+
66+
1. Navigate to your organization in Docker Hub.
67+
2. Go to Settings > General.
68+
3. Select Unassociated machines.
69+
70+
The machine list displays:
71+
72+
- Machine ID (Docker-generated identifier)
73+
- Registry addresses accessed (when available)
74+
- Last activity date
75+
- Docker Desktop version
76+
- User email (after sign-in enforcement)
77+
78+
You can:
79+
80+
- Export the list as CSV
81+
- Filter and sort machines by activity
82+
- Take actions on individual or multiple machines
83+
84+
## Manage unassociated machines
85+
86+
### Enable sign-in enforcement
87+
88+
You can require users to sign in to Docker Desktop.
89+
90+
For all unassociated machines:
91+
92+
1. In your organization settings, go to Unassociated machines.
93+
2. Select Enforce sign-in for all machines.
94+
3. Confirm the action.
95+
96+
For specific machines:
97+
98+
1. In the unassociated machines list, select individual machines.
99+
2. Choose Require sign-in from the actions menu.
100+
101+
### Manually add users
102+
103+
To manually add users:
104+
105+
1. Go to Settings > General > Unassociated machines.
106+
2. Review users who have signed in (identified by email addresses).
107+
3. Select users to add to your organization.
108+
4. Choose Add to organization.
109+
110+
## User experience
111+
112+
Sign in enforcement only take effect after a Docker Desktop restart. The
113+
following sections outline the user experience after sign in is enforced
114+
and Docker Desktop restarted.
115+
116+
### First time sign in on enforced machine
117+
118+
When a user opens Docker Desktop on an enforced machine:
119+
120+
1. They see a customizable prompt explaining that their organization requires
121+
sign-in.
122+
2. The prompt includes information that their email will be shared with
123+
organization administrators.
124+
3. Users can continue using Docker Desktop immediately after signing in.
125+
4. Users are not blocked based on license availability.
126+
127+
### After sign in
128+
129+
Once users sign in to enforced machines:
130+
131+
- With verified domains and auto-provisioning enabled: Users are automatically
132+
added to your organization.
133+
- For more information on verifying a domain and enabling auto-provisioning,
134+
see [Domain management](/manuals/security/for-admins/domain-management.md).
135+
- Without auto-provisioning: User emails appear in your the machines management
136+
view for manual review and addition.
137+
138+
## Troubleshooting
139+
140+
For common issues and solutions, see [Troubleshoot unassociated machines](/manuals/security/troubleshoot/troubleshoot-unassociated-machines.md).

‎content/manuals/security/troubleshoot/troubleshoot-unassociated-machines.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: Troubleshoot unassociated machines
3+
description: Learn how to troubleshoot common unassociated account issues.
4+
keywords: unassociated machines, unassociated accounts, troubleshoot
5+
tags: [Troubleshooting]
6+
toc_max: 2
7+
---
8+
9+
If you experience issues with unassociated machine management, refer to the
10+
following solutions.
11+
12+
## Machine incorrectly identified as belonging to your organization
13+
14+
### Possible causes
15+
16+
- Docker's machine identification algorithm incorrectly associated the machine
17+
with your organization based on registry usage patterns
18+
- A contractor or temporary user accessed your organization's registries from
19+
a personal machine
20+
- Shared or public registries created false associations
21+
22+
### Affected environments
23+
24+
- All Docker Desktop versions
25+
- All operating systems
26+
27+
### Solution
28+
29+
Docker can add incorrectly identified machines to an ignore list to prevent
30+
future appearances.
31+
32+
[Contact Docker Support](https://hub.docker.com/support/contact) and provide:
33+
34+
- The machine ID
35+
- The reason for why the machine doesn't belong to your organization
36+
37+
## Users cannot sign in to Docker Desktop after enforcement
38+
39+
### Error message
40+
41+
```txt
42+
Sign-in required by your organization
43+
```
44+
45+
### Possible causes
46+
47+
- User is running an outdated version of Docker Desktop that doesn't support
48+
sign-in enforcement
49+
- Network connectivity issues preventing authentication
50+
- User is attempting to sign in with an incorrect email address
51+
52+
### Affected environments
53+
54+
- Docker Desktop versions before 4.37
55+
- Networks with restricted internet access
56+
- Corporate firewalls blocking Docker authentication services
57+
58+
### Solution
59+
60+
1. Verify the user is running Docker Desktop version 4.37 or later.
61+
2. If not, update to the latest version.
62+
3. Ensure network access to Docker's authentication services:
63+
- https://login.docker.com
64+
- https://auth.docker.io
65+
4. Confirm the user is signing in with their work email address.
66+
67+
If issues persist, temporarily disable enforcement for that specific machine
68+
while troubleshooting.
69+
70+
## Machine remains in unassociated list after user signs in
71+
72+
### Possible causes
73+
74+
- Auto-provisioning is not enabled for the user's email domain
75+
- The user signed in with a personal email address instead of their work email
76+
- There's a delay in the data refresh cycle
77+
78+
### Affected environments
79+
80+
- Organizations without domain auto-provisioning enabled
81+
- All Docker Desktop versions
82+
83+
### Solution
84+
85+
Recommended solution:
86+
87+
1. Check if the user appears in your organization's member list
88+
2. If not visible, go to Settings > General > Unassociated machines
89+
3. Look for the machine showing an email address
90+
4. Select the machine and choose Add to organization
91+
92+
Alternative solution:
93+
94+
1. Enable auto-provisioning for your verified domains
95+
2. Ask the user to sign in again with their work email address
96+
3. The user will be automatically added to your organization
97+
98+
## Unassociated machines count seems inaccurate
99+
100+
### Possible causes
101+
102+
- Docker Desktop instances are shared between multiple users
103+
- Users have multiple Docker Desktop installations (personal and work machines)
104+
- Data collection limitations due to network restrictions or opt-outs
105+
106+
### Affected environments
107+
108+
- Shared workstations or virtual desktop infrastructure (VDI)
109+
- Air-gapped or restricted network environments
110+
- Organizations with users who have opted out of telemetry
111+
112+
### Solution
113+
114+
Review the machine list to identify patterns:
115+
116+
- Multiple recent activities from the same machine ID may indicate sharing
117+
- Consider the registry access patterns shown in the details
118+
- For shared machines, enforce sign-in and add users as they authenticate
119+
- For air-gapped environments, consider implementing centralized Docker Desktop
120+
configuration
121+
122+
> [!NOTE]
123+
>
124+
> Docker achieves approximately 97% accuracy in machine identification.
125+
A ~3% variance is expected and normal."
126+
127+
## Sign-in enforcement not working for some machines
128+
129+
### Possible causes
130+
131+
- Machines are running Docker Desktop versions that don't support enforcement
132+
- Users haven't restarted Docker Desktop since enforcement was enabled
133+
- Network issues preventing the enforcement check
134+
135+
### Affected environments
136+
137+
- Docker Desktop versions before 4.37
138+
- All operating systems
139+
140+
### Steps to replicate
141+
142+
1. Enable sign-in enforcement for a machine
143+
2. User opens Docker Desktop
144+
145+
- Expected result: Sign-in prompt appears
146+
- Actual result: No prompt, Docker Desktop works normally
147+
148+
### Solution
149+
150+
1. Verify the machine is running Docker Desktop 4.37 or later
151+
2. Ask the user to restart Docker Desktop completely
152+
3. Check that the machine ID matches the one in your enforcement list
153+
4. If the issue persists, disable and re-enable enforcement for that specific
154+
machine
155+
156+
## Auto-provisioning not working after sign-in enforcement
157+
158+
### Possible causes
159+
160+
- Domain auto-provisioning is not enabled
161+
- User signed in with an unverified domain
162+
- Organization has reached its seat limit
163+
164+
### Affected environments
165+
166+
- Organizations without verified domains
167+
- Organizations at seat capacity
168+
169+
### Solution
170+
171+
Recommended solution:
172+
173+
Verify domain auto-provisioning is enabled:
174+
175+
1. Go to Settings > Security > Domain management
176+
2. Ensure the user's email domain is verified and auto-provisioning is enabled
177+
178+
Check organization seat usage:
179+
180+
1. If at capacity, purchase additional seats or remove inactive users
181+
2. Manually add the user if auto-provisioning cannot be enabled
182+
183+
Alternative solution:
184+
185+
1. Set up Single Sign-On (SSO) for automatic user provisioning
186+
2. Enable Just-in-Time (JIT) provisioning through your SSO configuration

0 commit comments

Comments
 (0)