#3462·headscale

[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