centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 06:18:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs(dhi): update OAT authentication support for dhi.io and mirror.md (#24357)

Browse Source 
<!--Delete sections as needed -->

## 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.

<!-- Tell us what you did and why -->

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
This commit is contained in:
Ajeet Singh Raina, Docker Captain, ARM Innovator
2026-03-18 09:52:19 +05:30
committed by GitHub
parent 8c5bfcc895
commit 28adbe758d
2 changed files with 69 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
content/manuals/dhi/how-to/mirror.md
View File

@@ -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 <YOUR_ORGANIZATION_NAME>
```
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"

18
content/manuals/dhi/how-to/use.md
View File

@@ -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. |