Improve registry authentication documentation (#394)

* Add opaque token and introspection support to auth docs

- Clarify OAuth mode supports both JWT and opaque tokens
- Add introspectionUrl field to provider configuration table
- Add opaque token configuration example using Google
- Update terminology from OIDC-compliant to OAuth-compliant

* Clarify token validation for JWT vs opaque tokens

Move JWT-specific signature verification details under a separate
paragraph that distinguishes between JWT and opaque token validation
methods.

* Update Kubernetes authentication docs with tested configuration

- Update provider config with correct issuerUrl (.cluster.local suffix)
- Add jwksUrl, authTokenFile, and allowPrivateIP fields to config table
- Add client workload example with projected service account tokens
- Replace legacy kubectl get secret with kubectl create token
- Add tip explaining projected tokens vs kubectl create token
- Update "How it works" section to reflect audience-based auth

* Add WWW-Authenticate note and clarify scopesSupported

- Add note about WWW-Authenticate header in RFC 9728 section
- Clarify that scopesSupported is for discovery endpoint advertisement

Author: jhrozek

docs/toolhive/guides-registry/authentication.mdx

@@ -29,9 +29,17 @@ unless you explicitly choose anonymous mode for development scenarios.
 
 ## OAuth authentication
 
-OAuth mode (the default) validates JWT tokens from identity providers. This
-enables enterprise authentication with providers like Keycloak, Auth0, Okta,
-Azure AD, Kubernetes service accounts, or any OIDC-compliant service.
+OAuth mode (the default) validates access tokens from identity providers. The
+server supports two token formats:
+
+- **JWT tokens**: Validated locally using the provider's public keys (JWKS
+  endpoint). This is the most common format for modern identity providers.
+- **Opaque tokens**: Validated via token introspection (RFC 7662) by querying
+  the provider's introspection endpoint. Use this when your provider issues
+  non-JWT tokens.
+
+This enables enterprise authentication with providers like Keycloak, Auth0,
+Okta, Azure AD, Kubernetes service accounts, or any OAuth-compliant service.
 
 ### Basic OAuth configuration
 
@@ -53,7 +61,7 @@ auth:
 | `mode`            | string   | Yes      | `oauth`                                   | Authentication mode (`oauth` or `anonymous`)       |
 | `resourceUrl`     | string   | Yes      | -                                         | The URL of the registry resource being protected   |
 | `realm`           | string   | No       | `mcp-registry`                            | OAuth realm identifier                             |
-| `scopesSupported` | []string | No       | `[mcp-registry:read, mcp-registry:write]` | Supported OAuth scopes                             |
+| `scopesSupported` | []string | No       | `[mcp-registry:read, mcp-registry:write]` | OAuth scopes advertised in the discovery endpoint  |
 | `publicPaths`     | []string | No       | `[]`                                      | Additional paths accessible without authentication |
 | `providers`       | array    | Yes      | -                                         | List of OAuth/OIDC identity providers              |
 
@@ -63,10 +71,14 @@ auth:
 | ------------------ | ------ | -------- | ----------------------------------------------------------------------- |
 | `name`             | string | Yes      | Provider identifier for logging and monitoring                          |
 | `issuerUrl`        | string | Yes      | OAuth/OIDC issuer URL (e.g., `https://keycloak.example.com/realms/mcp`) |
-| `audience`         | string | Yes      | Expected audience claim in the JWT token                                |
-| `clientId`         | string | No       | OAuth client ID (for token introspection)                               |
-| `clientSecretFile` | string | No       | Path to file containing client secret (for token introspection)         |
+| `audience`         | string | Yes      | Expected audience claim in the access token                             |
+| `jwksUrl`          | string | No       | JWKS endpoint URL (skips OIDC discovery if specified)                   |
+| `introspectionUrl` | string | No       | Token introspection endpoint URL for opaque token validation            |
+| `clientId`         | string | No       | OAuth client ID (for authenticated introspection requests)              |
+| `clientSecretFile` | string | No       | Path to file containing client secret (for authenticated introspection) |
 | `caCertPath`       | string | No       | Path to CA certificate for TLS verification                             |
+| `authTokenFile`    | string | No       | Path to token file for authenticating JWKS/introspection requests       |
+| `allowPrivateIP`   | bool   | No       | Allow connections to private IP addresses (for in-cluster use)          |
 
 ### Complete OAuth configuration example
 
@@ -94,6 +106,27 @@ auth:
         audience: registry-api-staging
 ```
 
+### Opaque token configuration
+
+When your identity provider issues opaque (non-JWT) tokens, configure the
+`introspectionUrl` field to enable token introspection:
+
+```yaml title="config-opaque-tokens.yaml"
+auth:
+  mode: oauth
+  oauth:
+    resourceUrl: https://registry.example.com
+    providers:
+      - name: google
+        issuerUrl: https://accounts.google.com
+        introspectionUrl: https://oauth2.googleapis.com/tokeninfo
+        audience: 407408718192.apps.googleusercontent.com
+```
+
+The server automatically detects the token format and uses the appropriate
+validation method—attempting JWT validation first and falling back to token
+introspection if needed.
+
 ## Kubernetes authentication
 
 For Kubernetes deployments, you can configure OAuth to validate service account
@@ -109,26 +142,31 @@ auth:
     resourceUrl: https://registry.example.com
     providers:
       - name: kubernetes
-        issuerUrl: https://kubernetes.default.svc
-        audience: https://kubernetes.default.svc
+        issuerUrl: https://kubernetes.default.svc.cluster.local
+        jwksUrl: https://kubernetes.default.svc/openid/v1/jwks
+        audience: registry-server
         caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+        authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
+        allowPrivateIP: true
 ```
 
-:::tip[In-cluster service DNS]
+:::info[Kubernetes-specific configuration]
 
-The correct Kubernetes API server URL for in-cluster access is
-`https://kubernetes.default.svc` (not
-`https://kubernetes.default.svc.cluster.local`).
+- **issuerUrl**: Use `https://kubernetes.default.svc.cluster.local` to match the
+  `iss` claim in Kubernetes service account tokens.
+- **jwksUrl**: Specify the JWKS endpoint directly to skip OIDC discovery.
+- **authTokenFile**: The server uses this token to authenticate when fetching
+  the JWKS from the Kubernetes API server.
+- **allowPrivateIP**: Required for in-cluster communication with the API server.
 
 :::
 
 ### How Kubernetes authentication works
 
-1. Workloads in the cluster mount service account tokens automatically at
-   `/var/run/secrets/kubernetes.io/serviceaccount/token`
+1. Workloads mount projected service account tokens with a specific audience
 2. Clients send these tokens in the `Authorization: Bearer <TOKEN>` header
 3. The server validates tokens using the Kubernetes API server's public keys
-4. Access is granted based on the service account's identity and token claims
+4. Only tokens with the correct audience (e.g., `registry-server`) are accepted
 
 ### Kubernetes deployment example
 
@@ -174,6 +212,39 @@ The service account token and CA certificate are automatically mounted at:
 - Token: `/var/run/secrets/kubernetes.io/serviceaccount/token`
 - CA cert: `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`
 
+### Client workload example
+
+Clients that need to authenticate with the registry should mount a projected
+service account token with the correct audience:
+
+```yaml title="client-workload.yaml"
+apiVersion: v1
+kind: Pod
+metadata:
+  name: registry-client
+spec:
+  serviceAccountName: my-client-sa
+  containers:
+    - name: client
+      image: my-client-image
+      volumeMounts:
+        - name: registry-token
+          mountPath: /var/run/secrets/registry
+          readOnly: true
+  volumes:
+    - name: registry-token
+      projected:
+        sources:
+          - serviceAccountToken:
+              audience: registry-server
+              expirationSeconds: 3600
+              path: token
+```
+
+The client reads the token from `/var/run/secrets/registry/token` and includes
+it in the `Authorization: Bearer <TOKEN>` header when making requests to the
+registry.
+
 ## Provider-specific examples
 
 ### Keycloak
@@ -317,6 +388,10 @@ GET /.well-known/oauth-protected-resource
 This allows OAuth clients to automatically configure themselves without manual
 setup, improving interoperability and reducing configuration errors.
 
+When a request fails authentication, the server returns a `WWW-Authenticate`
+header that includes a link to the discovery endpoint, helping clients locate
+the authentication requirements.
+
 ## Testing authentication
 
 ### Using curl with a bearer token
@@ -330,17 +405,27 @@ curl -H "Authorization: Bearer $TOKEN" \
 
 ### Using kubectl with Kubernetes service accounts
 
+Use `kubectl create token` to generate a token with the correct audience:
+
 ```bash
-# Get the service account token
-TOKEN=$(kubectl get secret <service-account-token-name> \
+# Create a token with the registry-server audience
+TOKEN=$(kubectl create token <service-account-name> \
   -n <namespace> \
-  -o jsonpath='{.data.token}' | base64 -d)
+  --audience=registry-server)
 
 # Make authenticated request
 curl -H "Authorization: Bearer $TOKEN" \
-  https://registry.example.com/default/v0.1/servers
+  https://registry.example.com/registry/v0.1/servers
 ```
 
+:::tip[Projected tokens vs kubectl create token]
+
+For automated workloads, use projected service account tokens (see
+[Client workload example](#client-workload-example)). The `kubectl create token`
+command is useful for manual testing and debugging.
+
+:::
+
 ### Testing token validation
 
 To verify your token is valid:
@@ -373,12 +458,14 @@ To verify your token is valid:
 
 All OAuth providers validate:
 
-- Token signature using the provider's public keys (fetched from issuer's JWKS
-  endpoint)
 - Token expiration (`exp` claim)
 - Audience claim (`aud`) matches configuration
 - Issuer (`iss`) matches the configured provider
 
+For JWT tokens, signature verification uses the provider's public keys (fetched
+from the issuer's JWKS endpoint). For opaque tokens, the server queries the
+configured `introspectionUrl` to validate the token.
+
 ### HTTPS requirements
 
 Always use HTTPS in production to protect tokens in transit: