[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: zyzzmohit
Once this PR has been reviewed and has the lgtm label, please assign yolossn for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

@illume @sniok
Friendly bump! 👋 Just checking in — this is a small docs-only change (2 lines) adding an important warning about API server OIDC configuration, which addresses the confusion reported in #4618. Would appreciate a review when you get a chance. Thanks :)

Maybe what you have is ok and fine enough. But I’m a bit unclear about the conditions that bring people here. Maybe you can help me understand?

How will people find this? What happens if it’s not? Maybe we can the error behavior here for folks to search for it.

I’m also wondering if those docs are adequate for folks configuring a cloud k8s instance? Or is this not something they will encounter?

Not like below(the details are probably wrong), but I think add the error condition they encounter to what you have and a note how to do this on a cloud provider is cloud provider specific (if it’s relevant at all to them?)

⚠️ Important: For Headlamp’s OIDC authentication to work, your Kubernetes API server must be configured to accept and validate OIDC tokens (for example by setting --oidc-issuer-url, --oidc-client-id, and the username/groups claims). Headlamp performs the login flow and returns a token, but the API server validates that token. If the API server is not configured, Headlamp’s login may succeed but subsequent API calls will be rejected with 401/403 errors. See the Kubernetes OIDC docs (link) and your cloud provider’s guidance for details.

Or maybe what you have already is better, and these two things are not needed.

@mlbiam this PR enough for the issue you reported?

I wonder if we can add into an error message into headlamp when people encounter this something like: “Have you configured your api server? If not see: xxx”

@illume

1. +1 for an error message that tells the user that the cluster isn't integrated
2. I'd recommend starting with that headlamp calls kubernetes APIs on the user's behalf, so the token must be accepted by kubernetes. Also include that the issuer and audience must be the same.

Thanks for the feedback @illume and @mlbiam! Great suggestions.

I agree the warning can be more actionable. I'll update it to include:

The specific API server flags (--oidc-issuer-url, --oidc-client-id, etc.)
The error behavior users will see (login succeeds but API calls fail with 401/403)
A note that the issuer and audience must match between Headlamp's config and the API server
A mention that cloud provider OIDC configuration is provider-specific
Something along the lines of what @illume suggested:

⚠️ Important: Headlamp performs the OIDC login flow and obtains a token, but it then calls Kubernetes APIs on the user's behalf — so the API server must be configured to accept and validate that token. The --oidc-issuer-url and --oidc-client-id flags (along with username/groups claim flags) must be set on the API server, and the issuer and audience must match your Headlamp OIDC configuration. If the API server is not configured, Headlamp login may succeed but subsequent API calls will be rejected with 401/403 errors. See the Kubernetes OIDC docs for details. For managed Kubernetes services (EKS, AKS, GKE), refer to your cloud provider's documentation for OIDC configuration.

Regarding the in-app error message idea — I think that's a great enhancement and worth tracking separately. I can open a follow-up issue for detecting when OIDC token validation fails at the API server level and surfacing a helpful message like "Your cluster's API server may not be configured to accept OIDC tokens. See: [link]". Would that work, or would you prefer it as part of this PR?

I'll push the docs update shortly!

I've updated the warning to be much more actionable. It now includes:

That Headlamp calls Kubernetes APIs on the user's behalf, so the API server must validate the token
Specific API server flags (--oidc-issuer-url, --oidc-client-id, username/groups claims)
The requirement that issuer and audience must match between Headlamp's config and the API server
The error behavior users will encounter (login succeeds but API calls fail with 401/403 errors)
A note about cloud provider-specific OIDC configuration (EKS, AKS, GKE)
Updated link pointing to the API server OIDC configuration docs

Please take a look at the updated changes and let me know if anything else needs tweaking :)