Support using Proxy-Authenticate and Proxy-Authorization rather than WWW-Authenticate and Authorization

[pqnet]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

While the header option allow setting Proxy-Authorization as source for auth data, we are missing the ability to customize the response header sent to the browser to trigger authentication to Proxy-Authenticate.

I suggest adding an optional header parameter in the authenticate option.

Motivation

When running fastify-basic-auth plugin in a proxy to perform authentication, it should rely on the standard headers Proxy-Authenticate and Proxy-Authorization, leaving WWW-Authenticate and Authorization free for the proxied webapp to use.

Example

options = {
    authenticate: { realm: "My Realm", header: "Proxy-Authorization" }
}

[pqnet]

To support Proxy-Authenticate it is necessary to also change the response status code to 407
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Proxy-Authenticate

I have created a PR that should take care of the header part, but I'm not sure what would be the right way to implement status code customization.
It may also be a good idea to support only the 407/Proxy-Authenticate/Proxy-Authorization case rather than making them entirely configurable - that is adding a boolean flag that switches all of them at the same time. For my use case that would be enough.

I seek guidance on this.

[jsumners]

The opening of the readme for this project is rather clear that the module is designed to implement https://datatracker.ietf.org/doc/html/rfc7617. Honestly, this is the first time I have heard of the headers mentioned in this issue. Some cursory reading makes me think that supporting them in this module would lead to confusion and complications in the code. I think that a new "proxy-authentication" module should be written that handles this specific use case.

https://www.rfc-editor.org/rfc/rfc9110.html#name-authenticating-clients-to-p

[pqnet]

The opening of the readme for this project is rather clear that the module is designed to implement https://datatracker.ietf.org/doc/html/rfc7617. Honestly, this is the first time I have heard of the headers mentioned in this issue. Some cursory reading makes me think that supporting them in this module would lead to confusion and complications in the code. I think that a new "proxy-authentication" module should be written that handles this specific use case.

https://www.rfc-editor.org/rfc/rfc9110.html#name-authenticating-clients-to-p

If this module only implements basic auth, it should not even do the 401/WWW-Authenticate/Authorization part, but only parsing/formatting/validating the content of these headers.

The cited RFC mentions both on the same level, and gives an external reference for both (https://datatracker.ietf.org/doc/html/rfc7235#section-3.2, obsoleted by https://datatracker.ietf.org/doc/html/rfc9110)

Quoting directly:

This document defines the "Basic" Hypertext Transfer Protocol (HTTP)
authentication scheme, which transmits credentials as user-id/
password pairs, encoded using Base64 (HTTP authentication schemes are
defined in [RFC7235]).

This scheme is not considered to be a secure method of user
authentication unless used in conjunction with some external secure
system such as TLS (Transport Layer Security, [RFC5246]), as the
user-id and password are passed over the network as cleartext.

The "Basic" scheme previously was defined in Section 2 of [RFC2617].
This document updates the definition, and also addresses
internationalization issues by introducing the 'charset'
authentication parameter (Section 2.1).

Other documents updating RFC 2617 are "Hypertext Transfer Protocol
(HTTP/1.1): Authentication" ([RFC7235], defining the authentication
framework), "HTTP Digest Access Authentication" ([RFC7616], updating
the definition of the "Digest" authentication scheme), and "HTTP
Authentication-Info and Proxy-Authentication-Info Response Header
Fields" ([RFC7615]). Taken together, these four documents obsolete
RFC 2617.

The proxy authentication is right below that, in the examples section:

Upon receipt of a request for a URI within the protection space that
lacks credentials, the server can reply with a challenge using the
401 (Unauthorized) status code ([RFC7235], Section 3.1) and the
WWW-Authenticate header field ([RFC7235], Section 4.1).

For instance:

  HTTP/1.1 401 Unauthorized
  Date: Mon, 04 Feb 2014 16:50:53 GMT
  WWW-Authenticate: Basic realm="WallyWorld"

where "WallyWorld" is the string assigned by the server to identify
the protection space.

A proxy can respond with a similar challenge using the 407 (Proxy
Authentication Required) status code ([RFC7235], Section 3.2) and the
Proxy-Authenticate header field ([RFC7235], Section 4.3).