Skip to content

Commit 4f24779

Browse files
sarahsanders-dockersarahsanders-docker
committed
guides: add security guide
1 parent f456066 commit 4f24779

File tree

6 files changed

+573
-0
lines changed

6 files changed

+573
-0
lines changed

‎content/guides/harden-docker/_index.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Harden Docker for production
3+
linkTitle: Harden Docker
4+
summary:
5+
description: Learn how to configure Docker across your organization to harden Docker for proudction, especially in secure environments
6+
tags: [admin]
7+
params:
8+
featured: true
9+
time: 20 minutes
10+
image:
11+
resource_links:
12+
- title:
13+
url:
14+
---
15+
16+
This guide is for teams deploying Docker in regulated, production, or security-conscious environments. It helps administrators enforce security best practices, apply organization-wide controls, and reduce the attack surface of Docker tools like Docker Desktop and Docker Hub.
17+
18+
## Who's this for?
19+
20+
- Organization administrators
21+
- Security engineers
22+
- IT teams responsible for enforcing organization-wide security policies
23+
24+
## What you’ll learn
25+
26+
This guide walks you through how to:
27+
28+
- Enforce secure authentication using SSO and domain verification
29+
- Apply least-privilege access controls across your organization
30+
- Lock down Docker Desktop using centralized settings and policy enforcement
31+
- Monitor usage and integrate with compliance and security tooling
32+
- Align your Docker implementation with enterprise security and compliance requirements
33+
34+
## Before you start
35+
36+
To follow this guide, you’ll need:
37+
38+
- A Docker Business subscription
39+
- Organization owner access to your Docker organization
40+
- Access to your identity provider (IdP) if configuring SSO
41+
- A list of domains to verify and manage
42+
- Docker Desktop installed on user machines
43+
44+
If you’re new to Docker or managing organizations, start with the [Admin setup guide](/guides/admin-set-up) first.

‎content/guides/harden-docker/control-access.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Control access with verified domains and groups
3+
description:
4+
weight: 20
5+
---
6+
7+
In high-security environments, controlling access to Docker resources is
8+
paramount. By verifying your organization's domains and implementing
9+
group-based access controls, you can ensure that only authorized users can
10+
access your Docker resources.
11+
12+
This module guides you through the process of verifying domains and setting up
13+
group mappings to enforce strict access controls.
14+
15+
## Prerequisites
16+
17+
Before you begin, ensure you have:
18+
19+
- A Docker Business subscription
20+
- Organization owner access to your Docker organization or company
21+
- Access to your Domain Name System (DNS) provider to add TXT records
22+
- Access to your Identity Provider (IdP) to configure group mappings
23+
24+
## Step two: Enable auto-provisioning
25+
26+
Auto-provisioning automatically adds users to your organization when they sign
27+
in with an email address that matches your verified domain. This simplifies
28+
user management and ensures consistent security settings.
29+
30+
To enable auto-provisioning:
31+
32+
1. In the [Admin Console](https://app.docker.com/admin), navigate to
33+
the **Domain management** page and locate your verified domain.
34+
1. Select the **Actions** menu, then **Enable auto-provisioning**.
35+
1. Confirm the action in the pop-up modal.
36+
37+
> [!NOTE]
38+
>
39+
> Auto-provisioning is optional and does not create accounts for new users, it
40+
adds existing unassociated users to your organization. For domains that are
41+
using SSO, Just-in-Time (JIT) provisioning overrides auto-provisioning.
42+
43+
## Step three: Configure group mapping
44+
45+
Group mapping automates permissions management by linking identity provider
46+
groups to Docker roles and teams. This ensures consistent access control
47+
policies and reduces manual errors in role assignments.
48+
49+
1. Create groups in your IdP:
50+
1. Use the format `organization:team` that matches the name of your Docker
51+
organization and teams. For example, `docker:developers`.
52+
1. Assign users to the appropriate groups in your IdP.
53+
1. Configure group mapping in Docker:
54+
1. In the Admin Console, navigate to
55+
**Security and access** > **Provisioning** > **Group mapping**.
56+
1. Add the group names following the `organization:team` format.
57+
1. Docker will automatically assign users to the corresponding teams based
58+
on their group membership in your IdP.
59+
60+
> [!NOTE]
61+
>
62+
> When groups are synced, Docker creates a team if it doesn’t already exist.
63+
For detailed instructions, see [Group mapping]().
64+
65+
## Step four: Assign roles and permissions
66+
67+
Assigning appropriate roles to users ensures they have the necessary
68+
permissions without over-provisioning access.
69+
70+
- Member: Non-administrative role; can view other members in the same
71+
organization.
72+
- Editor: Partial administrative access; can create, edit, and delete
73+
repositories, and edit existing team’s access permissions.
74+
- Organization owner: Full administrative access; can manage repositories,
75+
teams, members, settings, and billing.
76+
77+
For more information on roles and permissions, see [Roles and permissions]().
78+
79+
## Best practices
80+
81+
- Use verified domains: Ensure all users sign in with email addresses from
82+
your verified domains to maintain control over access.
83+
- Implement group mapping: Automate user assignments to teams and roles to
84+
reduce manual errors and maintain consistent access policies.
85+
- Regularly audit access: Create a schedule to review team memberships and role
86+
assignments to ensure they align with current organizational needs.
87+
- Limit privileged access: Assign the Organization Owner role sparingly to
88+
minimize the risk of unauthorized changes.

‎content/guides/harden-docker/enforce-secure-auth.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Enforce secure authentication
3+
description:
4+
weight: 10
5+
---
6+
7+
In regulated and security-sensitive environments, enforcing single sign-on
8+
(SSO) ensures all users authenticate through a centralized identity provider
9+
(IdP). This strengthens security, simplifies user management, and allows you to
10+
enforce organization-wide authentication policies.
11+
12+
This module walks you through how to configure SSO for your Docker organization,
13+
enforce it for all users, and disable fallback sign-in methods.
14+
15+
## Prerequisites
16+
17+
Before you begin, ensure you have:
18+
19+
- A Docker Business subscription
20+
- Admin access to your Docker organization or company
21+
- Access to your DNS provider
22+
- Access to your Identity Provider (IdP) admin console (e.g., Okta, Azure AD)
23+
24+
## Step one: Add and verify your domain
25+
26+
Verifying your organization’s domain is the first step in securing access. This
27+
process confirms ownership and allows you to enforce SSO and auto-provisioning.
28+
29+
1. Sign in to the [Docker Admin Console](https://app.docker.com/admin) and
30+
select your organization from the **Choose profile** page.
31+
1. Add your domain:
32+
1. Under **Security and access**, select **Domain management**.
33+
1. Select **Add a domain**.
34+
1. Enter your domain (e.g., `example.com`) and select **Add domain**.
35+
1. Verify your domain:
36+
1. A pop-up modal will display a **TXT Record Value.**
37+
1. Sign in to your DNS provider and add a TXT record using the provided value.
38+
1. It may take up to 72 hours for DNS changes to propagate.
39+
1. Once the TXT record is recognized, return to the Admin Console’s **Domain management** page and select **Verify**.
40+
41+
> [!NOTE]
42+
>
43+
> For detailed instructions on adding TXT records with specific DNS providers,
44+
see [Domain management]().
45+
46+
## Step two: Set up SSO
47+
48+
Docker offers two types of SSO integration:
49+
50+
- OIDC: For IdPs like Entra ID, Auth0, or Google Workspace
51+
- SAML 2.0: Widely supported by enterprise IdPs like Okta, Ping, and legacy
52+
providers
53+
54+
Docker’s SSO configuration supports:
55+
56+
- Just-in-Time (JIT) user provisioning
57+
- Multi-domain SSO
58+
- Group mapping for team assignment (covered in [Module 2]())
59+
60+
To compare protocols and choose your setup path, start with the
61+
[SSO overview]().
62+
63+
Then follow the instructions for your IdP:
64+
65+
- [Set up OIDC SSO]()
66+
- [Set up SAML SSO]()
67+
68+
Each guide walks you through:
69+
70+
- Linking your verified domain to your IdP
71+
- Entering credentials
72+
- Mapping user claims
73+
- Testing the connection with a non-admin account
74+
75+
## Step three: Enforce SSO
76+
77+
Once you’ve confirmed the SSO connection works, you can enforce it across your
78+
organization to ensure all users authenticate through your IdP.
79+
80+
To enforce SSO:
81+
82+
1. In the [Admin Console](https://app.docker.com/admin), navigate
83+
to **Security and access** > **Authentication**.
84+
2. Under **SSO enforcement**, select **Enforce SSO for all users**.
85+
3. Confirm your changes.
86+
87+
This step blocks users from signing in with Docker credentials and requires
88+
authentication via your IdP for any domain-matched account.
89+
90+
## Step four: Enforce Docker Desktop sign-in
91+
92+
To prevent users from running Docker Desktop anonymously or without
93+
organizational control, you can enforce sign-in at the Desktop client level.
94+
When enabled, users must sign in with a Docker ID to use Docker Desktop.
95+
96+
This setting is enforced using centralized configuration methods like:
97+
98+
- `admin-settings.json` for local testing and smaller rollouts
99+
- Mobile Device Management (MDM) tools for larger fleets
100+
101+
To enable it:
102+
103+
1. In your settings configuration, set:
104+
105+
```json
106+
{
107+
"enforceSignIn": true
108+
}
109+
```
110+
111+
2. Distribute the setting using one of the supported configuration
112+
methods (e.g., MDM, file copy, registry edit).
113+
114+
For full details, see [Enforce sign-in]().
115+
116+
## Best practices
117+
118+
- Enable Just-in-Time (JIT) provisioning to streamline user onboarding.
119+
- Set up Multi-Factor Authentication (MFA) in your IdP for stronger
120+
authentication.
121+
- Use Enforce Sign-In on Docker Desktop to prevent unauthenticated or offline
122+
usage.
123+
- Avoid fallback authentication paths by enforcing SSO per domain.
124+
- Test with sample accounts before rolling out enforcement org-wide.

‎content/guides/harden-docker/monitor-activity.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: Secure Docker Desktop with Settings Management
3+
description:
4+
weight: 50
5+
---
6+
7+
In hardened environments, it’s not enough to configure secure defaults. You
8+
also need ongoing visibility into how Docker is being used, where settings may
9+
drift, and whether your container environments meet compliance requirements.
10+
11+
This module walks you through how to monitor Docker organization activity,
12+
audit Desktop settings across your fleet, and integrate with external tooling
13+
like SIEM or Slack.
14+
15+
## Prerequisites
16+
17+
Before you begin, ensure you have:
18+
19+
- A Docker Business subscription
20+
- Organization owner access to your Docker organization
21+
- Docker Desktop deployed across managed machines
22+
- Optional. Docker Scout enabled for image analysis and SBOM indexing
23+
24+
## Step one: Review activity logs
25+
26+
Docker automatically tracks high-level organizational activity such as:
27+
28+
- User sign-ins
29+
- Team and role changes
30+
- Repository actions
31+
- SSO enforcement status
32+
- Domain verification events
33+
34+
To view logs:
35+
36+
1. Go to the [Docker Admin Console](https://app.docker.com/admin)
37+
2. Select your organization.
38+
3. Navigate to **Activity Logs**.
39+
40+
You can search by event type or user to trace changes across your org.
41+
42+
## Step two: Monitor Desktop settings compliance
43+
44+
If you're using centralized settings via `admin-settings.json` or the Admin
45+
Console, you can audit compliance across your fleet.
46+
47+
To view compliance reports:
48+
49+
1. In the Admin Console, go to **Settings management**.
50+
2. Open the **Reporting** tab to see which machines are:
51+
- Compliant with enforced settings
52+
- Out of sync or missing required controls
53+
54+
## Step three: Set up Docker Scout for image visibility
55+
56+
Use [Docker Scout](https://docs.docker.com/scout/) to track security posture at
57+
the container image level. Scout supports:
58+
59+
- Software Bill of Materials (SBOM) indexing
60+
- Vulnerability scanning
61+
- Policy enforcement
62+
- Exceptions and remediation tracking
63+
64+
You can integrate Scout with:
65+
66+
- GitHub Actions
67+
- GitLab CI/CD
68+
- Jenkins
69+
- Azure DevOps
70+
- Artifactory, ECR, ACR, and more
71+
72+
To start, visit the [Docker Scout integrations overview](https://docs.docker.com/scout/integrations/).
73+
74+
## Step four: Enable alerts and external integrations
75+
76+
For real-time visibility, consider integrating Docker logs and insights with:
77+
78+
- Slack: Docker Scout supports alerting via Slack for policy violations and
79+
vulnerability reports
80+
- SIEM tools: Export activity logs or Scout scan results into tools like
81+
Splunk or Sentinel
82+
- Webhook-based integrations: Set up Docker Hub [webhooks](https://docs.docker.com/docker-hub/repos/manage/webhooks/) for image pull/push notifications
83+
84+
## Best practices
85+
86+
- Review activity logs regularly (weekly or during incident response).
87+
- Monitor settings compliance to detect drift across endpoints.
88+
- Enable SBOM indexing and scan enforcement via Docker Scout.
89+
- Push logs and alerts into your broader monitoring and alerting systems.
90+
- Use webhook or CI integrations to track image updates and policy violations
91+
in real time.

0 commit comments

Comments
 (0)