backend: Implement support for Azure AKS managed OIDC auth provider

[daviddob]

This allows for enabling configuration for AKS managed OIDC and is also more flexible for other auth providers in the following ways:

• Allows overriding the clientID and issuerURL for validation phases
• Allows for grabbing the access_token instead of id_token.

All three of these changes are required in the case of AKS due to its nonstandard OIDC flow where it returns an access token from a single MSFT controlled enterprise application with the ID 6dae42f8-4368-4678-94ff-3960e28e3630 msft docs source. This is also apparent with other auth providers having nonstandard flows and token issuance this could potentially resolve as well.

The access_token returned is also using the older v1 token as opposed to the newer v2 tokens. This is not possible to override even when setting up your enterprise app to only issue v2 tokens, if the scope includes 6dae42f8-4368-4678-94ff-3960e28e3630/user.read, then it will be issues from a v1 endpoint. This means that the issuer returned in the token does not match the one obtained in discovery as it transitions from https://login.microsoftonline.com/<tenant-uuid>/v2.0 to https://sts.windows.net/<tenant-uuid>/ msft source

The above can be confirmed with any AKS managed OIDC cluster and kubelogin flow followed by decoding the token returned to you.

This implements three new flags oidc-validator-idp-issuer-url, oidc-validator-client-id, and oidc-use-access-token to permit the above required alterations to token validation

Closes: #2480, #1498 (will provide tests and docs for the above)

Related to:

• OIDC token times out too quickly on web client #2358 Older AAD login flows are deprecated for this new manged aks oidc
• I get redirected to OIDC auth pop up each time I click on any link/button inside headlamp UI. I'm using Azure AD for OIDC config. Headlamp installed in the cluster via helm #2848 (Was experiencing the same behavior when trying to log in with headlamp using the id_token

Testing & Docs

This can be tested by building the image from source, and deploying it to a K8s cluster with the following additional args defined in the helm chart (in addition to the standard OIDC config pointing at your azure ad enterprise app)

extraArgs:
  - "-oidc-validator-client-id=6dae42f8-4368-4678-94ff-3960e28e3630"
  - "-oidc-validator-idp-issuer-url=https://sts.windows.net/<your-tenant-uuid>/"
  - "-oidc-use-access-token"

Before writing out all of the tests and docs (I have this working and tested against both this approach and the one discussed below), I wanted to get some initial feedback on the changes and which method is preferred. From there id be happy to button up the tests, helm chart, and docs accordingly to get users able to auth with AKS managed OIDC implementations.

Alternate Options

Alternatively this can be implemented with a single flag specifically for Azure AKS managed OIDC oidc-use-aks-managed. Implementation is here and adds only a single configuration value but is also then specific for AKS only which may not be desired. https://github.com/kubernetes-sigs/headlamp/compare/main...daviddob:headlamp:azure-aks-managed-oidc-support-simplified?expand=1

[illume]

Thanks for all this.

I'm starting to understand access_token is for authorization, and id_token is for authentication. It seems other providers use access_token from a bit of searching about. So I think this way is probably better, than the AKS specific flag.

It would be helpful to have some guidance of how to set this up for testing? Setting up AKS (following the link you posted I guess?)

Then where to get this? "https://sts.windows.net/<your-tenant-uuid>/" I imagine this needs something to be set up first too.

[ashu8912]

Thanks for all this.

I'm starting to understand access_token is for authorization, and id_token is for authentication. It seems other providers use access_token from a bit of searching about. So I think this way is probably better, than the AKS specific flag.

It would be helpful to have some guidance of how to set this up for testing? Setting up AKS (following the link you posted I guess?)

Then where to get this? "https://sts.windows.net/<your-tenant-uuid>/" I imagine this needs something to be set up first too.

I think https://sts.windows.net/<your-tenant-uuid> the tenant-uuid is your entra id app tenant id

[daviddob]

Yupp that's exactly right, I'll try to get the documentation and tests implemented shortly. Will include links to the MSFT docs for setting up entra OIDC with AKS and then steps for setting up the enterprise app + headlamp with the new parameters

[daviddob]

Planning on writing up the documentation tonight - I updated the helm chart accordingly for the 3 methods of setting the config properties (env, inline, or external secret) as well. Let me know if anything should be adjusted there, technically these are all parameters that could be set via the extraArgs field in the chart as follows with indirect references to env vars/secrets or with hardcoded values.

- "-oidc-validator-client-id=$(OIDC_VALIDATOR_CLIENT_ID)"
- "-oidc-validator-idp-issuer-url=$(OIDC_VALIDATOR_ISSUER_URL)"
- "-oidc-use-access-token=$(OIDC_USE_ACCESS_TOKEN)"

Absolutely down to drop the helm chart changes it it introduces too much clutter in favor of just these parameters called out in the documentation (whichever you believe is the best approach)

[daviddob]

Documentation and tutorials have been added - would be happy to add anything else for clarity or additional testing for validation. Let me know if there's anything else I should do for next steps. Thanks!

[ashu8912]

Thanks @daviddob for adding this, I am in the process of reviewing and testing this, will get back to you with more updates

[joaquimrocha]

I just want to second how awesome this is! Thank you @daviddob !

[illume]

🎉 thanks!

I didn’t test the chart changes. They look ok to me, but I’ll ask our local chart expert @knrt10 to have a quick look before we merge.

[ashu8912]

Tested this with AKS and EntraID, and this works like charm, and the docs as well are on point, thanks, lets wait for @knrt10 final approval and then we are good to go

[knrt10]

Awesome. Thanks for the change @daviddob

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ashu8912, daviddob, illume, knrt10

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [illume]

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

[viceice]

it seems this has broken oidc auth: #2643 (comment)

We're getting this error now:

Failed to verify ID Token: oidc: id token issued by a different provider, expected "$(OIDC_VALIDATOR_ISSUER_URL)" got "https://codeberg.org/"

[joaquimrocha]

Thanks @viceice . We are looking into it. Thanks!

[daviddob]

Replied in issue #2643 (comment), can write up a quick patch for this approach as well as the doc version confusion here #3380 if desired and no one has triaged this yet.

[Invincibear]

It seems that this doesn't handle the edge case where an access token for an Entra ID user has already been exchanged, and redeploying Headlamp loses the refresh token.

Failed to exchange token: oauth2: "invalid_grant" "AADSTS54005: 
OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token. 
Trace ID: 00000000-0000-0000-0000-000000000000 
Correlation ID: 00000000-0000-0000-0000-000000000000 
Timestamp: 2025-08-02 20:22:22Z"

I've tried the following, they all result in the same AADSTS54005 error:

• Nuking the Entra ID App Registration & Enterprise App
• Removing Headlamp from https://myapps.microsoft.com
• Signing out from all Microsoft locations
• Private browsing tab
• Logging in with an entirely different browser to rule out caching/cookies/local storage entirely
• Nuking Headlamp from Kubernetes, and redeploying all of the above with a new App Client Id & Client Secret
• Appending &conset=prompt to the Microsoft login url to force re-granting consent