security: account association

.markdownlint.json

@@ -13,7 +13,7 @@
   "no-space-in-code": true,
   "no-space-in-links": true,
   "no-empty-links": true,
-  "ol-prefix": {"style": "ordered"},
+  "ol-prefix": {"style": "one_or_ordered"},
   "no-reversed-links": true,
   "reference-links-images": {
     "shortcut_syntax": false

content/manuals/security/_index.md

@@ -31,10 +31,18 @@ grid_admins:
   description: Configure sign-in for members of your teams and organizations.
   link: /security/for-admins/enforce-sign-in/
   icon: passkey
+- title: Domain management
+  description: Learn how to manage domains and users in the Admin Console.
+  link: /security/for-admins/domain-management/
+  icon: domain_verification
 - title: Domain audit
   description: Identify uncaptured users in your organization.
   link: /security/for-admins/domain-audit/
   icon: person_search
+- title: Manage unassociated machines
+  description: Learn how to manage unassociated machines using the Docker Admin Console.
+  link: /security/for-admins/unassociated-machines/
+  icon: desktop_windows
 - title: Docker Scout
   description: Explore how Docker Scout can help you create a more secure software supply chain.
   icon: query_stats

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

@@ -0,0 +1,185 @@
+---
+title: Manage unassociated machines
+description: Learn how to manage unassociated machines using the Docker Admin Console
+keywords: unassociated machines, insights, manage users, enforce sign-in
+weight: 56
+---
+
+Docker administrators can identify, view, and manage Docker Desktop machines
+that should be associated with their organization but aren't currently linked
+to user accounts. This self-service capability helps you understand Docker
+Desktop usage across your organization and streamline user onboarding without
+IT involvement.
+
+## Prerequisites
+
+- Docker Business subscription
+- Organization owner access to your Docker organization
+
+## About unassociated machines
+
+Docker Desktop machines in your organization may be:
+
+- Associated: The user has signed in to Docker Desktop and is a member of
+your organization
+- Unassociated: Docker has identified machines likely belonging to your
+organization based on usage patterns, but the users haven't signed in or
+joined your organization
+
+## How Docker identifies unassociated machines
+
+Docker uses telemetry data to identify which machines belong to your
+organization:
+
+- Private registry usage: Machines accessing your organization's private
+container registries
+- Domain matching: Users signed in with email domains associated with your
+organization
+- Registry patterns: Analysis of container registry access patterns that
+indicate organizational usage
+
+## View unassociated machines
+
+To see detailed information about unassociated machines:
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+
+The machine list displays:
+
+- Machine ID (Docker-generated identifier)
+- Registry addresses accessed (when available)
+- User email
+- Docker Desktop version
+- Last activity date
+- Sign-in enforced status
+
+You can:
+
+- Export the list as CSV
+- Take actions on individual or multiple machines
+
+## Add unassociated machines to your organization
+
+You can add unassociated machines by:
+- [Auto-provisiong](/manuals/security/for-admins/domain-management.md#auto-provisioning)
+- [SSO user provisioning](/manuals/security/for-admins/provisioning/_index.md)
+- [Manually adding them](#add-unassociated-machines-to-your-organization)
+
+> [!NOTE]
+>
+> If you add users and do not have enough seats in your organization, a
+pop-up will appear prompting you to **Get more seats**.
+
+### Add individual users
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+1. Locate the machine you want to add to your organization.
+1. Select the **Actions** menu and choose **Add to organization**.
+1. In the pop-up modal, select **Add user**.
+
+### Bulk add users
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+1. Use the **checkboxes** to select the machines you want to add to your
+organizations.
+1. Select the **Add to organization** button.
+1. In the pop-up modal, select **Add users** to confirm.
+
+## Enable sign-in enforcement
+
+### Enable for all unassociated machines
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+1. Turn on the **Require sign-in** toggle.
+1. In the pop-up modal, select **Require sign-in** to confirm.
+
+The **Sign-in required** status will update for all unassociated machines to
+**Yes**.
+
+> [!NOTE]
+>
+> Sign-in enforcement requires Docker Desktop version 4.37 or later. If you
+enable enforcement for a user with an older version, their status shows
+as **Pending** until they update Docker Desktop.
+
+### Enable for individual unassociated machines
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+1. Locate the machine you want to enable sign-in enforcement for.
+1. Select the **Actions** menu and choose **Turn on sign-in enforcement**.
+1. In the pop-up modal, select **Require sign-in** to confirm.
+
+The **Sign-in required** status will update for the individual machine to
+**Yes**.
+
+> [!NOTE]
+>
+> Sign-in enforcement works with Docker Desktop versions 4.37 and later. If you
+enable sign-in enforcement for a user using an older version of Docker Desktop,
+their **Sign-in required** status will display as **Pending**.
+
+## Disable sign-in enforcement
+
+### Disable for all unassociated machines
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+1. Turn off the **Require sign-in** toggle.
+1. In the pop-up modal, select **Turn off sign-in** to confirm.
+
+The **Sign-in required** status will update for all unassociated machines to
+**No**.
+
+### Disable for specific unassociated machines
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin) and select
+your organization.
+1. In **User management**, select **Unassociated**.
+1. Locate the machine you want to disable sign-in enforcement for.
+1. Select the **Actions** menu and choose **Turn off sign-in enforcement**.
+1. In the pop-up modal, select **Turn off sign-in** to confirm.
+
+The **Sign-in required** status will update for the individual machine to
+**No**.
+
+## Developer experience
+
+Sign in enforcement only takes effect after a Docker Desktop restart. The
+following sections outline the developer experience after sign in is enforced
+and Docker Desktop is restarted.
+
+### First time sign in on enforced machine
+
+When a user opens Docker Desktop on an enforced machine, they see a sign-in
+prompt explaining that their organization requires authentication. After
+signing in, users can continue using Docker Desktop immediately.
+
+> [!NOTE]
+>
+> Sign-in enforcement only takes effect after Docker Desktop is restarted.
+
+### After sign in
+
+Once users sign in to enforced machines:
+
+- With verified domains and auto-provisioning enabled: Users are automatically
+added to your organization. For more information on verifying a domain and
+enabling auto-provisioning, see [Domain management](/manuals/security/for-admins/domain-management.md).
+- Without auto-provisioning: User emails appear in your the machines management
+view for manual review and addition. To add a user to your organization,
+see [Add unassociated machines to your organization](#add-unassociated-machines-to-your-organization).
+
+## Troubleshooting
+
+For common issues and solutions, see [Troubleshoot unassociated machines](/manuals/security/troubleshoot/troubleshoot-unassociated-machines.md).

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

@@ -0,0 +1,185 @@
+---
+title: Troubleshoot unassociated machines
+description: Learn how to troubleshoot common unassociated account issues.
+keywords: unassociated machines, unassociated accounts, troubleshoot
+tags: [Troubleshooting]
+toc_max: 2
+---
+
+If you experience issues with unassociated machine management, refer to the
+following solutions.
+
+## Machine incorrectly identified as belonging to your organization
+
+### Possible causes
+
+- Docker's machine identification algorithm incorrectly associated the machine
+with your organization based on registry usage patterns
+- A contractor or temporary user accessed your organization's registries from
+a personal machine
+- Shared or public registries created false associations
+
+### Affected environments
+
+- All Docker Desktop versions
+- All operating systems
+
+### Solution
+
+Docker can add incorrectly identified machines to an ignore list to prevent
+future appearances.
+
+[Contact Docker Support](https://hub.docker.com/support/contact) and provide:
+
+- The machine ID
+- The reason for why the machine doesn't belong to your organization
+
+## Users cannot sign in to Docker Desktop after enforcement
+
+### Error message
+
+```txt
+Sign-in required by your organization
+```
+
+### Possible causes
+
+- User is running an outdated version of Docker Desktop that doesn't support
+sign-in enforcement
+- Network connectivity issues preventing authentication
+- User is attempting to sign in with an incorrect email address
+
+### Affected environments
+
+- Docker Desktop versions before 4.37
+- Networks with restricted internet access
+- Corporate firewalls blocking Docker authentication services
+
+### Solution
+
+1. Verify the user is running Docker Desktop version 4.37 or later.
+1. If not, have the user update to the latest version.
+1. Ensure the user has network access to Docker's authentication services:
+    - https://login.docker.com
+    - https://auth.docker.io
+1. Confirm the user is signing in with their work email address.
+
+If issues persist, temporarily disable enforcement for that specific machine
+while troubleshooting.
+
+## Machine is in unassociated list after user signs in
+
+### Possible causes
+
+- Auto-provisioning is not enabled for the user's email domain
+- The user signed in with a personal email address instead of their work email
+- There's a delay in the data refresh cycle
+
+### Affected environments
+
+- Organizations without domain auto-provisioning enabled
+- All Docker Desktop versions
+
+### Solution
+
+**Recommended solution**:
+
+1. In the [Admin Console](https://app.docker.com/admin), navigate to **User management** > **Members**
+and check if the user appears in your organization's member list.
+1. If not visible, go to **User management** > **Unassociated**.
+1. Look for the machine and verify the email address.
+1. Select the **Actions** menu and select **Add to organization**.
+
+**Alternative solution**:
+
+1. Enable [auto-provisioning](/manuals/security/for-admins/domain-management.md#auto-provisioning) for your verified domains.
+2. Ask the user to sign in again with their work email address.
+3. The user will be automatically added to your organization.
+
+## Unassociated machines count seems inaccurate
+
+### Possible causes
+
+- Docker Desktop instances are shared between multiple users
+- Users have multiple Docker Desktop installations (personal and work machines)
+- Data collection limitations due to network restrictions or opt-outs
+
+### Affected environments
+
+- Shared workstations or virtual desktop infrastructure (VDI)
+- Air-gapped or restricted network environments
+- Organizations with users who have opted out of telemetry
+
+### Solution
+
+Review the machine list to identify patterns:
+
+- Multiple recent activities from the same machine ID may indicate sharing.
+- Consider the registry access patterns show in the **Unassociated** page of
+the Admin Console.
+- For shared machines, enforce sign-in and add users as they authenticate.
+- For air-gapped environments, consider implementing centralized Docker Desktop
+configuration.
+
+> [!NOTE]
+>
+> Docker achieves approximately 97% accuracy in machine identification.
+A ~3% variance is expected and normal.
+
+## Sign-in enforcement not working for some machines
+
+### Possible causes
+
+- Machines are running Docker Desktop versions that don't support enforcement
+- Users haven't restarted Docker Desktop since enforcement was enabled
+- Network issues preventing the enforcement check
+
+### Steps to replicate
+
+1. Enable sign-in enforcement for a machine.
+1. User opens Docker Desktop.
+1. View the result:
+    - Expected result: Sign-in prompt appears
+    - Actual result: No prompt, Docker Desktop works normally
+
+### Solution
+
+1. Verify the machine is running Docker Desktop 4.37 or later. If not,
+have the user upgrade to the latest version.
+1. Ask the user to restart Docker Desktop completely.
+1. Check that the machine ID matches the one in your enforcement list.
+1. If the issue persists, disable and re-enable enforcement for that specific
+machine.
+
+## Auto-provisioning not working after sign-in enforcement
+
+### Possible causes
+
+- Domain auto-provisioning is not enabled
+- User signed in with an unverified domain
+- Organization has reached its seat limit
+
+### Affected environments
+
+- Organizations without verified domains
+- Organizations at seat capacity
+
+### Solution
+
+**Recommended solution**:
+
+Verify domain auto-provisioning is enabled:
+
+1. In the [Admin Console](https://app.docker.com/admin), select **Domain management**
+and confirm auto-provisioning is enabled.
+1. Ensure the user's email domain is associated with your verified domain.
+
+Check organization seat usage:
+
+1. If at capacity, purchase additional seats or remove inactive users.
+1. Manually add the user if you can't enable auto-provisioning.
+
+**Alternative solution**:
+
+1. Set up [Single Sign-On (SSO)](/manuals/security/for-admins/single-sign-on/_index.md).
+1. Enable [Just-in-Time (JIT)](/manuals/security/for-admins/provisioning/just-in-time.md) provisioning through your SSO configuration.