feat: Add Sb-Forwarded-For header and IP-based rate limiting (#2295)

## What kind of change does this PR introduce?

This PR adds support for IP address forwarding using a new header,
`Sb-Forwarded-For`, optionally gated by
`GOTRUE_SECURITY_SB_FORWARDED_FOR_ENABLED`. When this feature is
enabled, both `utilities.GetIPAddress` and rate limiting will use the
first value of the `Sb-Forwarded-For` header as the IP address/rate
limiting key.

If the feature is disabled or the `Sb-Forwarded-For` header contains an
invalid value, Auth will fall back to existing behavior.

## What is the current behavior?

There are currently two paths along which users are likely to use IP
address information. The first is IP tracking (e.g., logging, MFA
challenge validation, and CAPTCHA challenge validation). The second is
rate limiting. Both of these follow slightly different logical paths,
relying on the `X-Forwarded-For` header explicitly in the former case
and a separate rate limiting key header in the latter.

The presence of these two paths results in some friction for users.
`X-Forwarded-For` can be (and frequently is) rewritten by proxies or
otherwise spoofed, and there is no guarantee that a rate limiting key in
the rate limit header is an IP address.

## What is the new behavior?

The API uses a new middleware, `sbff.Middleware`, that parses the
`Sb-Forwarded-For` header and inserts it into the request context if
`GOTRUE_SECURITY_SB_FORWARDED_FOR_ENABLED` is true. Consumers of the
`Sb-Forwarded-For` header can use `sbff.GetIPAddress` to retrieve the
parsed IP address.

`utilities.GetIPAddress` will prefer the result of `sbff.GetIPAddress`
as the end-user IP address if the feature is enabled and the
`Sb-Forwarded-For` header contains a value value. Similarly, Auth will
use the end user IP address as determined by `sbff.GetIPAddress` as the
rate limiting key under the same circumstances.

If the feature is not enabled or the `Sb-Forwarded-For` header is absent
or otherwise invalid, Auth will default to existing/legacy behavior.

Author: jnschaeffer

README.md

@@ -888,6 +888,12 @@ Enforce reauthentication on password update.
 
 Use this to enable/disable anonymous sign-ins.
 
+### IP address forwarding
+
+`GOTRUE_SECURITY_SB_FORWARDED_FOR_ENABLED` - `bool`
+
+Enable IP address forwarding using the `Sb-Forwarded-For` HTTP request header. When enabled, Auth will parse the first value of this header as an IP address and use it for IP address tracking and rate limiting. Make sure this header is fully trusted before enabling this feature by only passing it from trustworthy clients or proxies.
+
 ## Endpoints
 
 Auth exposes the following endpoints:

internal/api/api.go

@@ -19,6 +19,7 @@ import (
 	"github.com/supabase/auth/internal/mailer/templatemailer"
 	"github.com/supabase/auth/internal/models"
 	"github.com/supabase/auth/internal/observability"
+	"github.com/supabase/auth/internal/sbff"
 	"github.com/supabase/auth/internal/storage"
 	"github.com/supabase/auth/internal/tokens"
 	"github.com/supabase/auth/internal/utilities"
@@ -152,8 +153,17 @@ func NewAPIWithVersion(globalConfig *conf.GlobalConfiguration, db *storage.Conne
 	r := newRouter()
 	r.UseBypass(observability.AddRequestID(globalConfig))
 	r.UseBypass(logger)
-	r.UseBypass(xffmw.Handler)
 	r.UseBypass(recoverer)
+	r.UseBypass(
+		sbff.Middleware(
+			&globalConfig.Security,
+			func(r *http.Request, err error) {
+				log := observability.GetLogEntry(r).Entry
+				log.WithField("error", err.Error()).Warn("error processing Sb-Forwarded-For")
+			},
+		),
+	)
+	r.UseBypass(xffmw.Handler)
 
 	if globalConfig.API.MaxRequestDuration > 0 {
 		r.UseBypass(timeoutMiddleware(globalConfig.API.MaxRequestDuration))

internal/api/middleware.go

@@ -20,6 +20,7 @@ import (
 	"github.com/supabase/auth/internal/api/shared"
 	"github.com/supabase/auth/internal/models"
 	"github.com/supabase/auth/internal/observability"
+	"github.com/supabase/auth/internal/sbff"
 	"github.com/supabase/auth/internal/security"
 	"github.com/supabase/auth/internal/utilities"
 
@@ -61,7 +62,7 @@ func (f *FunctionHooks) UnmarshalJSON(b []byte) error {
 
 var emailRateLimitCounter = observability.ObtainMetricCounter("gotrue_email_rate_limit_counter", "Number of times an email rate limit has been triggered")
 
-func (a *API) performRateLimiting(lmt *limiter.Limiter, req *http.Request) error {
+func (a *API) performRateLimitingWithHeader(lmt *limiter.Limiter, req *http.Request) error {
 	limitHeader := a.config.RateLimitHeader
 
 	// If no rate limit header was set, ignore rate limiting
@@ -112,6 +113,18 @@ func (a *API) performRateLimiting(lmt *limiter.Limiter, req *http.Request) error
 	return nil
 }
 
+func (a *API) performRateLimiting(lmt *limiter.Limiter, req *http.Request) error {
+	if sbffAddr, ok := sbff.GetIPAddress(req); ok {
+		if err := tollbooth.LimitByKeys(lmt, []string{sbffAddr}); err != nil {
+			return apierrors.NewTooManyRequestsError(apierrors.ErrorCodeOverRequestRateLimit, "Request rate limit reached")
+		}
+
+		return nil
+	}
+
+	return a.performRateLimitingWithHeader(lmt, req)
+}
+
 func (a *API) limitHandler(lmt *limiter.Limiter) middlewareHandler {
 	return func(w http.ResponseWriter, req *http.Request) (context.Context, error) {
 		return req.Context(), a.performRateLimiting(lmt, req)

internal/api/middleware_test.go

@@ -19,6 +19,7 @@ import (
 	"github.com/stretchr/testify/suite"
 	"github.com/supabase/auth/internal/api/apierrors"
 	"github.com/supabase/auth/internal/conf"
+	"github.com/supabase/auth/internal/sbff"
 	"github.com/supabase/auth/internal/storage"
 )
 
@@ -415,7 +416,166 @@ func TestTimeoutResponseWriter(t *testing.T) {
 	require.Equal(t, w1.Result(), w2.Result())
 }
 
-func (ts *MiddlewareTestSuite) TestPerformRateLimiting() {
+func (ts *MiddlewareTestSuite) TestPerformRateLimitingWithSBFF() {
+	origRateLimitHeader := ts.Config.RateLimitHeader
+	origSBFFEnabled := ts.Config.Security.SbForwardedForEnabled
+
+	defer func() {
+		ts.Config.RateLimitHeader = origRateLimitHeader
+		ts.Config.Security.SbForwardedForEnabled = origSBFFEnabled
+	}()
+
+	ts.Config.RateLimitHeader = "X-Test-Perform-Rate-Limiting"
+	ts.Config.Security.SbForwardedForEnabled = true
+
+	type headerSet struct {
+		rateLimiting   string
+		sbForwardedFor string
+	}
+
+	testCases := []struct {
+		name         string
+		headerValues []headerSet
+		expErr       error
+	}{
+		{
+			name: "multiple SBFF values, single rate limiting value",
+			headerValues: []headerSet{
+				{
+					sbForwardedFor: "192.168.1.100",
+					rateLimiting:   "60.60.60.60",
+				},
+				{
+					sbForwardedFor: "192.168.1.200",
+					rateLimiting:   "60.60.60.60",
+				},
+			},
+			expErr: nil,
+		},
+		{
+			name: "single SBFF value, multiple rate limiting values",
+			headerValues: []headerSet{
+				{
+					sbForwardedFor: "192.168.1.100",
+					rateLimiting:   "60.60.60.60",
+				},
+				{
+					sbForwardedFor: "192.168.1.100",
+					rateLimiting:   "70.70.70.70",
+				},
+			},
+			expErr: apierrors.NewTooManyRequestsError(
+				apierrors.ErrorCodeOverRequestRateLimit,
+				"Request rate limit reached",
+			),
+		},
+		{
+			name: "no SBFF value, multiple rate limiting values",
+			headerValues: []headerSet{
+				{
+					sbForwardedFor: "",
+					rateLimiting:   "60.60.60.60",
+				},
+				{
+					sbForwardedFor: "",
+					rateLimiting:   "70.70.70.70",
+				},
+			},
+			expErr: nil,
+		},
+		{
+			name: "no SBFF value, single rate limiting value",
+			headerValues: []headerSet{
+				{
+					sbForwardedFor: "",
+					rateLimiting:   "60.60.60.60",
+				},
+				{
+					sbForwardedFor: "",
+					rateLimiting:   "60.60.60.60",
+				},
+			},
+			expErr: apierrors.NewTooManyRequestsError(
+				apierrors.ErrorCodeOverRequestRateLimit,
+				"Request rate limit reached",
+			),
+		},
+		{
+			name: "invalid SBFF value, multiple rate limiting values",
+			headerValues: []headerSet{
+				{
+					sbForwardedFor: "invalid",
+					rateLimiting:   "60.60.60.60",
+				},
+				{
+					sbForwardedFor: "invalid",
+					rateLimiting:   "70.70.70.70",
+				},
+			},
+			expErr: nil,
+		},
+		{
+			name: "invalid SBFF value, single rate limiting value",
+			headerValues: []headerSet{
+				{
+					sbForwardedFor: "invalid",
+					rateLimiting:   "60.60.60.60",
+				},
+				{
+					sbForwardedFor: "invalid",
+					rateLimiting:   "60.60.60.60",
+				},
+			},
+			expErr: apierrors.NewTooManyRequestsError(
+				apierrors.ErrorCodeOverRequestRateLimit,
+				"Request rate limit reached",
+			),
+		},
+	}
+
+	// This test uses the SBFF middleware to inject the Sb-Forwarded-For IP address value, then
+	// wraps a handler that calls performRateLimiting and stores the error value.
+	for _, tc := range testCases {
+		lmt := tollbooth.NewLimiter(
+			1,
+			&limiter.ExpirableOptions{
+				DefaultExpirationTTL: time.Hour,
+			},
+		)
+
+		var obsErr error
+
+		var handler http.HandlerFunc = func(rw http.ResponseWriter, r *http.Request) {
+			obsErr = ts.API.performRateLimiting(lmt, r)
+		}
+
+		errCallback := func(r *http.Request, err error) {
+		}
+
+		middleware := sbff.Middleware(&ts.Config.Security, errCallback)
+
+		wrappedHandler := middleware(handler)
+
+		for _, h := range tc.headerValues {
+			r := httptest.NewRequest(http.MethodGet, "http://localhost/", nil)
+
+			if h.rateLimiting != "" {
+				r.Header.Set(ts.Config.RateLimitHeader, h.rateLimiting)
+			}
+
+			if h.sbForwardedFor != "" {
+				r.Header.Set(sbff.HeaderName, h.sbForwardedFor)
+			}
+
+			wrappedHandler.ServeHTTP(nil, r)
+		}
+
+		require.ErrorIs(ts.T(), obsErr, tc.expErr)
+	}
+
+}
+
+func (ts *MiddlewareTestSuite) TestPerformRateLimitingWithHeader() {
 	ts.Config.RateLimitHeader = "X-Test-Perform-Rate-Limiting"
 
 	tests := []struct {

internal/conf/configuration.go

@@ -731,6 +731,7 @@ type SecurityConfiguration struct {
 	RefreshTokenAllowReuse                bool                 `json:"refresh_token_allow_reuse" split_words:"true"`
 	UpdatePasswordRequireReauthentication bool                 `json:"update_password_require_reauthentication" split_words:"true"`
 	ManualLinkingEnabled                  bool                 `json:"manual_linking_enabled" split_words:"true" default:"false"`
+	SbForwardedForEnabled                 bool                 `json:"sb_forwarded_for_enabled" split_words:"true" default:"false"`
 
 	DBEncryption DatabaseEncryptionConfiguration `json:"database_encryption" split_words:"true"`
 }

internal/sbff/sbff.go

@@ -0,0 +1,94 @@
+package sbff
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"strings"
+
+	"github.com/supabase/auth/internal/conf"
+)
+
+// HeaderName is the Sb-Forwarded-For header name. It is all lowercase here as HTTP header names
+// are not case-sensitive.
+const HeaderName = "sb-forwarded-for"
+
+var (
+	ctxKeySBFF = &struct{}{}
+
+	ErrHeaderNotFound = errors.New("Sb-Forwarded-For header not found")
+	ErrHeaderInvalid  = errors.New("invalid Sb-Forwarded-For header value")
+)
+
+func parseSBFFHeader(headerVal string) (string, error) {
+	values := strings.SplitN(headerVal, ",", 2)
+	key := strings.TrimSpace(values[0])
+	if ipAddr := net.ParseIP(key); ipAddr != nil {
+		return ipAddr.String(), nil
+	}
+
+	return "", ErrHeaderInvalid
+}
+
+// GetIPAddress returns the value of the IP address in Sb-Forwarded-For as defined by
+// SBForwardedForMiddleware. If no value is present in the request context, this function will
+// return ("", false).
+func GetIPAddress(r *http.Request) (addr string, found bool) {
+	if ipAddr, ok := r.Context().Value(ctxKeySBFF).(string); ok && ipAddr != "" {
+		return ipAddr, true
+	}
+
+	return "", false
+}
+
+// withIPAddress parses the Sb-Forwarded-For header and adds the leftmost value to the
+// request context if it is a valid IP address, then returns a new request with modified context.
+// If the leftmost value is not a valid IP address or the header is not set, this function returns
+// an error.
+func withIPAddress(r *http.Request) (*http.Request, error) {
+	headerVal := r.Header.Get(HeaderName)
+	if headerVal == "" {
+		return nil, ErrHeaderNotFound
+	}
+
+	parsedIPAddr, err := parseSBFFHeader(headerVal)
+	if err != nil {
+		return nil, err
+	}
+
+	ctx := r.Context()
+	newCtx := context.WithValue(ctx, ctxKeySBFF, parsedIPAddr)
+	out := r.WithContext(newCtx)
+
+	return out, nil
+}
+
+// Middleware returns a middleware function that parses the Sb-Forwarded-For header
+// and adds the leftmost header value to the request context if GOTRUE_SECURITY_SB_FORWARDED_FOR_ENABLED
+// is true and the value is a valid IP address.
+func Middleware(cfg *conf.SecurityConfiguration, errCallback func(*http.Request, error)) func(http.Handler) http.Handler {
+	out := func(next http.Handler) http.Handler {
+		handlerFunc := func(rw http.ResponseWriter, r *http.Request) {
+			if !cfg.SbForwardedForEnabled {
+				next.ServeHTTP(rw, r)
+				return
+			}
+
+			reqWithSBFF, err := withIPAddress(r)
+			switch {
+			case err == nil:
+				next.ServeHTTP(rw, reqWithSBFF)
+			case errors.Is(err, ErrHeaderNotFound):
+				next.ServeHTTP(rw, r)
+			default:
+				errCallback(r, err)
+				next.ServeHTTP(rw, r)
+			}
+		}
+
+		return http.HandlerFunc(handlerFunc)
+	}
+
+	return out
+}