OAuth2 - 💧 Mizu

Overview

The oauth2 middleware provides OAuth 2.0 authentication flows for integrating with providers like Google, GitHub, Facebook, and custom OAuth servers. Use it when you need:

Social login (Google, GitHub, etc.)
Third-party authentication
OAuth 2.0 authorization code flow

Installation

import "github.com/go-mizu/mizu/middlewares/oauth2"

Quick Start

app := mizu.New()

// Configure OAuth provider
config := oauth2.Config{
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
    RedirectURL:  "http://localhost:3000/callback",
    AuthURL:      "https://provider.com/oauth/authorize",
    TokenURL:     "https://provider.com/oauth/token",
    Scopes:       []string{"email", "profile"},
}

app.Get("/login", oauth2.Login(config))
app.Get("/callback", oauth2.Callback(config, handleUser))

Configuration

Config

Field	Type	Description
`ClientID`	`string`	OAuth client ID
`ClientSecret`	`string`	OAuth client secret
`RedirectURL`	`string`	Callback URL
`AuthURL`	`string`	Provider’s auth endpoint
`TokenURL`	`string`	Provider’s token endpoint
`Scopes`	`[]string`	Requested scopes

Examples

Google OAuth

config := oauth2.Google(oauth2.Config{
    ClientID:     os.Getenv("GOOGLE_CLIENT_ID"),
    ClientSecret: os.Getenv("GOOGLE_CLIENT_SECRET"),
    RedirectURL:  "http://localhost:3000/auth/google/callback",
    Scopes:       []string{"email", "profile"},
})

app.Get("/auth/google", oauth2.Login(config))
app.Get("/auth/google/callback", oauth2.Callback(config, func(c *mizu.Ctx, token *oauth2.Token, user *oauth2.User) error {
    // User authenticated successfully
    session.Get(c).Set("user_id", user.ID)
    return c.Redirect(302, "/dashboard")
}))

GitHub OAuth

config := oauth2.GitHub(oauth2.Config{
    ClientID:     os.Getenv("GITHUB_CLIENT_ID"),
    ClientSecret: os.Getenv("GITHUB_CLIENT_SECRET"),
    RedirectURL:  "http://localhost:3000/auth/github/callback",
    Scopes:       []string{"user:email"},
})

app.Get("/auth/github", oauth2.Login(config))
app.Get("/auth/github/callback", oauth2.Callback(config, handleGitHubUser))

Custom Provider

config := oauth2.Config{
    ClientID:     "client-id",
    ClientSecret: "client-secret",
    RedirectURL:  "http://localhost:3000/callback",
    AuthURL:      "https://auth.example.com/authorize",
    TokenURL:     "https://auth.example.com/token",
    UserInfoURL:  "https://api.example.com/userinfo",
    Scopes:       []string{"openid", "profile"},
}

State Parameter

app.Get("/login", oauth2.LoginWithState(config, func(c *mizu.Ctx) string {
    // Generate state with return URL
    return base64.URLEncoding.EncodeToString([]byte(c.Query("return_url")))
}))

API Reference

Functions

// Login starts OAuth flow
func Login(config Config) mizu.Handler

// LoginWithState starts flow with custom state
func LoginWithState(config Config, stateFn func(*mizu.Ctx) string) mizu.Handler

// Callback handles OAuth callback
func Callback(config Config, handler CallbackHandler) mizu.Handler

// Provider presets
func Google(config Config) Config
func GitHub(config Config) Config
func Facebook(config Config) Config

Types

type Token struct {
    AccessToken  string
    RefreshToken string
    Expiry       time.Time
}

type User struct {
    ID       string
    Email    string
    Name     string
    Picture  string
    Provider string
}

type CallbackHandler func(*mizu.Ctx, *Token, *User) error

Technical Details

Architecture

The OAuth2 middleware is designed as a resource server implementation that validates OAuth 2.0 access tokens. It follows a flexible architecture that supports multiple validation strategies:

Token Extraction: Supports multiple token sources (header, query, form) via configurable TokenLookup parameter
Token Validation: Two validation strategies:
- Custom validator function for flexibility
- Token introspection endpoint (RFC 7662) for standard OAuth servers
Scope Verification: Automatic scope checking against required scopes
Context Storage: Validated token information is stored in request context for downstream handlers

Token Validation Flow

Extract token from request based on TokenLookup configuration
Validate token using:
- Custom Validator function if provided, or
- OAuth 2.0 token introspection endpoint
Check token expiration if ExpiresAt is set
Verify required scopes match token scopes
Store validated token in context
Pass request to next handler

Token Introspection

When using the introspection endpoint, the middleware:

Sends POST request to IntrospectionURL with token
Uses Basic authentication with ClientID and ClientSecret if provided
Parses introspection response according to RFC 7662
Validates the active field and extracts token metadata (subject, scopes, expiry)

Error Handling

The middleware returns appropriate HTTP status codes:

401 Unauthorized: Missing, invalid, or expired tokens
403 Forbidden: Insufficient scopes
Sets WWW-Authenticate: Bearer header on errors

Custom error handling can be implemented via the ErrorHandler option.

Context Access

Helper functions provide convenient access to token information:

Get(c): Retrieves full token object
Subject(c): Gets token subject
Scopes(c): Returns token scopes
HasScope(c, scope): Checks for specific scope

Scope Middleware

The RequireScopes middleware can be chained after the main OAuth2 middleware to enforce scope requirements at specific routes or route groups.

Security Considerations

Store secrets securely - Use environment variables
Validate state parameter - Prevents CSRF attacks
Use HTTPS - Required for production OAuth
Verify tokens - Check expiration and validity
Limit scopes - Request only needed permissions

Best Practices

Store tokens securely (encrypted if stored)
Implement token refresh for long sessions
Handle callback errors gracefully
Log OAuth events for security monitoring

Testing

The OAuth2 middleware includes comprehensive test coverage for all functionality:

Test Case	Description	Expected Behavior
`TestNew` - valid token	Request with valid Bearer token	Returns 200 OK, token validated
`TestNew` - invalid token	Request with invalid Bearer token	Returns 401 Unauthorized
`TestNew` - missing token	Request without Authorization header	Returns 401 Unauthorized
`TestWithOptions_RequiredScopes`	Token with insufficient scopes	Returns 403 Forbidden
`TestWithOptions_ExpiredToken`	Token with past expiration time	Returns 401 Unauthorized
`TestGet`	Retrieve token from context	Token object accessible via Get()
`TestSubject`	Extract subject from token	Subject field returned correctly
`TestHasScope`	Check for specific scope	Returns true/false based on presence
`TestRequireScopes`	Scope enforcement middleware	Blocks request if scopes missing
`TestWWWAuthenticateHeader`	Invalid token response	WWW-Authenticate header present
`TestExtractToken_Query`	Token in query parameter	Token extracted from URL query
`TestExtractToken_Form`	Token in form body	Token extracted from form data
`TestExtractToken_InvalidLookup`	Malformed TokenLookup config	Returns 401, no token found
`TestExtractToken_UnknownSource`	Unknown token source type	Returns 401, no token found
`TestExtractToken_HeaderWithoutBearer`	Plain token without Bearer prefix	Token extracted and validated
`TestWithOptions_NoValidator`	No validator configured	Returns 401 with ErrNoValidator
`TestWithOptions_CustomErrorHandler`	Custom error handler set	Custom handler invoked on error
`TestIntrospectToken` - active	Introspection returns active token	Returns 200 OK
`TestIntrospectToken` - inactive	Introspection returns inactive token	Returns 401 Unauthorized
`TestIntrospectToken_ServerError`	Introspection endpoint error	Returns 401 Unauthorized
`TestIntrospectToken_InvalidJSON`	Malformed introspection response	Returns 401 Unauthorized
`TestIntrospectToken_ConnectionError`	Cannot connect to endpoint	Returns 401 Unauthorized
`TestGet_NoToken`	Get() without middleware	Returns nil
`TestSubject_NoToken`	Subject() without token	Returns empty string
`TestScopes`	Retrieve scopes list	Returns all token scopes
`TestScopes_NoToken`	Scopes() without token	Returns nil
`TestRequireScopes_NoToken`	RequireScopes without auth	Returns 401 Unauthorized
`TestRequireScopes_Sufficient`	Token has required scopes	Returns 200 OK, access granted
`TestHasScope_NoToken`	HasScope() without token	Returns false
`TestErrorTypes`	Error message strings	All error types return correct messages
`TestWithOptions_IntrospectionWithoutClientCreds`	Introspection without client auth	No Basic auth sent, request succeeds

oidc - OpenID Connect
jwt - JWT authentication
session - Session management

​Overview

​Installation

​Quick Start

​Configuration

​Config

​Examples

​Google OAuth

​GitHub OAuth

​Custom Provider

​State Parameter

​API Reference

​Functions

​Types

​Technical Details

​Architecture

​Token Validation Flow

​Token Introspection

​Error Handling

​Context Access

​Scope Middleware

​Security Considerations

​Best Practices

​Testing

​Related Middlewares