feat: implement OAuth2 authorization endpoint (#2107)

# Summary

This PR implements the OAuth 2.1 authorization endpoint in Supabase
Auth, completing the server-side OAuth flow by adding user authorization
and consent management. Building on the OAuth client registration
foundation (#2098), this enables Supabase Auth to function as an OAuth
2.1 authorization server.

# Features Added
## Authorization Flow Endpoints

- **Authorization Initiation** (`GET /oauth/authorize`) - Initiates
OAuth 2.1 authorization code flow with PKCE support and redirects user
to (for now) pre-configured url
- **Authorization Details** (`GET
/oauth/authorizations/{authorization_id}`) - Retrieves authorization
request details for consent UI
- **Consent Processing** (`POST
/oauth/authorizations/{authorization_id}/consent`) - Handles user
consent decisions (approve/deny)

## Authorization Management

- **PKCE Enforcement** - Mandatory PKCE (RFC 7636) with S256/Plain
support for OAuth 2.1 compliance
- **User Consent Tracking** - Persistent consent storage with
scope-based auto-approval for trusted clients
- **State Management** - Complete authorization lifecycle management
(pending → approved/denied/expired)
- **Security Controls** - Authorization expiration, redirect URI
validation

# Technical Implementation
## Database Schema

- New `oauth_authorizations` table for authorization requests with
status tracking
- New `oauth_consents` table for persistent user consent management  
- Enhanced enums for authorization status and response types
- Comprehensive indexing for performance and cleanup operations

## Code Organization

- Extended `internal/api/oauthserver` package with authorization flow
handlers
- New models: `OAuthServerAuthorization`, `OAuthServerConsent`, and
scope utilities
- Shared PKCE utilities extracted to `internal/models/pkce.go` for reuse
- Context utilities moved to `internal/api/shared` to avoid circular
dependencies

# Future Work

- **Integration Tests** - Add comprehensive integration tests for
authorization flow handlers
- **Audit Logging** - Enhanced audit logging for authorization decisions
and consent management
- **Scope Enforcement** - Currently scope handling provides future
extensibility without active enforcement/utilization

Author: cemalkilic

go.mod

@@ -173,7 +173,7 @@ require (
 	golang.org/x/net v0.38.0 // indirect
 	golang.org/x/sync v0.12.0
 	golang.org/x/sys v0.31.0
-	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/text v0.23.0
 	golang.org/x/time v0.9.0
 	google.golang.org/appengine v1.6.8 // indirect
 	google.golang.org/grpc v1.63.2 // indirect

internal/api/api.go

@@ -88,10 +88,14 @@ func (a *API) deprecationNotices() {
 // NewAPIWithVersion creates a new REST API using the specified version
 func NewAPIWithVersion(globalConfig *conf.GlobalConfiguration, db *storage.Connection, version string, opt ...Option) *API {
 	api := &API{
-		config:      globalConfig,
-		db:          db,
-		version:     version,
-		oauthServer: oauthserver.NewServer(globalConfig, db),
+		config:  globalConfig,
+		db:      db,
+		version: version,
+	}
+
+	// Only initialize OAuth server if enabled
+	if globalConfig.OAuthServer.Enabled {
+		api.oauthServer = oauthserver.NewServer(globalConfig, db)
 	}
 
 	for _, o := range opt {
@@ -171,6 +175,10 @@ func NewAPIWithVersion(globalConfig *conf.GlobalConfiguration, db *storage.Conne
 	r.Get("/health", api.HealthCheck)
 	r.Get("/.well-known/jwks.json", api.Jwks)
 
+	if globalConfig.OAuthServer.Enabled {
+		r.Get("/.well-known/oauth-authorization-server", api.oauthServer.OAuthServerMetadata)
+	}
+
 	r.Route("/callback", func(r *router) {
 		r.Use(api.isValidExternalHost)
 		r.Use(api.loadFlowState)
@@ -185,6 +193,8 @@ func NewAPIWithVersion(globalConfig *conf.GlobalConfiguration, db *storage.Conne
 
 		r.Get("/settings", api.Settings)
 
+		// `/authorize` to initiate OAuth2 authorization flow with the external providers
+		// where Supabase Auth is an OAuth2 Client
 		r.Get("/authorize", api.ExternalProviderRedirect)
 
 		r.With(api.requireAdminCredentials).Post("/invite", api.Invite)
@@ -325,27 +335,37 @@ func NewAPIWithVersion(globalConfig *conf.GlobalConfiguration, db *storage.Conne
 			})
 
 			// Admin only oauth client management endpoints
-			r.Route("/oauth", func(r *router) {
-				r.Route("/clients", func(r *router) {
-					// Manual client registration
-					r.Post("/", api.oauthServer.AdminOAuthServerClientRegister)
-
-					r.Get("/", api.oauthServer.OAuthServerClientList)
-
-					r.Route("/{client_id}", func(r *router) {
-						r.Use(api.oauthServer.LoadOAuthServerClient)
-						r.Get("/", api.oauthServer.OAuthServerClientGet)
-						r.Delete("/", api.oauthServer.OAuthServerClientDelete)
+			if globalConfig.OAuthServer.Enabled {
+				r.Route("/oauth", func(r *router) {
+					r.Route("/clients", func(r *router) {
+						// Manual client registration
+						r.Post("/", api.oauthServer.AdminOAuthServerClientRegister)
+
+						r.Get("/", api.oauthServer.OAuthServerClientList)
+
+						r.Route("/{client_id}", func(r *router) {
+							r.Use(api.oauthServer.LoadOAuthServerClient)
+							r.Get("/", api.oauthServer.OAuthServerClientGet)
+							r.Delete("/", api.oauthServer.OAuthServerClientDelete)
+						})
 					})
 				})
-			})
+			}
 		})
 
 		// OAuth Dynamic Client Registration endpoint (public, rate limited)
-		r.Route("/oauth", func(r *router) {
-			r.With(api.limitHandler(api.limiterOpts.OAuthClientRegister)).
-				Post("/clients/register", api.oauthServer.OAuthServerClientDynamicRegister)
-		})
+		if globalConfig.OAuthServer.Enabled {
+			r.Route("/oauth", func(r *router) {
+				r.With(api.limitHandler(api.limiterOpts.OAuthClientRegister)).
+					Post("/clients/register", api.oauthServer.OAuthServerClientDynamicRegister)
+
+				// OAuth 2.1 Authorization endpoints
+				// `/authorize` to initiate OAuth2 authorization code flow where Supabase Auth is the OAuth2 provider
+				r.Get("/authorize", api.oauthServer.OAuthServerAuthorize)
+				r.With(api.requireAuthentication).Get("/authorizations/{authorization_id}", api.oauthServer.OAuthServerGetAuthorization)
+				r.With(api.requireAuthentication).Post("/authorizations/{authorization_id}/consent", api.oauthServer.OAuthServerConsent)
+			})
+		}
 	})
 
 	corsHandler := cors.New(cors.Options{

internal/api/api_test.go

@@ -55,3 +55,30 @@ func TestEmailEnabledByDefault(t *testing.T) {
 
 	require.True(t, api.config.External.Email.Enabled)
 }
+
+func TestOAuthServerDisabledByDefault(t *testing.T) {
+	api, _, err := setupAPIForTest()
+	require.NoError(t, err)
+
+	// OAuth server should be disabled by default
+	require.False(t, api.config.OAuthServer.Enabled)
+	
+	// OAuth server instance should not be initialized when disabled
+	require.Nil(t, api.oauthServer)
+}
+
+func TestOAuthServerCanBeEnabled(t *testing.T) {
+	api, _, err := setupAPIForTestWithCallback(func(config *conf.GlobalConfiguration, conn *storage.Connection) {
+		if config != nil {
+			// Enable OAuth server
+			config.OAuthServer.Enabled = true
+		}
+	})
+	require.NoError(t, err)
+
+	// OAuth server should be enabled
+	require.True(t, api.config.OAuthServer.Enabled)
+	
+	// OAuth server instance should be initialized when enabled
+	require.NotNil(t, api.oauthServer)
+}

internal/api/apierrors/errorcode.go

@@ -97,4 +97,7 @@ const (
 	ErrorCodeWeb3UnsupportedChain                   ErrorCode = "web3_unsupported_chain"
 	ErrorCodeOAuthDynamicClientRegistrationDisabled ErrorCode = "oauth_dynamic_client_registration_disabled"
 	ErrorCodeEmailAddressNotProvided                ErrorCode = "email_address_not_provided"
+
+	ErrorCodeOAuthClientNotFound        ErrorCode = "oauth_client_not_found"
+	ErrorCodeOAuthAuthorizationNotFound ErrorCode = "oauth_authorization_not_found"
 )

internal/api/context.go

@@ -5,6 +5,7 @@ import (
 	"net/url"
 
 	jwt "github.com/golang-jwt/jwt/v5"
+	"github.com/supabase/auth/internal/api/shared"
 	"github.com/supabase/auth/internal/models"
 )
 
@@ -21,7 +22,6 @@ const (
 	tokenKey            = contextKey("jwt")
 	inviteTokenKey      = contextKey("invite_token")
 	signatureKey        = contextKey("signature")
-	userKey             = contextKey("user")
 	targetUserKey       = contextKey("target_user")
 	factorKey           = contextKey("factor")
 	sessionKey          = contextKey("session")
@@ -60,7 +60,7 @@ func getClaims(ctx context.Context) *AccessTokenClaims {
 
 // withUser adds the user to the context.
 func withUser(ctx context.Context, u *models.User) context.Context {
-	return context.WithValue(ctx, userKey, u)
+	return shared.WithUser(ctx, u)
 }
 
 // withTargetUser adds the target user for linking to the context.
@@ -75,14 +75,7 @@ func withFactor(ctx context.Context, f *models.Factor) context.Context {
 
 // getUser reads the user from the context.
 func getUser(ctx context.Context) *models.User {
-	if ctx == nil {
-		return nil
-	}
-	obj := ctx.Value(userKey)
-	if obj == nil {
-		return nil
-	}
-	return obj.(*models.User)
+	return shared.GetUser(ctx)
 }
 
 // getTargetUser reads the user from the context.