Add external auth helper support (OIDC/OAuth2, cookies, etc.)

[baralai329]

Adds a generic auth helper interface that lets Nagstamon delegate authentication to an external command. This enables OIDC, OAuth2, SAML, or any custom auth scheme without modifying Nagstamon's core.

Providing documentation and an example implementation for others to use.

[HenriWahl]

Thanks @baralai329 - I will need some time to check.

[HenriWahl]

Just one question: can you explain how this is intended to work? What is the external auth helper?

[baralai329]

In summary the the external auth helper is a standalone command-line program that you write and configure to handle authentication for Nagstamon.

When authentication is needed, Nagstamon calls the auth helper.

That external helper performs the actual login process (for example with OIDC or OAuth2) and needs to return headers (e.g. token) or a cookie in the specified format.

Nagstamon then uses those returned credentials to make authenticated requests to the systems it monitors. It does that by adding these credentials to the HTTP session.

[HenriWahl]

Sorry for the late answer, but I am actually not convinced that this merge request should be merged. If the authentication is delegated to some not yet existing external script, what is the use of it? So the magic work needs to be done somewhere else. I think this makes it all more complicated.

[baralai329]

I understand the concern about complexity. The reason the auth logic lives externally is that every organization's SSO setup is different (different providers, client IDs, token endpoints). It's the same pattern Git uses with git credential helpers and kubectl uses with --exec credential plugins. The core tool stays simple, and the environment-specific auth is handled outside.

For existing users, nothing will change. This is purely opt-in via a new config field. No one who doesn't configure it is affected.

Here's a concrete use case: I'm trying to monitor services protected by a corporate OIDC SSO. Nagstamon currently has no way to authenticate against these. This PR makes that possible without baking one specific OIDC implementation into the core.