From 20573af630f0338454793146888385e4b04fcdb9 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 28 Aug 2024 16:16:39 -0700 Subject: [PATCH 1/9] admin: add org access tokens Signed-off-by: Craig Osterhout --- .../admin/organization/activity-logs.md | 3 + content/manuals/docker-hub/release-notes.md | 2 +- .../manuals/docker-hub/service-accounts.md | 6 +- .../security/for-admins/access-tokens.md | 114 ++++++++++++++++++ 4 files changed, 123 insertions(+), 2 deletions(-) create mode 100644 content/manuals/security/for-admins/access-tokens.md diff --git a/content/manuals/admin/organization/activity-logs.md b/content/manuals/admin/organization/activity-logs.md index 11e596bb470b..051bbb0bf2ab 100644 --- a/content/manuals/admin/organization/activity-logs.md +++ b/content/manuals/admin/organization/activity-logs.md @@ -66,6 +66,9 @@ Refer to the following section for a list of events and their descriptions: | Single Sign-On domain added | Details of the single sign-on domain added to your organization | | Single Sign-On domain removed | Details of the single sign-on domain removed from your organization | | Single Sign-On domain verified | Details of the single sign-on domain verified for your organization | +| Access token created | Access token created in organization | +| Access token updated | Access token updated in organization | +| Access token deleted | Access token deleted in organization | ### Repository events diff --git a/content/manuals/docker-hub/release-notes.md b/content/manuals/docker-hub/release-notes.md index 30c2440fdb44..9e402191cd29 100644 --- a/content/manuals/docker-hub/release-notes.md +++ b/content/manuals/docker-hub/release-notes.md @@ -254,7 +254,7 @@ Each organization page now breaks down into these tabs: ### New features -* You can now [create personal access tokens](access-tokens.md) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section. +* You can now [create personal access tokens](/security/for-developers/access-tokens/) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section. ### Known Issues diff --git a/content/manuals/docker-hub/service-accounts.md b/content/manuals/docker-hub/service-accounts.md index b8c43a5dc37c..9237220d091a 100644 --- a/content/manuals/docker-hub/service-accounts.md +++ b/content/manuals/docker-hub/service-accounts.md @@ -11,6 +11,10 @@ weight: 50 > > Service accounts require a > [Docker Team, or Business subscription](../subscription/_index.md). +> +> Docker recommends that you use organization access tokens instead of service +> accounts. For more details, see [Organization access +> tokens](/security/for-admins/access-tokens/). A service account is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the organization. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process. @@ -49,7 +53,7 @@ To create a new service account for your Team account: 2. Create a [team](manage-a-team.md) in your organization and grant it read-only access to your private repositories. 3. Add the new Docker ID to your [organization](orgs.md). 4. Add the new Docker ID to the [team](manage-a-team.md) you created earlier. -5. Create a new [personal access token (PAT)](access-tokens.md) from the user account and use it for CI. +5. Create a new [personal access token (PAT)](/security/for-developers/access-tokens/) from the user account and use it for CI. > [!NOTE] > diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md new file mode 100644 index 000000000000..b6ade2a2e0f4 --- /dev/null +++ b/content/manuals/security/for-admins/access-tokens.md @@ -0,0 +1,114 @@ +--- +title: Organization access tokens +description: Learn how to create and manage organization access tokens + to securely push and pull images programmatically. +keywords: docker hub, security, OAT, organization access token +--- + +> [!NOTE] +> +> Organization access tokens require a +> [Docker Team, or Business subscription](/subscription/core-subscription/details/). + +An organization access token (OAT) is like a [personal access token +(PAT)](/security/for-developers/access-tokens/), but an OAT is associated with +an organization and not a single user account. Use an OAT instead of a PAT to +let business-critical tasks access Docker Hub repositories without connecting +the token to single user. + +OATs provide the following advantages: + +- You can investigate when the OAT was last used and then disable or delete it + if you find any suspicious activity. +- You can limit what each OAT has access to, which limits the impact if an OAT + is compromised. +- All organization owners can manage OATs. If one owner leaves the organization, + the remaining owners can still manage the OATs. +- OATs have their own Docker Hub usage limits that don't count towards your + personal account's limits. + +If you have existing [service accounts](/docker-hub/service-accounts/), Docker recommends that you replace the service accounts with OATs. OATs offer the following advantages over service accounts: + +- Access permissions are easier to manage with OATs. You can assign access + permissions to OATs, while service accounts require using teams for access + permissions. +- OATs are easier to manage. OATs are centrally managed in the Admin Console. + For service accounts, you may need to sign in to that service account to + manage it. If using single sign-on enforcement and the service account is not + in your IdP, you may not be able to sign in to the service account to manage + it. +- OATs are not associated with a single user. If a user with access to the + service account leaves your organization, you may lose access to the service + account. OATs can be managed by any organization owner. + +## Create an organization access token + +> [!IMPORTANT] +> +> Treat access tokens like a password and keep them secret. Store your tokens securely in a credential manager for example. + +Organization owners can create up to 3 organization access tokens (OATs) for +organizations with a Team subscription and up to 100 OATs for organizations with +a Business subscription. Expired tokens count towards the total amount of +tokens. + +To create an OAT: + +1. Sign in to the [Admin Console](https://app.docker.com/admin). + +2. Select the organization you want to create an access token for. + +3. Under **Security and access**, select **Access tokens**. + +4. Select **Generate access token**. + +5. Add a label and optional description for your token. Use something that indicates the use case or purpose of the token. + +6. Select the expiration date for the token. + +7. Select the repository access for the token. + + The access permissions are scopes that set restrictions in your repositories. + For example, for Read & Write permissions, an automation pipeline can build + an image and then push it to a repository. However, it can't delete the + repository. You can select one of the following options: + + - **Public repositories (read only)** + - **All repositories**: You can select read access, or read and write access. + - **Select repositories**: You can select up to 50 repositories, and then + select read access, or read and write access for each repository. + +8. Select **Generate token** and then copy the token that appears on the screen + and save it. You won't be able to retrieve the token once you exit the + screen. + +## Use an organization access token + +You can use an organization access token when you sign in using Docker CLI. + +Sign in from your Docker CLI client with the following command, replacing +`YOUR_ORG` with your organization name: + +```console +$ docker login --username +``` + +When prompted for a password, enter your organization access token instead of a +password. + +## Modify existing tokens + +You can rename, update the description, update the repository access, +deactivate, or delete a token as needed. + +1. Sign in to the [Admin Console](https://app.docker.com/admin). + +2. Select the organization you want to modify an access token for. + +3. Under **Security and access**, select **Access tokens**. + +4. Select the actions menu on the far right of a token row, then select + **Deactivate**, **Edit**, or **Delete** to modify the token. For **Inactive** + tokens, you can only select **Delete**. + +5. If editing a token, select **Save** after specifying your modifications. From 779de751d2c9d5ebe60dedda4a87708ee58d20b0 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Thu, 29 Aug 2024 13:45:50 -0700 Subject: [PATCH 2/9] add OAT to vocab Signed-off-by: Craig Osterhout --- _vale/config/vocabularies/Docker/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index b6c03f848c08..a4ad20368d6d 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -85,10 +85,12 @@ MySQL NAT Nginx Nuxeo +OAT OAuth OCI OTel Okta +PAT Postgres PowerShell Python From c2d25644b02380452324f2db8635ddb02cad95a7 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Thu, 12 Sep 2024 09:28:10 -0700 Subject: [PATCH 3/9] update team token limit Signed-off-by: Craig Osterhout --- content/manuals/security/for-admins/access-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md index b6ade2a2e0f4..f81a4bb3fd41 100644 --- a/content/manuals/security/for-admins/access-tokens.md +++ b/content/manuals/security/for-admins/access-tokens.md @@ -47,7 +47,7 @@ If you have existing [service accounts](/docker-hub/service-accounts/), Docker r > > Treat access tokens like a password and keep them secret. Store your tokens securely in a credential manager for example. -Organization owners can create up to 3 organization access tokens (OATs) for +Organization owners can create up to 10 organization access tokens (OATs) for organizations with a Team subscription and up to 100 OATs for organizations with a Business subscription. Expired tokens count towards the total amount of tokens. From 3c4b9accc22753dfc66fedc3144fcb6c0b211b83 Mon Sep 17 00:00:00 2001 From: Craig Date: Tue, 24 Sep 2024 13:16:59 -0700 Subject: [PATCH 4/9] add beta label Signed-off-by: Craig --- content/manuals/security/for-admins/access-tokens.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md index f81a4bb3fd41..992375934371 100644 --- a/content/manuals/security/for-admins/access-tokens.md +++ b/content/manuals/security/for-admins/access-tokens.md @@ -3,18 +3,19 @@ title: Organization access tokens description: Learn how to create and manage organization access tokens to securely push and pull images programmatically. keywords: docker hub, security, OAT, organization access token +linkTitle: Organization access tokens (Beta) --- -> [!NOTE] -> -> Organization access tokens require a -> [Docker Team, or Business subscription](/subscription/core-subscription/details/). +{{% experimental title="Beta" %}} +The organization access tokens feature is currently in [Beta](../../release-lifecycle.md#beta). +{{% /experimental %}} An organization access token (OAT) is like a [personal access token (PAT)](/security/for-developers/access-tokens/), but an OAT is associated with an organization and not a single user account. Use an OAT instead of a PAT to let business-critical tasks access Docker Hub repositories without connecting -the token to single user. +the token to single user. You must have a [Docker Team or Business +subscription](/subscription/core-subscription/details/) to use OATs. OATs provide the following advantages: From 0da04dd5dd9e9f5e38a929b3c8934f1227f53277 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 15 Oct 2024 15:16:54 +0100 Subject: [PATCH 5/9] ENGDOCS-2256 (#21114) * ENGDOCS-2256 * ENGDOCS-2256 --- content/manuals/desktop/faqs/general.md | 37 +++++++++++++++++++ .../manuals/desktop/install/mac-install.md | 4 ++ .../desktop/install/windows-install.md | 4 ++ 3 files changed, 45 insertions(+) diff --git a/content/manuals/desktop/faqs/general.md b/content/manuals/desktop/faqs/general.md index c228c6a342f9..6fbdaa921f4f 100644 --- a/content/manuals/desktop/faqs/general.md +++ b/content/manuals/desktop/faqs/general.md @@ -65,3 +65,40 @@ For more information and examples, see [how to connect from a container to a ser It is not possible to pass through a USB device (or a serial port) to a container as it requires support at the hypervisor level. + +### How do I run Docker Desktop without administrator privileges? + +Docker Desktop requires administrator privileges only for installation. Once installed, administrator privileges are not needed to run it. However, for non-admin users to run Docker Desktop, it must be installed using a specific installer flag and meet certain prerequisites, which vary by platform. + +{{< tabs >}} +{{< tab name="Mac" >}} + +To run Docker Desktop on Mac without requiring administrator privileges, install via the command line and pass the `—user=` installer flag: + +```console +$ /Applications/Docker.app/Contents/MacOS/install --user= +``` + +You can then sign in to your machine with the user ID specified, and launch Docker Desktop. + +> [!NOTE] +> +> Before launching Docker Desktop, if a `settings.json` file already exists in the `~/Library/Group Containers/group.com.docker/` directory, you will see a **Finish setting up Docker Desktop** window that prompts for administrator privileges when you select **Finish**. To avoid this, ensure you delete the `settings.json` file left behind from any previous installations before launching the application. + +{{< /tab >}} +{{< tab name="Windows" >}} + +> [!NOTE] +> +> If you are using the WSL 2 backend, first make sure that you meet the [minimum required version](/manuals/desktop/wsl/best-practices.md) for WSL 2. Otherwise, update WSL 2 first. + +To run Docker Desktop on Windows without requiring administrator privileges, install via the command line and pass the `—always-run-service` installer flag. + +```console +$ "Docker Desktop Installer.exe" install —always-run-service +``` + +{{< /tab >}} +{{< /tabs >}} + + diff --git a/content/manuals/desktop/install/mac-install.md b/content/manuals/desktop/install/mac-install.md index d6d743afbc88..47379f9f4383 100644 --- a/content/manuals/desktop/install/mac-install.md +++ b/content/manuals/desktop/install/mac-install.md @@ -63,6 +63,10 @@ This page contains download URLs, information about system requirements, and ins ## Install and run Docker Desktop on Mac +> [!TIP] +> +> See the [FAQs](/manuals/desktop/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. + ### Install interactively 1. Download the installer using the download buttons at the top of the page, or from the [release notes](../release-notes.md). diff --git a/content/manuals/desktop/install/windows-install.md b/content/manuals/desktop/install/windows-install.md index 1537e2c845b4..d1e8beff42a4 100644 --- a/content/manuals/desktop/install/windows-install.md +++ b/content/manuals/desktop/install/windows-install.md @@ -164,6 +164,10 @@ again when you switch back. ## Install Docker Desktop on Windows +> [!TIP] +> +> See the [FAQs](/manuals/desktop/faqs/general.md#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges. + ### Install interactively 1. Download the installer using the download button at the top of the page, or from the [release notes](../release-notes.md). From f90323e7c25c27601be6deed76fd87b4d5e7bb2c Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 15 Oct 2024 15:17:13 +0100 Subject: [PATCH 6/9] ENGDOCS-2245 (#21059) * ENGDOCS-2245 * module 1 content * module 1 content * module 2, 3, 4 content * module 2, 3, 4 content * edits and additions * fix build * vale stuff * more vale fun * change step * docs team review edits * KB review --- _vale/config/vocabularies/Docker/accept.txt | 13 +++- content/guides/admin-set-up/_index.md | 69 +++++++++++++++++++ .../admin-set-up/comms-and-info-gathering.md | 33 +++++++++ content/guides/admin-set-up/deploy.md | 18 +++++ .../admin-set-up/finalize-plans-and-setup.md | 43 ++++++++++++ content/guides/admin-set-up/testing.md | 32 +++++++++ 6 files changed, 207 insertions(+), 1 deletion(-) create mode 100644 content/guides/admin-set-up/_index.md create mode 100644 content/guides/admin-set-up/comms-and-info-gathering.md create mode 100644 content/guides/admin-set-up/deploy.md create mode 100644 content/guides/admin-set-up/finalize-plans-and-setup.md create mode 100644 content/guides/admin-set-up/testing.md diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 35a06b4664e0..f1685dadf646 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -65,12 +65,16 @@ Grafana Gravatar HTTP HyperKit +IAM IPs? IPv[46] IPvlan Intel +Intune +Jamf JFrog JetBrains +Kerberos Kitematic Kubernetes LTS @@ -80,16 +84,19 @@ Logstash MAC Mac Mail(chimp|gun) +MDM Microsoft MySQL NAT Netplan Nginx +NTLM Nuxeo OAuth OCI OTel Okta +PAT Postgres PowerShell Python @@ -138,8 +145,10 @@ Zsh [Ff]iletypes? [GgCc]oroutine [Hh]ostname +[Ii]nfosec [Ll]oopback [Mm]oby +[Oo]nboarding [Pp]aravirtualization [Pp]roxying [Rr]eal-time @@ -149,10 +158,12 @@ Zsh [Ss]warm [Tt]oolchains? [Vv]irtualize +[Vv]irtiofs [Ww]alkthrough cgroup config containerd +deprovisioning deserialization deserialize displayName @@ -187,4 +198,4 @@ ufw umask ungated vSphere -virtiofs +vpnkit diff --git a/content/guides/admin-set-up/_index.md b/content/guides/admin-set-up/_index.md new file mode 100644 index 000000000000..0a5bff1818fc --- /dev/null +++ b/content/guides/admin-set-up/_index.md @@ -0,0 +1,69 @@ +--- +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. +levels: [intermediate] +params: + featured: true + 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 Build Cloud subscription information + url: /subscription/build-cloud/build-details/ + - title: Docker Scout subscription information + url: /subscription/scout-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 \ No newline at end of file diff --git a/content/guides/admin-set-up/comms-and-info-gathering.md b/content/guides/admin-set-up/comms-and-info-gathering.md new file mode 100644 index 000000000000..a70f525ab160 --- /dev/null +++ b/content/guides/admin-set-up/comms-and-info-gathering.md @@ -0,0 +1,33 @@ +--- +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 free trials for 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.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 new file mode 100644 index 000000000000..ab91d9f4e568 --- /dev/null +++ b/content/guides/admin-set-up/deploy.md @@ -0,0 +1,18 @@ +--- +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 new file mode 100644 index 000000000000..3f085fb1c556 --- /dev/null +++ b/content/guides/admin-set-up/finalize-plans-and-setup.md @@ -0,0 +1,43 @@ +--- +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 on your baseline and security configurations as outlined in module one, follow the instructions in the [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md) documentation to create the `admin-settings.json` file that captures these configurations. + +Once the file is ready, collaborate with your MDM team to deploy the `admin-settings.json` file, 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 free tier 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](http://build.docker.com). + +[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 new file mode 100644 index 000000000000..d4fd0b805ccc --- /dev/null +++ b/content/guides/admin-set-up/testing.md @@ -0,0 +1,32 @@ +--- +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 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 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. From 8c3965bd0d8c95319c23cdf9bae0251c439ff32e Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 15 Oct 2024 15:17:28 +0100 Subject: [PATCH 7/9] ENGDOCS-2257 (#21115) * ENGDOCS-2257 * clarify methods * Update content/manuals/compose/how-tos/environment-variables/envvars.md --- .../manuals/compose/how-tos/environment-variables/envvars.md | 3 +-- .../how-tos/environment-variables/set-environment-variables.md | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/content/manuals/compose/how-tos/environment-variables/envvars.md b/content/manuals/compose/how-tos/environment-variables/envvars.md index 8531e7072165..05196b5ce4d1 100644 --- a/content/manuals/compose/how-tos/environment-variables/envvars.md +++ b/content/manuals/compose/how-tos/environment-variables/envvars.md @@ -31,8 +31,7 @@ This page contains information on how you can set or change the following pre-de ## Methods to override You can set or change the pre-defined environment variables: -- Within your Compose file using the [`environment` attribute](set-environment-variables.md#use-the-environment-attribute) -- With the `env-file` attribute and an [environment file](set-environment-variables.md#use-the-env_file-attribute) +- With an [`.env` file located in your working director](/manuals/compose/how-tos/environment-variables/variable-interpolation.md) - From the command line - From your [shell](variable-interpolation.md#substitute-from-the-shell) diff --git a/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md b/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md index cdf70b2009da..55db221e9e3d 100644 --- a/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md +++ b/content/manuals/compose/how-tos/environment-variables/set-environment-variables.md @@ -68,7 +68,7 @@ services: env_file: "webapp.env" ``` -Using an `.env` file lets you to use the same file for use by a plain `docker run --env-file ...` command, or to share the same `.env` file within multiple services without the need to duplicate a long `environment` YAML block. +Using an `.env` file lets you use the same file for use by a plain `docker run --env-file ...` command, or to share the same `.env` file within multiple services without the need to duplicate a long `environment` YAML block. It can also help you keep your environment variables separate from your main configuration file, providing a more organized and secure way to manage sensitive information, as you do not need to place your `.env` file in the root of your project's directory. @@ -85,7 +85,6 @@ The paths to your `.env` file, specified in the `env_file` attribute, are relati ### Additional information - If multiple files are specified, they are evaluated in order and can override values set in previous files. -- In addition, as the `.env` file supports [interpolation](variable-interpolation.md), it is possible to combine those with values set by `environment`. - As of Docker Compose version 2.24.0, you can set your `.env` file, defined by the `env_file` attribute, to be optional by using the `required` field. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry. ```yaml env_file: From bcaa915378100bae468deeaee3a4e7909f24ae7b Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 15 Oct 2024 16:15:27 +0100 Subject: [PATCH 8/9] remove ea banner for insights (#21120) --- content/manuals/admin/organization/insights.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/content/manuals/admin/organization/insights.md b/content/manuals/admin/organization/insights.md index a991ecb0a70f..29b6f44f3e45 100644 --- a/content/manuals/admin/organization/insights.md +++ b/content/manuals/admin/organization/insights.md @@ -2,14 +2,8 @@ description: Gain insights about your organization's users and their Docker usage. keywords: organization, insights title: Insights -sitemap: false --- -{{% restricted title="Early Access" %}} -Insights is an [early access](/release-lifecycle#early-access-ea) feature and -is only available to those in the early access feedback program. -{{% /restricted %}} - > [!NOTE] > Insights requires a [Docker Business > subscription](/subscription/core-subscription/details/#docker-business) and From 660044a1c9211020ca22f555da85743f9594ab74 Mon Sep 17 00:00:00 2001 From: Craig Date: Tue, 15 Oct 2024 09:00:01 -0700 Subject: [PATCH 9/9] add build cloud warning Signed-off-by: Craig --- content/manuals/security/for-admins/access-tokens.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/manuals/security/for-admins/access-tokens.md b/content/manuals/security/for-admins/access-tokens.md index 992375934371..87dcc000fe64 100644 --- a/content/manuals/security/for-admins/access-tokens.md +++ b/content/manuals/security/for-admins/access-tokens.md @@ -10,6 +10,11 @@ linkTitle: Organization access tokens (Beta) The organization access tokens feature is currently in [Beta](../../release-lifecycle.md#beta). {{% /experimental %}} +> [!WARNING] +> +> Organization access tokens aren't currently compatible with Docker Build Cloud. If you +> are using Docker Build Cloud, you must use personal access tokens instead. + An organization access token (OAT) is like a [personal access token (PAT)](/security/for-developers/access-tokens/), but an OAT is associated with an organization and not a single user account. Use an OAT instead of a PAT to