caddyauth: Allow user-configurable headers and status code

[tie]

Summary

This change alllows user-configurable headers and status code for HTTP basic authentication handler.

Motivation

This change allows using basic_auth authentication provider for web proxies (i.e. http_proxy). E.g. forwardproxy currently implements its own authentication that is identical to basic_auth, except that forward proxies use different headers (Authorization → Proxy-Authorization, WWW-Authentication → Proxy-Authenticate) and respond with HTTP status code 407 Proxy Authentication Required instead of 401 Unauthorized.

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Authentication#proxy_authentication

The same challenge and response mechanism can be used for proxy authentication. As both resource authentication and proxy authentication can coexist, a different set of headers and status codes is needed. In the case of proxies, the challenging status code is 407 (Proxy Authentication Required), the Proxy-Authenticate response header contains at least one challenge applicable to the proxy, and the Proxy-Authorization request header is used for providing the credentials to the proxy server.

Changes

• Added authorization_header and authenticate_header fields to basic_auth authentication provider.
• Added status_code field to authentication handler (with support for expressions, similar to static response).
• Moved vendored net/http/internal/ascii package source to internal/ascii.
• Added parseBasicAuth with tests based on net/http.parseBasicAuth. The function itself was copied as is, the tests were modified to cover more edge cases.
• Added integration tests for authentication handler with basic_auth provider (with proxy authentication).

Assistance Disclosure

No AI was used.

[CLAassistant]

All committers have signed the CLA.

[francislavoie]

Thanks, the code looks good (though it seems to be missing Caddyfile support but that may be on purpose?) but I don't understand the motivation. Why would alternate headers ever be used for basic auth? What's the real-world usecase here? What would this allow you to do exactly?

[tie]

Why would alternate headers ever be used for basic auth? What's the real-world usecase here? What would this allow you to do exactly?

This allows using basic_auth for HTTP proxies that use the same authentication flow, except with different headers and status code. See motivation above.

It seems to be missing Caddyfile support but that may be on purpose?

Yes, I don’t think it makes sense to expose this as-is in basic_auth Caddyfile syntax — it’s not really designed to extensible. I find the following confusing

basic_auth bcrypt restricted 407 Proxy-Authorization Proxy-Authenticate {
	Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
}

e.g. compared to

basic_auth {
	status_code 407
	authorization_header Proxy-Authorization
	authenticate_header Proxy-Authenticate
	algorithm bcrypt
	accounts {
		Bob $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
	}
}

[francislavoie]

That doesn't answer my question. In what situation would you need Caddy to solve proxy authentication like this? What is in front of or behind Caddy that would necessitate that? Why not just use the forwardproxy plugin, doesn't it already do that? Describe an actual real-world example (what other software would be used alongside Caddy for this, etc)

Also yes I agree the single line Caddyfile syntax does not make sense, but the block syntax you showed is not actually implemented by your code changes. You didn't update the Caddyfile unmarshal code to add support for those options. Also should have a Caddyfile adapt test (see .caddyfiletest files in the codebase)

[steadytao]

I’ve looked at the PR as a whole and my concern is less about any one implementation detail and more about the overall value/reason for this.

The patch is reasonably complete now but it still feels like a technically competent solution to a problem that has not been shown to belong in Caddy core, to my knowledge. It expands the auth surface with configurable request/response headers, a generic unauthenticated status code, a proxy Caddyfile mode, extra parsing/tests and supporting internal refactoring but the motivating use case still seems to be a narrow proxy-auth workflow that is already handled in proxy-specific code today 🤔

So the question for me is not whether it works code-wise because it seems to but why should core own this? Right now I do not see a compelling reason. The PR demonstrates protocol similarity and code reuse potential but not a compelling need for new core API/config surface. Without that stronger justification this feels like a fair amount of added maintenance burden for limited real benefit.

[francislavoie]

Yeah, without proper justification for this feature to exist in Caddy, I think I'll close this. We can reopen if a good argument is made.