diff --git a/content/guides/admin-set-up/_index.md b/content/guides/admin-set-up/_index.md deleted file mode 100644 index 556c512a7c14..000000000000 --- a/content/guides/admin-set-up/_index.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Set up your company for success with Docker -linkTitle: Admin set up -summary: Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company. -description: Learn how to onboard your company and take advantage of all of the Docker products and features. -tags: [admin] -params: - featured: true - time: 20 minutes - image: - resource_links: - - title: Overview of Administration in Docker - url: /admin/ - - title: Single sign-on - url: /security/for-admins/single-sign-on/ - - title: Enforce sign-in - url: /security/for-admins/enforce-sign-in/ - - title: Roles and permissions - url: /security/for-admins/roles-and-permissions/ - - title: Settings Management - url: /security/for-admins/hardened-desktop/settings-management/ - - title: Registry Access Management - url: /security/for-admins/hardened-desktop/registry-access-management/ - - title: Image Access Management - url: /security/for-admins/hardened-desktop/image-access-management/ - - title: Docker subscription information - url: /subscription/details/ ---- - -Docker's tools provide a scalable, secure platform that empowers your developers to create, ship, and run applications faster. As an administrator, you have the ability to streamline workflows, standardize development environments, and ensure smooth deployments across your organization. - -By configuring Docker products to suit your company’s needs, you can optimize performance, simplify user management, and maintain control over resources. This guide will help you set up and configure Docker products to maximize productivity and success for your team whilst meeting compliance and security policies - -## Who’s this for? - -- Administrators responsible for managing Docker environments within their organization -- IT leaders looking to streamline development and deployment workflows -- Teams aiming to standardize application environments across multiple users -- Organizations seeking to optimize their use of Docker products for greater scalability and efficiency -- Organizations with [Docker Business subscriptions](https://www.docker.com/pricing/). - -## What you’ll learn - -- The importance of signing in to the company's Docker organization for access to usage data and enhanced functionality. -- How to standardize Docker Desktop versions and settings to create a consistent baseline for all users, while allowing flexibility for advanced developers. -- Strategies for implementing Docker’s security configurations to meet company IT and software development security requirements without hindering developer productivity. - -## Features covered - -- Organizations. These are the core structure for managing your Docker environment, grouping users, teams, and image repositories. Your organization was created with your subscription and is managed by one or more Owners. Users signed into the organization are assigned seats based on the purchased subscription. -- Enforce sign-in. By default, Docker Desktop does not require sign-in. However, you can configure settings to enforce this and ensure your developers sign in to your Docker organization. -- SSO. Without SSO, user management in a Docker organization is manual. Setting up an SSO connection between your identity provider and Docker ensures compliance with your security policy and automates user provisioning. Adding SCIM further automates user provisioning and de-provisioning. -- General and security settings. Configuring key settings will ensure smooth onboarding and usage of Docker products within your environment. Additionally, you can enable security features based on your company's specific security needs. - -## Who needs to be involved? - -- Docker organization owner: A Docker organization owner must be involved in the process and will be required for several key steps. -- DNS team: The DNS team is needed during the SSO setup to verify the company domain. -- MDM team: Responsible for distributing Docker-specific configuration files to developer machines. -- Identity Provider team: Required for configuring the identity provider and establishing the SSO connection during setup. -- Development lead: A development lead with knowledge of Docker configurations to help establish a baseline for developer settings. -- IT team: An IT representative familiar with company desktop policies to assist with aligning Docker configuration to those policies. -- Infosec: A security team member with knowledge of company development security policies to help configure security features. -- Docker testers: A small group of developers to test the new settings and configurations before full deployment. - -## Tools integration - -Okta, Entra ID SAML 2.0, Azure Connect (OIDC), MDM solutions like Intune diff --git a/content/guides/admin-set-up/comms-and-info-gathering.md b/content/guides/admin-set-up/comms-and-info-gathering.md deleted file mode 100644 index 1ad54fb855c0..000000000000 --- a/content/guides/admin-set-up/comms-and-info-gathering.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Communication and information gathering -description: Gather your company's requirements from key stakeholders and communicate to your developers. -weight: 10 ---- - -## Step one: Communicate with your developers and IT teams - -### Docker user communication - -You may already have Docker Desktop users within your company, and some steps in this process may affect how they interact with the platform. It's highly recommended to communicate early with users, informing them that as part of the subscription onboarding, they will be upgraded to a supported version of Docker Desktop. - -Additionally, communicate that settings will be reviewed to optimize productivity, and users will be required to sign in to the company’s Docker organization using their business email to fully utilize the subscription benefits. - -### MDM team communication - -Device management solutions, such as Intune and Jamf, are commonly used for software distribution across enterprises, typically managed by a dedicated MDM team. It is recommended that you engage with this team early in the process to understand their requirements and the lead time for deploying changes. - -Several key setup steps in this guide require the use of JSON files, registry keys, or .plist files that need to be distributed to developer machines. It’s a best practice to use MDM tools for deploying these configuration files and ensuring their integrity is preserved. - -## Step two: Identify Docker organizations - -Some companies may have more than one [Docker organization](/manuals/admin/organization/_index.md) created. These organizations may have been created for specific purposes, or may not be needed anymore. If you suspect your company has more than one Docker organization, it's recommended you survey your teams to see if they have their own organizations. You can also contact your Docker Customer Success representative to get a list of organizations with users whose emails match your domain name. - -## Step three: Gather requirements - -Through [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md), Docker provides numerous configuration parameters that can be preset. The Docker organization owner, development lead, and infosec representative should review these settings to establish the company’s baseline configuration, including security features and [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for Docker Desktop users. Additionally, they should decide whether to take advantage of other Docker products, such as [Docker Scout](/manuals/scout/_index.md), which is included in the subscription. - -To view the parameters that can be preset, see [Configure Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md#step-two-configure-the-settings-you-want-to-lock-in). - -## Optional step four: Meet with the Docker Implementation team - -The Docker Implementation team can help you step through setting up your organization, configuring SSO, enforcing sign-in, and configuring Docker. You can reach out to set up a meeting by emailing successteam@docker.com. diff --git a/content/guides/admin-set-up/deploy.md b/content/guides/admin-set-up/deploy.md deleted file mode 100644 index ab91d9f4e568..000000000000 --- a/content/guides/admin-set-up/deploy.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Deploy -description: Deploy your Docker setup across your company. -weight: 40 ---- - -> [!WARNING] -> Ensure you communicate with your users before proceeding, and confirm that your IT and MDM teams are prepared to handle any unexpected issues, as these steps will affect all existing users signing into your Docker organization. - -## Step one: Enforce SSO - -Enforcing SSO means that anyone who has a Docker profile with an email address that matches your verified domain must sign in using your SSO connection. Make sure the Identity provider groups associated with your SSO connection cover all the developer groups that you want to have access to the Docker subscription. - -## Step two: Deploy configuration settings and enforce sign-in to users - -Have the MDM team deploy the configuration files for Docker to all users. - -Congratulations, you have successfully completed the admin implementation process for Docker. diff --git a/content/guides/admin-set-up/finalize-plans-and-setup.md b/content/guides/admin-set-up/finalize-plans-and-setup.md deleted file mode 100644 index b810d3dfbc06..000000000000 --- a/content/guides/admin-set-up/finalize-plans-and-setup.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Finalize plans and begin setup -description: Collaborate with your MDM team to distribute configurations and set up SSO and Docker product trials. -weight: 20 ---- - -## Step one: Send finalized settings files to the MDM team - -After reaching an agreement with the relevant teams about your baseline and security configurations as outlined in module one, configure Settings Management using either the [Docker Admin Console](/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md) or an [`admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md). - -Once the file is ready, collaborate with your MDM team to deploy your chosen settings, along with your chosen method for [enforcing sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). - -> [!IMPORTANT] -> -> It’s highly recommended that you test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely. - -## Step two: Manage your organizations - -If you have more than one organization, it’s recommended that you either consolidate them into one organization or create a [Docker company](/manuals/admin/company/_index.md) to manage multiple organizations. Work with the Docker Customer Success and Implementation teams to make this happen. - -## Step three: Begin setup - -### Set up single sign-on SSO domain verification - -Single sign-on (SSO) lets developers authenticate using their identity providers (IdPs) to access Docker. SSO is available for a whole company, and all associated organizations, or an individual organization that has a Docker Business subscription. For more information, see the [documentation](/manuals/security/for-admins/single-sign-on/_index.md). - -You can also enable [SCIM](/manuals/security/for-admins/provisioning/scim.md) for further automation of provisioning and deprovisioning of users. - -### Set up Docker product entitlements included in the subscription - -[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces build times, both locally and in CI, by providing a dedicated remote builder and shared cache. Powered by the cloud, developer time and local resources are freed up so your team can focus on more important things, like innovation. To get started, [set up a cloud builder](https://app.docker.com/build/). - -[Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing your software supply chain security. By analyzing your images, Docker Scout compiles an inventory of components, also known as a Software Bill of Materials (SBOM). The SBOM is matched against a continuously updated vulnerability database to pinpoint security weaknesses. To get started, see [Quickstart](/manuals/scout/quickstart.md). - -### Ensure you're running a supported version of Docker Desktop - -> [!WARNING] -> -> This step could affect the experience for users on older versions of Docker Desktop. - -Existing users may be running outdated or unsupported versions of Docker Desktop. It is highly recommended that all users update to a supported version. Docker Desktop versions released within the past 6 months from the latest release are supported. - -It's recommended that you use a MDM solution to manage the version of Docker Desktop for users. Users may also get Docker Desktop directly from Docker or through a company software portal. diff --git a/content/guides/admin-set-up/testing.md b/content/guides/admin-set-up/testing.md deleted file mode 100644 index 9ee6306764e9..000000000000 --- a/content/guides/admin-set-up/testing.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Testing -description: Test your Docker setup. -weight: 30 ---- - -## SSO and SCIM testing - -You can test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email address linked to a Docker account that is part of the verified domain. Developers who sign in using their Docker usernames will remain unaffected by the SSO and/or SCIM setup. - -> [!IMPORTANT] -> -> Some users may need CLI based logins to Docker Hub, and for this they will need a [personal access token (PAT)](/manuals/security/for-developers/access-tokens.md). - -## Test RAM and IAM - -> [!WARNING] -> Be sure to communicate with your users before proceeding, as this step will impact all existing users signing into your Docker organization - -If you plan to use [Registry Access Management (RAM)](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) and/or [Image Access Management (IAM)](/manuals/security/for-admins/hardened-desktop/image-access-management.md), ensure your test developer signs in to Docker Desktop using their organization credentials. Once authenticated, have them attempt to pull an unauthorized image or one from a disallowed registry via the Docker CLI. They should receive an error message indicating that the registry is restricted by the organization. - -## Deploy settings and enforce sign in to test group - -Deploy the Docker settings and enforce sign-in for a small group of test users via MDM. Have this group test their development workflows with containers on Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement function as expected. - -## Test Docker Build Cloud capabilities - -Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md). - -## Verify Docker Scout monitoring of repositories - -Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that data is being properly received for the repositories where Docker Scout has been enabled. diff --git a/content/guides/harden-docker/_index.md b/content/guides/harden-docker/_index.md new file mode 100644 index 000000000000..7ba3e37a1b10 --- /dev/null +++ b/content/guides/harden-docker/_index.md @@ -0,0 +1,44 @@ +--- +title: Harden Docker for production +linkTitle: Harden Docker +summary: +description: Learn how to configure Docker across your organization to harden Docker for proudction, especially in secure environments +tags: [admin] +params: + featured: true + time: 20 minutes + image: + resource_links: + - title: + url: +--- + +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. + +## Who's this for? + +- Organization administrators +- Security engineers +- IT teams responsible for enforcing organization-wide security policies + +## What you’ll learn + +This guide walks you through how to: + +- Enforce secure authentication using SSO and domain verification +- Apply least-privilege access controls across your organization +- Lock down Docker Desktop using centralized settings and policy enforcement +- Monitor usage and integrate with compliance and security tooling +- Align your Docker implementation with enterprise security and compliance requirements + +## Before you start + +To follow this guide, you’ll need: + +- A Docker Business subscription +- Organization owner access to your Docker organization +- Access to your identity provider (IdP) if configuring SSO +- A list of domains to verify and manage +- Docker Desktop installed on user machines + +If you’re new to Docker or managing organizations, start with the [Admin setup guide](/guides/admin-set-up) first. \ No newline at end of file diff --git a/content/guides/harden-docker/control-access.md b/content/guides/harden-docker/control-access.md new file mode 100644 index 000000000000..c8ccb16cf62f --- /dev/null +++ b/content/guides/harden-docker/control-access.md @@ -0,0 +1,88 @@ +--- +title: Control access with verified domains and groups +description: +weight: 20 +--- + +In high-security environments, controlling access to Docker resources is +paramount. By verifying your organization's domains and implementing +group-based access controls, you can ensure that only authorized users can +access your Docker resources. + +This module guides you through the process of verifying domains and setting up +group mappings to enforce strict access controls. + +## Prerequisites + +Before you begin, ensure you have: + +- A Docker Business subscription +- Organization owner access to your Docker organization or company +- Access to your Domain Name System (DNS) provider to add TXT records +- Access to your Identity Provider (IdP) to configure group mappings + +## Step two: Enable auto-provisioning + +Auto-provisioning automatically adds users to your organization when they sign +in with an email address that matches your verified domain. This simplifies +user management and ensures consistent security settings. + +To enable auto-provisioning: + +1. In the [Admin Console](https://app.docker.com/admin), navigate to +the **Domain management** page and locate your verified domain. +1. Select the **Actions** menu, then **Enable auto-provisioning**. +1. Confirm the action in the pop-up modal. + +> [!NOTE] +> +> Auto-provisioning is optional and does not create accounts for new users, it +adds existing unassociated users to your organization. For domains that are +using SSO, Just-in-Time (JIT) provisioning overrides auto-provisioning. + +## Step three: Configure group mapping + +Group mapping automates permissions management by linking identity provider +groups to Docker roles and teams. This ensures consistent access control +policies and reduces manual errors in role assignments. + +1. Create groups in your IdP: + 1. Use the format `organization:team` that matches the name of your Docker + organization and teams. For example, `docker:developers`. + 1. Assign users to the appropriate groups in your IdP. +1. Configure group mapping in Docker: + 1. In the Admin Console, navigate to + **Security and access** > **Provisioning** > **Group mapping**. + 1. Add the group names following the `organization:team` format. + 1. Docker will automatically assign users to the corresponding teams based + on their group membership in your IdP. + +> [!NOTE] +> +> When groups are synced, Docker creates a team if it doesn’t already exist. +For detailed instructions, see [Group mapping](). + +## Step four: Assign roles and permissions + +Assigning appropriate roles to users ensures they have the necessary +permissions without over-provisioning access. + +- Member: Non-administrative role; can view other members in the same +organization. +- Editor: Partial administrative access; can create, edit, and delete +repositories, and edit existing team’s access permissions. +- Organization owner: Full administrative access; can manage repositories, +teams, members, settings, and billing. + +For more information on roles and permissions, see [Roles and permissions](). + +## Best practices + +- Use verified domains: Ensure all users sign in with email addresses from +your verified domains to maintain control over access. +- Implement group mapping: Automate user assignments to teams and roles to +reduce manual errors and maintain consistent access policies. +- Regularly audit access: Create a schedule to review team memberships and role +assignments to ensure they align with current organizational needs. +- Limit privileged access: Assign the Organization Owner role sparingly to +minimize the risk of unauthorized changes. diff --git a/content/guides/harden-docker/enforce-secure-auth.md b/content/guides/harden-docker/enforce-secure-auth.md new file mode 100644 index 000000000000..467703bd8936 --- /dev/null +++ b/content/guides/harden-docker/enforce-secure-auth.md @@ -0,0 +1,124 @@ +--- +title: Enforce secure authentication +description: +weight: 10 +--- + +In regulated and security-sensitive environments, enforcing single sign-on +(SSO) ensures all users authenticate through a centralized identity provider +(IdP). This strengthens security, simplifies user management, and allows you to +enforce organization-wide authentication policies. + +This module walks you through how to configure SSO for your Docker organization, +enforce it for all users, and disable fallback sign-in methods. + +## Prerequisites + +Before you begin, ensure you have: + +- A Docker Business subscription +- Admin access to your Docker organization or company +- Access to your DNS provider +- Access to your Identity Provider (IdP) admin console (e.g., Okta, Azure AD) + +## Step one: Add and verify your domain + +Verifying your organization’s domain is the first step in securing access. This +process confirms ownership and allows you to enforce SSO and auto-provisioning. + +1. Sign in to the [Docker Admin Console](https://app.docker.com/admin) and +select your organization from the **Choose profile** page. +1. Add your domain: + 1. Under **Security and access**, select **Domain management**. + 1. Select **Add a domain**. + 1. Enter your domain (e.g., `example.com`) and select **Add domain**. +1. Verify your domain: + 1. A pop-up modal will display a **TXT Record Value.** + 1. Sign in to your DNS provider and add a TXT record using the provided value. + 1. It may take up to 72 hours for DNS changes to propagate. + 1. Once the TXT record is recognized, return to the Admin Console’s **Domain management** page and select **Verify**. + +> [!NOTE] +> +> For detailed instructions on adding TXT records with specific DNS providers, +see [Domain management](). + +## Step two: Set up SSO + +Docker offers two types of SSO integration: + +- OIDC: For IdPs like Entra ID, Auth0, or Google Workspace +- SAML 2.0: Widely supported by enterprise IdPs like Okta, Ping, and legacy +providers + +Docker’s SSO configuration supports: + +- Just-in-Time (JIT) user provisioning +- Multi-domain SSO +- Group mapping for team assignment (covered in [Module 2]()) + +To compare protocols and choose your setup path, start with the +[SSO overview](). + +Then follow the instructions for your IdP: + +- [Set up OIDC SSO]() +- [Set up SAML SSO]() + +Each guide walks you through: + +- Linking your verified domain to your IdP +- Entering credentials +- Mapping user claims +- Testing the connection with a non-admin account + +## Step three: Enforce SSO + +Once you’ve confirmed the SSO connection works, you can enforce it across your +organization to ensure all users authenticate through your IdP. + +To enforce SSO: + +1. In the [Admin Console](https://app.docker.com/admin), navigate +to **Security and access** > **Authentication**. +2. Under **SSO enforcement**, select **Enforce SSO for all users**. +3. Confirm your changes. + +This step blocks users from signing in with Docker credentials and requires +authentication via your IdP for any domain-matched account. + +## Step four: Enforce Docker Desktop sign-in + +To prevent users from running Docker Desktop anonymously or without +organizational control, you can enforce sign-in at the Desktop client level. +When enabled, users must sign in with a Docker ID to use Docker Desktop. + +This setting is enforced using centralized configuration methods like: + +- `admin-settings.json` for local testing and smaller rollouts +- Mobile Device Management (MDM) tools for larger fleets + +To enable it: + +1. In your settings configuration, set: + + ```json + { + "enforceSignIn": true + } + ``` + +2. Distribute the setting using one of the supported configuration +methods (e.g., MDM, file copy, registry edit). + +For full details, see [Enforce sign-in](). + +## Best practices + +- Enable Just-in-Time (JIT) provisioning to streamline user onboarding. +- Set up Multi-Factor Authentication (MFA) in your IdP for stronger +authentication. +- Use Enforce Sign-In on Docker Desktop to prevent unauthenticated or offline +usage. +- Avoid fallback authentication paths by enforcing SSO per domain. +- Test with sample accounts before rolling out enforcement org-wide. diff --git a/content/guides/harden-docker/monitor-activity.md b/content/guides/harden-docker/monitor-activity.md new file mode 100644 index 000000000000..6dbc7f0486ea --- /dev/null +++ b/content/guides/harden-docker/monitor-activity.md @@ -0,0 +1,91 @@ +--- +title: Secure Docker Desktop with Settings Management +description: +weight: 50 +--- + +In hardened environments, it’s not enough to configure secure defaults. You +also need ongoing visibility into how Docker is being used, where settings may +drift, and whether your container environments meet compliance requirements. + +This module walks you through how to monitor Docker organization activity, +audit Desktop settings across your fleet, and integrate with external tooling +like SIEM or Slack. + +## Prerequisites + +Before you begin, ensure you have: + +- A Docker Business subscription +- Organization owner access to your Docker organization +- Docker Desktop deployed across managed machines +- Optional. Docker Scout enabled for image analysis and SBOM indexing + +## Step one: Review activity logs + +Docker automatically tracks high-level organizational activity such as: + +- User sign-ins +- Team and role changes +- Repository actions +- SSO enforcement status +- Domain verification events + +To view logs: + +1. Go to the [Docker Admin Console](https://app.docker.com/admin) +2. Select your organization. +3. Navigate to **Activity Logs**. + +You can search by event type or user to trace changes across your org. + +## Step two: Monitor Desktop settings compliance + +If you're using centralized settings via `admin-settings.json` or the Admin +Console, you can audit compliance across your fleet. + +To view compliance reports: + +1. In the Admin Console, go to **Settings management**. +2. Open the **Reporting** tab to see which machines are: + - Compliant with enforced settings + - Out of sync or missing required controls + +## Step three: Set up Docker Scout for image visibility + +Use [Docker Scout](https://docs.docker.com/scout/) to track security posture at +the container image level. Scout supports: + +- Software Bill of Materials (SBOM) indexing +- Vulnerability scanning +- Policy enforcement +- Exceptions and remediation tracking + +You can integrate Scout with: + +- GitHub Actions +- GitLab CI/CD +- Jenkins +- Azure DevOps +- Artifactory, ECR, ACR, and more + +To start, visit the [Docker Scout integrations overview](https://docs.docker.com/scout/integrations/). + +## Step four: Enable alerts and external integrations + +For real-time visibility, consider integrating Docker logs and insights with: + +- Slack: Docker Scout supports alerting via Slack for policy violations and +vulnerability reports +- SIEM tools: Export activity logs or Scout scan results into tools like +Splunk or Sentinel +- Webhook-based integrations: Set up Docker Hub [webhooks](https://docs.docker.com/docker-hub/repos/manage/webhooks/) for image pull/push notifications + +## Best practices + +- Review activity logs regularly (weekly or during incident response). +- Monitor settings compliance to detect drift across endpoints. +- Enable SBOM indexing and scan enforcement via Docker Scout. +- Push logs and alerts into your broader monitoring and alerting systems. +- Use webhook or CI integrations to track image updates and policy violations +in real time. diff --git a/content/guides/harden-docker/provision-users.md b/content/guides/harden-docker/provision-users.md new file mode 100644 index 000000000000..b78a68140ec0 --- /dev/null +++ b/content/guides/harden-docker/provision-users.md @@ -0,0 +1,53 @@ +--- +title: Provision users with least privilege +description: +weight: 30 +--- + +Granting the right level of access to each user in your Docker organization +helps prevent accidental misconfiguration, enforces separation of duties, and +reduces risk. + +This module shows you how to assign roles, restrict self-invites, and use group +mapping for automated, least-privilege access. + +## Prerequisites + +Before you begin, ensure you have: + +- A Docker Business subscription +- Organization owner access to your Docker organization +- A verified domain and SSO configured +- [Group mapping](https://docs.docker.com/security/for-admins/provisioning/group-mapping/) (optional but recommended) + +## Step one: Assign roles based on job function + +Docker provides three organization-level roles: + +- Member: Default role for most users. +- Editor: Manage repositories, settings, and access for assigned teams. +- Organization owner: Full administrator access. + +To assign roles: + +1. Sign in to the [Admin Console](https://app.docker.com/admin) and choose your +organization from the **Choose profile** page. +2. Navigate to **Members** and select the **Actions** menu next to a user. +3. Select **Edit** and assign a role. + +For more details, see [Roles and permissions](). + +## Step two: Use teams to organize access + +Organize users into teams to control access to Docker Hub repositories, +products, and settings: + +1. In the [Admin Console](https://app.docker.com/admin), navigate to **Teams**. +2. Create a new team or edit an existing one. +3. Add members manually or automatically via group mapping. + +## Step three: Automate role assignment with group mapping + +If you set up SSO and group mapping, Docker can assign users to teams automatically based on their group in your IdP. + +Use the `org:team` naming convention in Docker and your IdP for group names. diff --git a/content/guides/harden-docker/secure-docker-desktop.md b/content/guides/harden-docker/secure-docker-desktop.md new file mode 100644 index 000000000000..ef7c5139abce --- /dev/null +++ b/content/guides/harden-docker/secure-docker-desktop.md @@ -0,0 +1,173 @@ +--- +title: Secure Docker Desktop with Settings Management +description: +weight: 40 +--- + +In secure environments, Docker Desktop must be tightly controlled to prevent +unauthorized behavior, unvetted updates, and data leakage. This module shows +you how to enforce strict settings using `admin-settings.json` and the Admin +Console, based on centralized security policy. + +For a full list of supported settings and values, see the +[Settings reference](https://docs.docker.com/security/for-admins/hardened-desktop/settings-management/settings-reference/). + +## Prerequisites + +- Docker Desktop installed on user machines +- Organization owner access to your Docker organization +- A way to distribute `admin-settings.json` file or manage settings via MDM + +## Step one: Disable telemetry and crash reporting + +To prevent unapproved outbound data from Docker Desktop: + +```json +{ + "sendUsageStatistics": false, + "sendErrorReports": false +} +``` + +Lock both settings to ensure users can’t re-enable them. This prevents Docker +Desktop from sending anonymized usage data or crash logs to Docker servers. + +## Step two: Disable update checks + +Prevent Docker Desktop from checking for new versions: + +```json +{ + "disableUpdates": true +} +``` + +You should distribute updates internally through a vetted package source. Lock +this setting to ensure consistent versions across your organization. + +## Step three: Restrict Docker Desktop features + +Set the following to prevent installation of unvetted code or execution of +risky commands: + +```json +{ + "allowExtensions": false, + "blockDockerLoad": true, + "hideOnboarding": true, + "exposeDockerAPIOnWindows": false +} +``` + +These settings disable extensions, block loading local image tarballs, +suppress UI prompts, and prevent unsafe remote access to the Docker daemon. + +## Step four: Lock down file sharing and emulation + +Limit which host paths can be mounted into containers, enforce safe drivers, +and restrict CPU architecture emulation: + +```json + +{ + "allowedFileSharingPaths": ["/Users/dev/projects", "/Volumes/code"], + "shareFilesOnStart": true, + "useVirtioFS": true, + "useGrpcFUSE": false, + "useRosetta": false + } +``` + +Ensure all of the above are locked. This ensures users can only mount secure, +pre-approved directories. + +## Step five: Enforce SBOM indexing with Docker Scout + +Enable Software Bill of Materials (SBOM) generation for all images: + +```json +{ + "enableSBOMIndexing": true, + "enableBackgroundSBOMIndexing": true + } +``` + +Lock both settings to support compliance and vulnerability management workflows. + +## Step six: Enforce proxy configuration + +Prevent users from overriding corporate proxy settings: + +```json +{ + "proxySettings": { + "mode": "manual", + "httpProxy": "http://proxy.corp.example.com:3128", + "httpsProxy": "http://proxy.corp.example.com:3128", + "noProxy": "*.internal.example.com,localhost", + "authenticationMethod": "kerberos" + }, + "allowUserToEditProxySettings": false + } +``` + +Lock the entire proxy config to ensure consistent and auditable network routing. + +## Step seven: Standardize the Linux VM and WSL settings + +Enforce low-level Linux backend configuration: + +```json +{ + "useWSL2Engine": true, + "daemonConfigFile": { + "log-driver": "json-file", + "storage-driver": "overlay2" + }, + "vpnKitCIDR": "10.255.0.0/24" +} +``` + +Lock all of these settings to prevent drift from your approved baseline. + +## Step eight: Disable embedded Kubernetes + +To prevent local Kubernetes environments from drifting from production +standards: + +```json +{ + "allowKubernetes": false, + "showKubernetesSystemContainers": false, + "kubernetesImageRepository": "registry.corp.example.com/k8s" +} +``` + +Lock these settings to remove ambiguity around where clusters are running and +how they behave. + +## Step nine: Enforce Enhanced Container Isolation (ECI) + +ECI provides a hardened boundary around Docker containers, especially important +in untrusted environments. + +```json +{ + "enableECI": true, + "allowECIConfiguration": false, + "eciAllowedImages": ["registry.corp.example.com/secure-build-runner:latest"], + "eciAllowDerivedImages": false, + "eciAllowedCommands": ["ps", "pull"] +} +``` + +Use ECI to restrict which containers can mount the Docker socket and exactly +what they can do with it. + +## Best practices + +- Lock all critical security settings to prevent end-user overrides. +- Distribute `admin-settings.json` centrally, ideally via MDM or login script. +- Use [desktop settings reporting](https://docs.docker.com/security/for-admins/hardened-desktop/settings-management/compliance-reporting/) to audit compliance. +- Enforce a single approved Desktop version across your org. See [disableUpdates](https://docs.docker.com/security/for-admins/hardened-desktop/settings-management/settings-reference/#disableupdates). +- Avoid optional features unless explicitly vetted for your use case. diff --git a/layouts/_default/_markup/render-link.html b/layouts/_default/_markup/render-link.html index 32a87795f1f4..df2591b142a1 100644 --- a/layouts/_default/_markup/render-link.html +++ b/layouts/_default/_markup/render-link.html @@ -10,4 +10,4 @@ {{ .Text | safeHTML }} {{- else -}} {{ .Text | safeHTML }} -{{- end -}} +{{- end -}} \ No newline at end of file diff --git a/layouts/partials/github-links.html b/layouts/partials/github-links.html index 8ed3de9d0876..6aeba4eebea7 100644 --- a/layouts/partials/github-links.html +++ b/layouts/partials/github-links.html @@ -8,13 +8,10 @@ {{ if not (in .Filename "/_vendor/") }}

- {{ partial "utils/svg.html" "theme/icons/edit.svg" }} + {{ partial "utils/svg.html" "theme/icons/edit.svg" }} {{- T "editPage" -}} - - {{ partialCached "icon" "open_in_new" "open_in_new" }} - + href="{{ site.Params.repo }}/edit/main/content/{{ .Path }}">{{- T "editPage" -}}

{{ end }} {{ end }} @@ -23,10 +20,6 @@ {{ partial "utils/svg.html" "theme/icons/issue.svg" }} {{- T "requestChanges" -}} - - {{ partialCached "icon" "open_in_new" "open_in_new" }} - - + href="{{ site.Params.repo }}/issues/new?template=doc_issue.yml&location={{ .Permalink }}&labels=status%2Ftriage">{{- T "requestChanges" -}}

-{{ end }} +{{ end }} \ No newline at end of file