From 98a24cc2a6ed63c51f1cc95bff8d147037d5d40d Mon Sep 17 00:00:00 2001
From: 1seal <security@1seal.org>
Date: Mon, 9 Feb 2026 12:48:46 +0000
Subject: [PATCH] docs: clarify proxy cache trust boundary for upstream
 token-service discovery

document that proxy cache follows upstream WWW-Authenticate bearer realm challenges when obtaining tokens. clarify that token service endpoints can differ from the registry host, and recommend trusted endpoints plus least-privilege upstream credentials. docs-only change; no behavior or config changes.
---
 docs/administration/configure-proxy-cache/_index.md        | 7 ++++++-
 .../create-replication-endpoints.md                        | 6 ++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/administration/configure-proxy-cache/_index.md b/docs/administration/configure-proxy-cache/_index.md
index ba72994ee..af05aa2f1 100644
--- a/docs/administration/configure-proxy-cache/_index.md
+++ b/docs/administration/configure-proxy-cache/_index.md
@@ -38,6 +38,12 @@ The next time a user requests that image, Harbor checks the image's latest manif
 
 As of Harbor v2.1.1, Harbor proxy cache fires a HEAD request to determine whether any layer of a cached image has been updated in the Docker Hub registry. Using this method to check the target registry will not trigger the [Docker Hub rate limiter](https://www.docker.com/blog/scaling-docker-to-serve-millions-more-developers-network-egress/). If any image layer was updated, the proxy cache will pull the new image, which will count towards the Docker Hub rate limiter.
 
+{{< note >}}
+Proxy cache follows upstream registry authentication challenges (for example, `WWW-Authenticate: Bearer realm="..."`) to obtain tokens.
+The token service endpoint can be different from the registry host (for example, Docker Hub).
+Only configure proxy cache endpoints that are within your trust boundary, and use least-privilege credentials for the upstream access account.
+{{< /note >}}
+
 ## Create Proxy Cache Project
 
 To set up a proxy cache, a Harbor system administrators can create a proxy cache project that connects to a target registry using a registry endpoint.
@@ -66,4 +72,3 @@ To start using the proxy cache, configure your docker pull commands or pod manif
 ```bash
 > docker pull <harbor_server_name>/<proxy_project_name>/goharbor/harbor-core:dev
 ```
-
diff --git a/docs/administration/configuring-replication/create-replication-endpoints.md b/docs/administration/configuring-replication/create-replication-endpoints.md
index 9363ccd39..5de011186 100644
--- a/docs/administration/configuring-replication/create-replication-endpoints.md
+++ b/docs/administration/configuring-replication/create-replication-endpoints.md
@@ -47,6 +47,12 @@ You can also use an endpoint in a proxy cache project. Read more about how to [C
    If you plan to use this endpoint with a proxy cache project, the access accounts you provide here enables the proxy cache project to pull every image from the target registry that the access account has permission to pull.
    {{< /note >}}
 
+   {{< note >}}
+   When an endpoint is used for proxy cache, Harbor may obtain tokens by following the upstream `WWW-Authenticate: Bearer realm="..."` challenge.
+   The token service can be hosted on a different domain from the registry.
+   Configure only trusted upstream registries/endpoints and use least-privilege access credentials.
+   {{< /note >}}
+
 1. Optionally, select the **Verify Remote Cert** check box.
 
    Deselect the check box if the remote registry uses a self-signed or untrusted certificate.