From 28adbe758d16f3a1c99aae82e91cd8174846477e Mon Sep 17 00:00:00 2001 From: "Ajeet Singh Raina, Docker Captain, ARM Innovator" Date: Wed, 18 Mar 2026 09:52:19 +0530 Subject: [PATCH] docs(dhi): update OAT authentication support for dhi.io and mirror.md (#24357) ## Description Documents OAT (Organization Access Token) support for authenticating to the dhi.io registry, which was previously undocumented. Adds guidance for CI/CD workflows where org-scoped tokens are preferred over personal credentials. ## Related issues or tickets ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --- content/manuals/dhi/how-to/mirror.md | 62 +++++++++++++++++++++++++--- content/manuals/dhi/how-to/use.md | 18 +++++--- 2 files changed, 69 insertions(+), 11 deletions(-) diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index f44fcd0bd1..f488f9c8e7 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -154,7 +154,7 @@ repository. > [!NOTE] > -> If you only want to stop mirroring ELS versions, you can uncheck the ELS +> If you only want to stop mirroring ELS versions, you can clear the ELS > option in the mirrored repository's **Settings** tab. For more details, see > [Disable ELS for a repository](./els.md#disable-els-for-a-repository). @@ -189,6 +189,56 @@ OCI-aware CLI that supports mirroring images along with attached artifacts such as SBOMs, vulnerability reports, and SLSA provenance. For ongoing synchronization, you can use [`regsync`](https://regclient.org/cli/regsync/). +### Authenticate to `dhi.io` with an organization access token + +You can authenticate to `dhi.io` using an [organization access token +(OAT)](../../enterprise/security/access-tokens.md) instead of a personal access +token (PAT). OATs are owned by the organization rather than an individual user, +which makes them better suited for CI/CD pipelines and automated workflows. + +> [!NOTE] +> +> When using an OAT, use your organization name as the username, not your +> personal Docker ID. OATs are org-scoped and will return a `401 Unauthorized` +> error if presented under an individual user's username. + +To authenticate using an OAT: + +1. Sign in to [Docker Home](https://app.docker.com) and select your organization. +2. Select **Admin Console**, then **Access tokens**. +3. Select **Generate access token**. +4. Give the token a descriptive name, for example `dhi-pull-automation`. +5. Expand the **Repository** drop-down and select **Read public repositories**. +6. Select **Generate token**, then copy and save the token. You won't be able + to retrieve it after closing the screen. +7. Sign in to `dhi.io` using your organization name as the username and the OAT + as the password: + + ```console + $ oras login dhi.io -u + ``` + + Or non-interactively in a CI/CD pipeline: + + ```console + $ echo $OAT | oras login dhi.io -u "$DOCKER_ORG" --password-stdin + ``` + +8. Verify access by discovering attestations on a DHI image: + + ```console + $ oras discover dhi.io/node:24-dev --platform linux/amd64 + ``` + + > [!NOTE] + > + > The `--platform` flag is required. Without it, `oras discover` resolves to + > the multi-arch image index, which returns only an index-level signature + > rather than the full set of per-platform attestations. + + A successful response lists the attestations attached to the image, + including SBOMs, provenance, vulnerability reports, and changelog metadata. + ### Example mirroring with `regctl` The following example shows how to mirror a specific tag of a Docker Hardened @@ -198,7 +248,7 @@ attestations using `regctl`. You must [install The example assumes you have mirrored the DHI repository to your organization's namespace on Docker Hub as described in the previous section. You can apply the -same steps to a non-mirrored image by updating the the `SRC_ATT_REPO` and +same steps to a non-mirrored image by updating the `SRC_ATT_REPO` and `SRC_REPO` variables accordingly. 1. Set environment variables for your specific environment. Replace the @@ -207,10 +257,12 @@ same steps to a non-mirrored image by updating the the `SRC_ATT_REPO` and In this example, you use a Docker username to represent a member of the Docker Hub organization that the DHI repositories are mirrored in. Prepare a [personal access token (PAT)](../../security/access-tokens.md) for the user - with `read only` access. Alternatively, you can use an organization namespace and + with `read only` access. Alternatively, you can use your organization name and an [organization access token - (OAT)](../../enterprise/security/access-tokens.md) to sign in to Docker Hub, but OATs - are not yet supported for `registry.scout.docker.com`. + (OAT)](../../enterprise/security/access-tokens.md) to authenticate with `docker.io`. + Note that OATs are not supported for `registry.scout.docker.com`. If your + workflow requires authenticating to the Scout registry, use a personal access + token (PAT) for that step. ```console $ export DOCKER_USERNAME="YOUR_DOCKER_USERNAME" diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index a46f884592..17c57d51c0 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -12,26 +12,32 @@ reference them in your Dockerfile, and run containers with `docker run`. The key difference is that DHIs are security-focused and intentionally minimal to reduce the attack surface. This means some variants don't include a shell or -package manager, and may run as a nonroot user by default. +package manager, and may run as a non-root user by default. > [!IMPORTANT] > > You must authenticate to the Docker Hardened Images registry (`dhi.io`) to -> pull images. Use your Docker ID credentials (the same username and password -> you use for Docker Hub) when signing in. If you don't have a Docker account, -> [create one](../../accounts/create-account.md) for free. +> pull images. You can authenticate using either of the following: +> +> - **Docker ID (personal credentials):** Use the same username and password +> you use for Docker Hub. If you don't have a Docker account, +> [create one](../../accounts/create-account.md) for free. +> - **Organization access token (OAT):** Use your organization name as the +> username and an OAT as the password. OATs are recommended for CI/CD +> pipelines and automated workflows. See +> [Organization access tokens](../../enterprise/security/access-tokens.md). > > Run `docker login dhi.io` to authenticate. ## Considerations when adopting DHIs -Docker Hardened Images are intentionally minimal to improve security. If you're updating existing Dockerfiles or frameworks to use DHIs, keep the following considerations in mind: +Docker Hardened Images are intentionally minimal to improve security. If you're updating existing Dockerfiles or frameworks to use DHIs, keep the considerations in mind: | Feature | Details | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | No shell or package manager | Runtime images don’t include a shell or package manager. Use `-dev` or `-sdk` variants in build stages to run shell commands or install packages, and then copy artifacts to a minimal runtime image. | | Non-root runtime | Runtime DHIs default to running as a non-root user. Ensure your application doesn't require privileged access and that all needed files are readable and executable by a non-root user. | -| Ports | Applications running as non-root users can't bind to ports below 1024 in older versions of Docker or in some Kubernetes configurations. Use ports above 1024 for compatibility. | +| Ports | Applications running as non-root users can't bind to ports lower than 1024 in older versions of Docker or in some Kubernetes configurations. Use ports higher than 1024 for compatibility. | | Entry point | DHIs may not include a default entrypoint or might use a different one than the original image you're familiar with. Check the image configuration and update your `CMD` or `ENTRYPOINT` directives accordingly. | | Multi-stage builds | Always use multi-stage builds for frameworks: a `-dev` image for building or installing dependencies, and a minimal runtime image for the final stage. | | TLS certificates | DHIs include standard TLS certificates. You do not need to manually install CA certs. |