Improve registry authentication documentation

[jhrozek]

Summary

This PR improves the registry authentication documentation based on hands-on testing with a Kind cluster. The main changes address several issues found during review:

• The docs incorrectly equated OAuth with JWT tokens - the server actually supports both JWT and opaque tokens via introspection
• The Kubernetes authentication section had outdated configuration that wouldn't work in practice
• The kubectl get secret example used a legacy approach that produces tokens incompatible with the documented OAuth setup

Related server changes: stacklok/toolhive-registry-server#298

Changes

OAuth token type support

• Clarified that OAuth mode supports both JWT tokens (validated via JWKS) and opaque tokens (validated via introspection)
• Added an example showing opaque token configuration with introspectionUrl
• Updated the token validation section to explain both validation methods

Kubernetes authentication overhaul

• Fixed the issuerUrl - K8s tokens use https://kubernetes.default.svc.cluster.local (with the .cluster.local suffix), not https://kubernetes.default.svc
• Added new configuration fields to the provider table: jwksUrl, authTokenFile, allowPrivateIP
• Added a client workload example showing how to mount projected service account tokens with a specific audience
• Replaced the legacy kubectl get secret example with kubectl create token

Minor improvements

• Added note about WWW-Authenticate header behavior for 401 responses
• Clarified that scopesSupported is currently only advertised in the discovery endpoint

Testing

Tested in a Kind cluster by deploying the registry server with Kubernetes OAuth authentication enabled. The setup used projected service account tokens with a custom audience (registry-server) to verify that audience-based access control works correctly.

Registry server config:

auth:
  mode: oauth
  oauth:
    resourceUrl: http://registry-api.registry-test.svc.cluster.local:8080
    providers:
      - name: kubernetes
        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

Client workload with projected token:

volumes:
  - name: registry-token
    projected:
      sources:
        - serviceAccountToken:
            audience: registry-server
            expirationSeconds: 3600
            path: token

Verified that clients with tokens issued for the correct audience can access the registry, while clients using the default Kubernetes service account token (wrong audience) are rejected with 401. Also confirmed that requests without tokens or with invalid tokens are properly rejected.

The key finding was that the legacy kubectl get secret approach produces tokens with issuer kubernetes/serviceaccount, which doesn't match the expected issuerUrl. Only the modern kubectl create token approach (or projected tokens) produces tokens compatible with the OAuth configuration.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs-website	Ready	Preview	Comment	Dec 12, 2025 5:08pm

[Copilot]

Pull request overview

This PR improves the registry authentication documentation based on hands-on testing with a Kubernetes cluster. The changes address critical inaccuracies in the OAuth token support description and Kubernetes authentication configuration, while adding practical examples for client workloads.

Key changes:

• Clarified that OAuth mode supports both JWT tokens (via JWKS) and opaque tokens (via introspection), not just JWT
• Fixed Kubernetes authentication configuration with correct issuerUrl, added missing fields (jwksUrl, authTokenFile, allowPrivateIP), and replaced legacy token retrieval commands
• Added new sections for opaque token configuration and client workload examples with projected service account tokens

[Copilot]

In the "How Kubernetes authentication works" step 1, the phrase "Workloads mount projected service account tokens" could be clearer. Consider revising to "Workloads mount projected service account tokens (configured with a specific audience)" to make it clear that this requires configuration, as shown in the client workload example below.

Suggested change

	1. Workloads mount projected service account tokens with a specific audience
	1. Workloads mount projected service account tokens (configured with a specific audience)