docs(headlamp): document authentication methods and troubleshooting

Add clear documentation for both OIDC and token-based authentication.
Include troubleshooting section for common 403 errors caused by
using tokens from wrong namespace.

Fixes issue where token was generated from kube-system instead of
headlamp namespace, causing 403 errors on metrics API.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/headlamp/README.md

@@ -39,4 +39,47 @@ Users authenticate through the Pocket ID SSO and receive cluster-admin permissio
 After deployment via ArgoCD, access the dashboard at:
 https://headlamp.basicstack.de
 
-Users will be redirected to Pocket ID for authentication before accessing the cluster dashboard.
+### Authentication Methods
+
+#### 1. OIDC Authentication (Recommended)
+
+Users will be redirected to Pocket ID for authentication. Once OIDC is fully configured in Pocket ID:
+- Navigate to https://headlamp.basicstack.de
+- Click "Sign in with OIDC"
+- Authenticate via Pocket ID
+- Headlamp uses the `headlamp-admin` ServiceAccount for all Kubernetes API calls
+
+#### 2. Token-Based Authentication (Fallback)
+
+For testing or when OIDC is not available, you can use token-based authentication:
+
+```bash
+# Generate a token from the headlamp-admin ServiceAccount
+kubectl create token headlamp-admin -n headlamp
+
+# Copy the token and paste it in the Headlamp login form
+```
+
+**Important**: The ServiceAccount exists in the `headlamp` namespace, not `kube-system`. Using the wrong namespace will result in 403 errors when accessing Kubernetes APIs.
+
+The token has `cluster-admin` permissions and provides full access to all cluster resources including metrics APIs.
+
+## Troubleshooting
+
+### 403 Errors on Metrics API
+
+If you see 403 errors like `GET https://headlamp.basicstack.de/clusters/main/apis/metrics.k8s.io/v1beta1/nodes`:
+
+**Cause**: Using a token from the wrong namespace or a ServiceAccount without sufficient permissions.
+
+**Solution**: Generate the token from the correct namespace:
+```bash
+kubectl create token headlamp-admin -n headlamp
+```
+
+### Asset Loading Errors
+
+If you encounter errors loading JavaScript assets, check:
+- Ingress configuration is correct
+- TLS certificate is valid
+- Browser console for specific error messages