docs: add warning about API server OIDC configuration

[zyzzmohit]

Summary

This PR updates the OIDC installation documentation to explicitly state that the Kubernetes API server must be configured to accept OIDC tokens. This addresses confusion where users configure Headlamp for OIDC but forget the underlying cluster configuration.

Related Issue

Fixes #4618

Changes

• Added an "Important" warning note to docs/installation/in-cluster/oidc.md linking to the official Kubernetes OIDC documentation.

Preview

⚠️ Important: For Headlamp's OIDC authentication to work, your Kubernetes cluster's API server must also be configured to accept OIDC tokens. Headlamp handles the user login flow, but the cluster validates the resulting token. See the Kubernetes documentation on OIDC tokens for details.

[k8s-ci-robot]

[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.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Copilot]

Pull request overview

Updates the in-cluster OIDC installation docs to clearly state that Headlamp OIDC login requires the Kubernetes API server to be configured to validate OIDC tokens, addressing a common setup gap reported in #4618.

Changes:

• Added an “Important” warning callout near the top of the OIDC in-cluster installation doc, with a link to the official Kubernetes OIDC token documentation.
• Removed an extra blank line in the Entra ID quick reference section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zyzzmohit]

@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 :)

[illume]

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.

[illume]

@mlbiam this PR enough for the issue you reported?

[illume]

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”

[mlbiam]

@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.