[Feature] Lazy discovery of oidc provider
Author: wittdennisCreated Sep 9, 2026Updated Sep 14, 2026
Labelsenhancement
Use case
Headscale does OIDC discovery exactly once at startup either stopping execution afterwards if only_start_if_oidc_is_available: true (default) or falling back to cli/web auth.
I use authentik as oidc provider which is only reachable internally via the headscale network. This poses a problem when the network map is stale and headscale can't reach authentik requiring me to restart headscale for oidc to work again.
Description
Stop treating oidc discovery as a hard failure and try discovery again after startup when a user is trying to login.
Contribution
- I can write the design doc for this feature
- I can contribute this feature
How can it be implemented?
- Try oidc discovery once on startup
- When unsuccessful -> On first login make a new discovery check
- If oidc provider is genuinely down give a clear error message to the user
- Try again on another login attempt (with backoff timeouts)
- When successful -> save result and properly setup oidc
- When 'only_start_if_oidc_is_available: true' only checking once at startup then exiting for users that prefer the current behavior
Source: juanfont/headscale