auth: add www-authenticate header (#282)

Author: System-Glitch

auth/authenticator.go

@@ -2,6 +2,7 @@ package auth
 
 import (
 	"context"
+	"fmt"
 	"net/http"
 
 	"goyave.dev/goyave/v5"
@@ -11,6 +12,8 @@ import (
 // if this meta is present in the matched route or any of its parent and is equal to `true`.
 const MetaAuth = "goyave.require-auth"
 
+const defaultRealm = "Authorization required"
+
 // Authenticator is an object in charge of authenticating a client.
 //
 // The generic type should be a DTO and not be a pointer. The `request.User`
@@ -31,6 +34,16 @@ type Authenticator[T any] interface {
 	Authenticate(request *goyave.Request) (*T, error)
 }
 
+// SchemeAuthenticator let Authenticators indicate their scheme for use in the WWW-Authenticate
+// header returned when authentication fails.
+// The header is not returned if the authenticator doesn't implement this interface.
+type SchemeAuthenticator interface {
+	// Scheme returns the authenticator's scheme.
+	// The returned value should be one of the values in the IANA's HTTP Authentication Schemes list.
+	// https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml
+	Scheme() string
+}
+
 // UserService is the dependency of authenticators used to retrieve a user by its "username".
 //
 // A username is actually any identifier (an ID, a email, a name, etc). It is the responsibility
@@ -56,13 +69,21 @@ type Unauthorizer interface {
 // The T parameter represents the user DTO and should not be a pointer.
 type Handler[T any] struct {
 	Authenticator[T]
+
+	// Realm describes the protected area. It is returned in the
+	// `WWW-Authenticate` header on authentication failure if the
+	// Authenticator implements `SchemeAuthenticator`.
+	// If empty, "Authorization Required" will be used by default.
+	Realm string
 }
 
 // Handle on success, set the request's `User` to the user returned by the authenticator
 // and inject it in the request's `context.Context`. The user can be retrieved from the
 // context using `UserFromContext`.
 //
 // Blocks if the authentication is not successful.
+// If the authenticator implements `SchemeAuthenticator`, add the `WWW-Authenticate` header
+// to the response.
 // If the authenticator implements `Unauthorizer`, `OnUnauthorized` is called,
 // otherwise returns a default `401 Unauthorized` error.
 // If the matched route doesn't contain the `MetaAuth` or if it's not equal to `true`,
@@ -76,6 +97,9 @@ func (m *Handler[T]) Handle(next goyave.Handler) goyave.Handler {
 
 		user, err := m.Authenticate(request)
 		if err != nil {
+			if authenticateHeader := m.getAuthenticateHeader(); authenticateHeader != "" {
+				response.Header().Set("WWW-Authenticate", authenticateHeader)
+			}
 			if unauthorizer, ok := m.Authenticator.(Unauthorizer); ok {
 				unauthorizer.OnUnauthorized(response, request, err)
 				return
@@ -89,6 +113,14 @@ func (m *Handler[T]) Handle(next goyave.Handler) goyave.Handler {
 	}
 }
 
+func (m *Handler[T]) getAuthenticateHeader() string {
+	sa, ok := m.Authenticator.(SchemeAuthenticator)
+	if !ok {
+		return ""
+	}
+	return fmt.Sprintf(`%s realm="%s", charset="UTF-8"`, sa.Scheme(), m.Realm)
+}
+
 // Middleware returns an authentication middleware which will use the given
 // authenticator and set the request's `User` according to the generic type `T`, which
 // should be a DTO.
@@ -98,8 +130,18 @@ func (m *Handler[T]) Handle(next goyave.Handler) goyave.Handler {
 // If the matched route or any of its parent doesn't have this meta or if it's not equal to
 // `true`, the authentication is skipped.
 func Middleware[T any](authenticator Authenticator[T]) *Handler[T] {
+	return MiddlewareWithRealm(authenticator, defaultRealm)
+}
+
+// MiddlewareWithRealm is the same as `Middleware` but with a custom realm description.
+// The realm describes the protected area and is returned in the `WWW-Authenticate` header
+// when the authentication fails.
+// Note that the `WWW-Authenticate` header is NOT added to the response if the authenticator
+// doesn't implement `SchemeAuthenticator`.
+func MiddlewareWithRealm[T any](authenticator Authenticator[T], realm string) *Handler[T] {
 	return &Handler[T]{
 		Authenticator: authenticator,
+		Realm:         realm,
 	}
 }
 

auth/authenticator_test.go

@@ -40,6 +40,14 @@ func (a *TestBasicUnauthorizer) OnUnauthorized(response *goyave.Response, _ *goy
 	response.JSON(http.StatusUnauthorized, map[string]string{"custom error key": err.Error()})
 }
 
+type TestNoScheme struct {
+	goyave.Component
+}
+
+func (a *TestNoScheme) Authenticate(request *goyave.Request) (*BasicUser, error) {
+	return (&ConfigBasicAuthenticator{Component: a.Component}).Authenticate(request)
+}
+
 func prepareAuthenticatorTest(t *testing.T) (*testutil.TestServer, *TestUser) {
 	cfg := config.LoadDefault()
 	cfg.Set("database.connection", "sqlite3")
@@ -64,6 +72,7 @@ func TestAuthenticator(t *testing.T) {
 
 		mockUserService := &MockUserService[TestUser]{user: user}
 		authenticator := Middleware(NewBasicAuthenticator(mockUserService, "Password"))
+		assert.Equal(t, defaultRealm, authenticator.Realm)
 
 		request := server.NewTestRequest(http.MethodGet, "/protected", nil)
 		request.Request().SetBasicAuth(user.Email, "secret")
@@ -77,6 +86,7 @@ func TestAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 
 		request = server.NewTestRequest(http.MethodGet, "/protected", nil)
 		request.Request().SetBasicAuth(user.Email, "incorrect password")
@@ -89,6 +99,7 @@ func TestAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Equal(t, `Basic realm="Authorization required", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("NoAuth", func(t *testing.T) {
@@ -108,6 +119,7 @@ func TestAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 
 		request.Route = &goyave.Route{Meta: map[string]any{}}
 		resp = server.TestMiddleware(authenticator, request, func(response *goyave.Response, request *goyave.Request) {
@@ -116,6 +128,7 @@ func TestAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("MiddlewareUnauthorizer", func(t *testing.T) {
@@ -136,6 +149,51 @@ func TestAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"custom error key": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Equal(t, `Basic realm="Authorization required", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
+	})
+
+	t.Run("MiddlewareWithRealm", func(t *testing.T) {
+		server, user := prepareAuthenticatorTest(t)
+		t.Cleanup(func() { server.CloseDB() })
+
+		mockUserService := &MockUserService[TestUser]{user: user}
+		authenticator := MiddlewareWithRealm(&TestBasicUnauthorizer{BasicAuthenticator: NewBasicAuthenticator(mockUserService, "Password")}, "custom realm")
+
+		request := server.NewTestRequest(http.MethodGet, "/protected", nil)
+		request.Request().SetBasicAuth(user.Email, "incorrect password")
+		request.Route = &goyave.Route{Meta: map[string]any{MetaAuth: true}}
+		resp := server.TestMiddleware(authenticator, request, func(response *goyave.Response, _ *goyave.Request) {
+			response.Status(http.StatusOK)
+		})
+		assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+		body, err := testutil.ReadJSONBody[map[string]string](resp.Body)
+		assert.NoError(t, resp.Body.Close())
+		require.NoError(t, err)
+		assert.Equal(t, map[string]string{"custom error key": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Equal(t, `Basic realm="custom realm", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
+	})
+
+	t.Run("MiddlewareWithRealmNoScheme", func(t *testing.T) {
+		server, user := prepareAuthenticatorTest(t)
+		t.Cleanup(func() { server.CloseDB() })
+
+		server.Config().Set("auth.basic.username", "johndoe")
+		server.Config().Set("auth.basic.password", "secret")
+
+		authenticator := MiddlewareWithRealm(&TestNoScheme{}, "custom realm")
+
+		request := server.NewTestRequest(http.MethodGet, "/protected", nil)
+		request.Request().SetBasicAuth(user.Email, "incorrect password")
+		request.Route = &goyave.Route{Meta: map[string]any{MetaAuth: true}}
+		resp := server.TestMiddleware(authenticator, request, func(response *goyave.Response, _ *goyave.Request) {
+			response.Status(http.StatusOK)
+		})
+		assert.Equal(t, http.StatusUnauthorized, resp.StatusCode)
+		body, err := testutil.ReadJSONBody[map[string]string](resp.Body)
+		assert.NoError(t, resp.Body.Close())
+		require.NoError(t, err)
+		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate")) // Authentication doesn't implement SchemeAuthenticator, header should not be added
 	})
 }
 

auth/basic.go

@@ -84,6 +84,10 @@ func (a *BasicAuthenticator[T]) Authenticate(request *goyave.Request) (*T, error
 	return user, nil
 }
 
+func (a *BasicAuthenticator[T]) Scheme() string {
+	return "Basic"
+}
+
 //--------------------------------------------
 
 func init() {
@@ -131,6 +135,10 @@ func (a *ConfigBasicAuthenticator) Authenticate(request *goyave.Request) (*Basic
 	}, nil
 }
 
+func (a *ConfigBasicAuthenticator) Scheme() string {
+	return "Basic"
+}
+
 // ConfigBasicAuth create a new authenticator middleware for
 // config-based Basic authentication. On auth success, the request
 // user is set to a `*BasicUser`.
@@ -139,3 +147,10 @@ func (a *ConfigBasicAuthenticator) Authenticate(request *goyave.Request) (*Basic
 func ConfigBasicAuth() *Handler[BasicUser] {
 	return Middleware(&ConfigBasicAuthenticator{})
 }
+
+// ConfigBasicAuthWithRealm is the same as ConfigBasicAuth but with a custom realm description.
+// The realm describes the protected area and is returned in the `WWW-Authenticate` header
+// when the authentication fails.
+func ConfigBasicAuthWithRealm(realm string) *Handler[BasicUser] {
+	return MiddlewareWithRealm(&ConfigBasicAuthenticator{}, realm)
+}

auth/basic_test.go

@@ -31,6 +31,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("success_ptr", func(t *testing.T) {
@@ -50,6 +51,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("wrong_password", func(t *testing.T) {
@@ -69,6 +71,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Equal(t, `Basic realm="Authorization required", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("service_error", func(t *testing.T) {
@@ -87,6 +90,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusInternalServerError, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("optional_success", func(t *testing.T) {
@@ -107,14 +111,15 @@ func TestBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("optional_wrong_password", func(t *testing.T) {
 		server, user := prepareAuthenticatorTest(t)
 		mockUserService := &MockUserService[TestUser]{user: user}
 		a := NewBasicAuthenticator(mockUserService, "Password")
 		a.Optional = true
-		authenticator := Middleware(a)
+		authenticator := MiddlewareWithRealm(a, "custom realm")
 
 		request := server.NewTestRequest(http.MethodGet, "/protected", nil)
 		request.Request().SetBasicAuth(user.Email, "wrong password")
@@ -128,6 +133,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Equal(t, `Basic realm="custom realm", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("optional_no_auth", func(t *testing.T) {
@@ -145,6 +151,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("no_auth", func(t *testing.T) {
@@ -164,6 +171,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.no-credentials-provided")}, body)
+		assert.Equal(t, `Basic realm="Authorization required", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("non-existing_password_field", func(t *testing.T) {
@@ -182,6 +190,7 @@ func TestBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusInternalServerError, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 }
 
@@ -200,6 +209,7 @@ func TestConfigBasicAuthenticator(t *testing.T) {
 		})
 		assert.Equal(t, http.StatusOK, resp.StatusCode)
 		assert.NoError(t, resp.Body.Close())
+		assert.Empty(t, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("wrong_password", func(t *testing.T) {
@@ -219,6 +229,7 @@ func TestConfigBasicAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.invalid-credentials")}, body)
+		assert.Equal(t, `Basic realm="Authorization required", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
 	})
 
 	t.Run("no_auth", func(t *testing.T) {
@@ -228,7 +239,7 @@ func TestConfigBasicAuthenticator(t *testing.T) {
 		server := testutil.NewTestServerWithOptions(t, goyave.Options{Config: cfg})
 		request := server.NewTestRequest(http.MethodGet, "/protected", nil)
 		request.Route = &goyave.Route{Meta: map[string]any{MetaAuth: true}}
-		resp := server.TestMiddleware(ConfigBasicAuth(), request, func(response *goyave.Response, _ *goyave.Request) {
+		resp := server.TestMiddleware(ConfigBasicAuthWithRealm("custom realm"), request, func(response *goyave.Response, _ *goyave.Request) {
 			assert.Fail(t, "middleware passed despite failed authentication")
 			response.Status(http.StatusOK)
 		})
@@ -237,5 +248,6 @@ func TestConfigBasicAuthenticator(t *testing.T) {
 		assert.NoError(t, resp.Body.Close())
 		require.NoError(t, err)
 		assert.Equal(t, map[string]string{"error": server.Lang.GetDefault().Get("auth.no-credentials-provided")}, body)
+		assert.Equal(t, `Basic realm="custom realm", charset="UTF-8"`, resp.Header.Get("WWW-Authenticate"))
 	})
 }

auth/jwt.go

@@ -299,3 +299,7 @@ func (a *JWTAuthenticator[T]) makeError(language *lang.Language, err error) erro
 		return fmt.Errorf("%s", language.Get("auth.jwt-invalid"))
 	}
 }
+
+func (a *JWTAuthenticator[T]) Scheme() string {
+	return "Bearer"
+}