extension-middleware-config

Extension Middleware Configuration Example

This example demonstrates how to customize the authentication middleware configuration when using AuthSome as a Forge extension.

Overview

The AuthSome extension for Forge allows you to configure the authentication middleware behavior at extension creation time, giving you full control over authentication requirements, session management, and context resolution.

Usage Patterns

1. Default Configuration (Backwards Compatible)

app := forge.New()

ext := extension.NewExtension(
    extension.WithBasePath("/auth"),
    extension.WithSecret("my-secret-key"),
)

app.RegisterExtension(ext)

Uses sensible defaults:

• SessionCookieName: "authsome_session"
• Optional: true (allows unauthenticated requests)
• AllowAPIKeyInQuery: false (secure)
• AllowSessionInQuery: false (secure)

2. Custom Middleware Configuration

ext := extension.NewExtension(
    extension.WithBasePath("/api/auth"),
    extension.WithSecret("my-secret-key"),
    extension.WithAuthMiddlewareConfig(middleware.AuthMiddlewareConfig{
        SessionCookieName:   "my_custom_session",
        Optional:            false, // Require authentication
        AllowAPIKeyInQuery:  false,
        AllowSessionInQuery: false,
        APIKeyHeaders:       []string{"Authorization", "X-API-Key", "X-Custom-Key"},
        Context: middleware.ContextConfig{
            AutoDetectFromAPIKey: true,
            AutoDetectFromConfig: false,
            AppIDHeader:          "X-App-ID",
            EnvironmentIDHeader:  "X-Environment-ID",
        },
    }),
)

3. Partial Configuration

Override only what you need:

ext := extension.NewExtension(
    extension.WithBasePath("/auth"),
    extension.WithSecret("my-secret-key"),
    extension.WithAuthMiddlewareConfig(middleware.AuthMiddlewareConfig{
        Optional: false, // Require auth, rest uses defaults
        Context: middleware.ContextConfig{
            AutoDetectFromAPIKey: true,
            AutoDetectFromConfig: true,
        },
    }),
)

4. Security-First Configuration

Production-ready secure configuration:

ext := extension.NewExtension(
    extension.WithBasePath("/auth"),
    extension.WithSecret("production-secret-key"),
    extension.WithAuthMiddlewareConfig(middleware.AuthMiddlewareConfig{
        SessionCookieName:   "secure_session",
        Optional:            false, // Block unauthenticated requests
        AllowAPIKeyInQuery:  false, // Never in production
        AllowSessionInQuery: false, // Never in production
        Context: middleware.ContextConfig{
            AutoDetectFromAPIKey: true,
        },
    }),
)

Configuration Options

AuthMiddlewareConfig

ContextConfig

YAML Configuration

You can also configure via YAML:

authsome:
  basePath: "/api/auth"
  secret: "my-secret-key"
  authMiddleware:
    sessionCookieName: "my_session"
    optional: false
    allowAPIKeyInQuery: false
    allowSessionInQuery: false
    context:
      defaultAppID: "c7ndh411g9k8pdunveeg"
      defaultEnvironmentID: "c7ndh412g9k8pdunveeh"
      autoDetectFromAPIKey: true
      autoDetectFromConfig: true
      appIDHeader: "X-App-ID"
      environmentIDHeader: "X-Environment-ID"

Then load it:

ext := extension.NewExtension()
// Config is automatically loaded from Forge's config system
app.RegisterExtension(ext)

Complete Example

package main

import (
    "context"
    "log"

    "github.com/xraph/authsome/core/middleware"
    "github.com/xraph/authsome/extension"
    "github.com/xraph/forge"
)

func main() {
    app := forge.New()

    // Create extension with custom middleware config
    authExt := extension.NewExtension(
        extension.WithBasePath("/api/auth"),
        extension.WithSecret("my-secret-key"),
        extension.WithAuthMiddlewareConfig(middleware.AuthMiddlewareConfig{
            SessionCookieName: "app_session",
            Optional:          true,
            Context: middleware.ContextConfig{
                AutoDetectFromAPIKey: true,
                AppIDHeader:          "X-App-ID",
                EnvironmentIDHeader:  "X-Environment-ID",
            },
        }),
    )

    // Register extension
    if err := app.RegisterExtension(authExt); err != nil {
        log.Fatal(err)
    }

    // Start app
    ctx := context.Background()
    if err := app.Start(ctx); err != nil {
        log.Fatal(err)
    }

    // Add your routes
    app.Router().GET("/", func(c forge.Context) error {
        return c.JSON(200, map[string]string{
            "message": "Hello!",
        })
    })

    // Run server
    if err := app.Run(":8080"); err != nil {
        log.Fatal(err)
    }
}

Security Considerations

Production Best Practices

✅ DO:

• Keep AllowAPIKeyInQuery as false
• Keep AllowSessionInQuery as false
• Use HTTPS in production
• Use strong secrets (environment variables)
• Set Optional: false for endpoints requiring auth

❌ DON'T:

• Enable query param authentication in production
• Hard-code secrets in source code
• Use weak or default secrets

Query Param Authentication Risk

Enabling query param authentication is dangerous because:

• Tokens appear in server logs
• Tokens appear in browser history
• Tokens leak via Referer headers
• Tokens visible in monitoring tools

Only use for local development/testing.

Integration with Forge Extensions

The middleware config works seamlessly with other Forge extensions:

app := forge.New()

// Register database extension
dbExt := database.NewExtension(/* config */)
app.RegisterExtension(dbExt)

// Register AuthSome with middleware config
authExt := extension.NewExtension(
    extension.WithBasePath("/auth"),
    extension.WithAuthMiddlewareConfig(middleware.AuthMiddlewareConfig{
        Optional: false,
    }),
)
app.RegisterExtension(authExt)

// Register other extensions...

Testing

Run the example:

cd examples/extension-middleware-config
go run main.go

Accessing the Auth Instance

After registration, access the AuthSome instance:

auth := ext.Auth()
serviceRegistry := ext.GetServiceRegistry()
pluginRegistry := ext.GetPluginRegistry()
basePath := ext.GetBasePath()
db := ext.GetDB()

Further Reading

• Extension Documentation
• Middleware Configuration
• Authentication Context
• Security Best Practices