Organization Module​

The organization module provides multi-org support:

• Create organizations with metadata and settings
• Role-based membership -- assign roles (owner, admin, member, or custom) to users within an organization
• Invitations -- invite users to organizations via email with configurable expiration
• Multiple memberships -- users can belong to multiple organizations

import "github.com/bete7512/goauth/pkg/modules/organization"

a.Use(organization.New(nil))

The organization module adds its own API endpoints for creating orgs, managing members, sending invitations, and switching organization context.

Audit Logging​

The audit module tracks security-relevant events across your system:

• Login attempts (successful and failed)
• Password changes and resets
• 2FA enrollment and verification
• Admin actions on user accounts
• Session creation and revocation

Each audit entry includes timestamp, actor ID, action, IP address, user agent, and severity level.

Retention Policies​

Audit logs support configurable retention with automatic cleanup:

import "github.com/bete7512/goauth/pkg/modules/audit"

a.Use(audit.New(&audit.Config{
    RetentionDays: 90,
    CleanupInterval: 24 * time.Hour,
}))

The cleanup runs as a background goroutine that respects context cancellation for graceful shutdown.

Two-Factor Authentication​

GoAuth's 2FA implementation includes:

• TOTP (RFC 6238) with configurable issuer, digits, and period
• Encrypted secret storage -- TOTP secrets are encrypted with AES-256-GCM before being written to the database
• Backup codes -- configurable count (default 10) and length (default 8 characters)
• Code reuse prevention -- each TOTP code can only be used once within its validity window
• Sync intercept -- during login, 2FA verification is enforced via EmitSync so the login flow blocks until the code is verified

import "github.com/bete7512/goauth/pkg/modules/twofactor"

a.Use(twofactor.New(&config.TwoFactorConfig{
    Issuer:           "MyCompany",
    BackupCodesCount: 10,
    CodeLength:       8,
}))

OAuth with PKCE​

The OAuth module supports 4 providers -- Google, GitHub, Microsoft, and Discord -- with PKCE (Proof Key for Code Exchange) for secure authorization code flows:

import "github.com/bete7512/goauth/pkg/modules/oauth"

a.Use(oauth.New(&config.OAuthModuleConfig{
    Providers: []config.OAuthProvider{
        {
            Name:         "google",
            ClientID:     os.Getenv("GOOGLE_CLIENT_ID"),
            ClientSecret: os.Getenv("GOOGLE_CLIENT_SECRET"),
            RedirectURL:  "https://app.example.com/auth/oauth/google/callback",
        },
    },
}, nil))

Event Hooks​

GoAuth's event system supports enterprise integration patterns:

• Multiple handlers per event -- attach several handlers to the same event type
• Priority ordering -- handlers execute in priority order (higher priority runs first)
• Retry policies -- configure retries for failed event handlers
• Dead-letter queue -- events that exhaust retries are sent to a DLQ for inspection
• Custom async backend -- replace the default in-memory worker pool with your own types.AsyncBackend implementation (e.g., backed by a message queue)

a.On(types.EventAfterSignup, func(ctx context.Context, data interface{}) error {
    // sync new user to external systems
    return nil
})

Pluggable Storage​

GoAuth's storage layer is interface-based:

• Built-in: GORM backend supporting PostgreSQL, MySQL, and SQLite
• Cache decorator: In-memory cache for reducing database load
• Custom backends: Implement types.Storage (with Core(), Session(), Stateless() sub-interfaces) to use any data store

This means you can use GoAuth with existing enterprise databases or non-SQL backends without forking the library.

What GoAuth Does Not Provide​

To be clear about scope:

• No SAML or LDAP -- GoAuth handles OAuth 2.0 for social login. For SAML/LDAP, integrate at the identity provider level and use GoAuth for session management.
• No RBAC system -- The organization module has roles for org membership. For application-level permissions, implement your own authorization layer on top of GoAuth's user/org identities.
• No built-in Redis or RabbitMQ -- The AsyncBackend and storage interfaces are pluggable, but GoAuth does not ship with Redis or message queue implementations. The in-memory worker pool and GORM storage are the built-in defaults.
• No Prometheus metrics or Kubernetes operators -- GoAuth is a library, not a service. Instrument it with your existing observability stack.

Getting Started​

Add the modules you need:

a.Use(organization.New(nil))
a.Use(audit.New(&audit.Config{RetentionDays: 90}))
a.Use(twofactor.New())
a.Use(oauth.New(&config.OAuthModuleConfig{...}, nil))

See the Examples page for complete setup patterns and the individual module docs for configuration details.

Follow development on GitHub.

Authentication Strategy Performance​

The single biggest performance decision in GoAuth is choosing between session and stateless authentication:

Cookie-Cache Strategy​

The session module's cookie-cache strategy is the most interesting from a performance perspective. It works by:

1. On login, the session is stored in the database and a session cookie is set.
2. A short-lived cache cookie (configurable TTL, e.g., 5 minutes) is set alongside the session cookie.
3. On subsequent requests, if the cache cookie is still valid, the session is trusted without a database round-trip.
4. When the cache cookie expires, the next request checks the database and refreshes the cache.

This gives you near-stateless performance for the common case while keeping the ability to revoke sessions within the cache TTL window.

a.Use(session.New(&config.SessionModuleConfig{
    Strategy:       types.SessionStrategyCookieCache,
    CookieCacheTTL: 5 * time.Minute,
}, nil))

Password Hashing​

GoAuth uses bcrypt for password hashing. Bcrypt is deliberately slow -- that is the point. The cost factor controls how many rounds of hashing are performed:

• Default cost: 10 (standard bcrypt.DefaultCost)
• Each increment roughly doubles the time

This is the most CPU-intensive operation in the auth lifecycle. For most applications, the default cost is appropriate. If you are seeing login latency issues under load, the bottleneck is almost certainly bcrypt, which is by design -- it prevents brute-force attacks.

Refresh Token Hashing​

Refresh tokens are hashed with SHA-256 before storage. This is a fast, constant-time operation that adds negligible overhead but ensures that a database breach does not expose raw refresh tokens.

Async Event Processing​

GoAuth's event system uses a worker pool (default: 10 workers, 1000-item queue) for asynchronous event processing. Events like sending notification emails or writing audit logs are dispatched to the pool without blocking the HTTP response.

The worker pool is the default AsyncBackend. You can replace it with a custom implementation (e.g., backed by a message queue) by implementing the types.AsyncBackend interface.

For synchronous intercept points (like checking 2FA during login), GoAuth uses EmitSync, which blocks and returns errors to the caller.

Storage Optimization​

GoAuth's GORM-based storage includes several optimizations:

• Selective migrations: Each module only migrates the tables it needs.
• Indexed lookups: Core tables have indexes on email and username for fast authentication queries.
• Type-safe storage access: Storage.Core(), Storage.Session(), Storage.Stateless() -- no reflection or string-based lookups.
• In-memory cache decorator: An optional cache layer that can be wrapped around any storage implementation.

Running Benchmarks​

GoAuth includes benchmarks in the test suite. Run them yourself to see performance on your hardware:

make test-bench

This runs Go's standard testing.B benchmarks across the codebase. Results will vary based on your CPU, memory, and disk speed. Do not trust benchmark numbers from blog posts (including this one) -- always measure on your own infrastructure.

You can also run benchmarks for specific packages:

go test -bench=. -benchmem ./internal/security/...
go test -bench=. -benchmem ./storage/...

Practical Recommendations​

1. Use stateless auth by default. It eliminates database calls for token validation entirely.
2. If you need session revocation, use the cookie-cache strategy with a reasonable TTL (2-5 minutes) rather than checking the database on every request.
3. Keep access token TTL short (15 minutes default). Short-lived tokens reduce the window of exposure without requiring token blacklisting.
4. Offload heavy work to the event system. Email sending, audit logging, and webhook delivery all happen asynchronously by default.
5. Index your database. GoAuth's auto-migration creates indexes, but verify they exist if you manage migrations manually.

See the Performance docs for strategy comparison details, and the Session Module docs for cookie-cache configuration.

Signing and Algorithms​

GoAuth uses HS256 (HMAC-SHA256) for JWT signing. The secret key is configured via SecurityConfig.JwtSecretKey and must be at least 32 characters. The library validates algorithm headers on every token parse to prevent algorithm confusion attacks.

a, _ := auth.New(&config.Config{
    Storage: store,
    Migration: config.MigrationConfig{Auto: true},
    Security: types.SecurityConfig{
        JwtSecretKey:  os.Getenv("JWT_SECRET"),       // min 32 chars
        EncryptionKey: os.Getenv("ENCRYPTION_KEY"),   // for AES-256-GCM
    },
})

Access and Refresh Token Pair​

GoAuth issues two tokens on login:

• Access token -- Short-lived (default 15 minutes). Carries user claims. Used for API authorization.
• Refresh token -- Longer-lived (default 7 days). Used only to obtain a new access token.

The TTLs are configurable:

Security: types.SecurityConfig{
    JwtSecretKey: os.Getenv("JWT_SECRET"),
    Session: types.SessionConfig{
        AccessTokenTTL:  15 * time.Minute,
        RefreshTokenTTL: 7 * 24 * time.Hour,
    },
},

Refresh Token Rotation​

How refresh tokens are secured depends on the authentication strategy:

Stateless module: Each refresh token includes a JTI (JWT ID) nonce. The JTI is stored in the database. When a refresh token is used, the old JTI is invalidated and a new token with a fresh JTI is issued. This provides one-time-use semantics -- replaying an old refresh token fails.

Session module: Refresh tokens are hashed with SHA-256 before storage. The raw token is only returned to the client; the database never holds the plaintext. On refresh, the incoming token is hashed and compared against the stored hash.

Account Lockout​

GoAuth includes brute-force protection via account lockout:

• Max attempts: 5 failed login attempts (configurable)
• Lockout window: 15 minutes (configurable)
• Lockout behavior: Returns a 429 status with time remaining until unlock

This is configured via Config.Validate() defaults or explicitly:

Lockout: types.LockoutConfig{
    MaxAttempts:     5,
    LockoutDuration: 15 * time.Minute,
},

Password Policy​

GoAuth enforces password requirements at the config level:

• Minimum length: 8 characters (default)
• Maximum length: 128 characters (default)
• Configurable via PasswordPolicy in the config

Passwords are hashed with bcrypt. The cost factor is configurable through SecurityConfig.

Encryption of Sensitive Data​

Beyond passwords and JWTs, GoAuth encrypts sensitive fields using AES-256-GCM:

• TOTP secrets stored in the database
• OAuth provider tokens

The encryption key is set via SecurityConfig.EncryptionKey (32 characters for AES-256).

Token Storage on the Client​

GoAuth sets tokens in HTTP-only, secure cookies with SameSite attributes when using the session module. For stateless JWT, tokens are returned in JSON response bodies for the client to store as appropriate.

What GoAuth Does Not Do​

To set expectations clearly:

• No RS256/ES256 -- GoAuth uses HS256 only. If you need asymmetric signing, you would need to implement a custom security manager satisfying the types.SecurityManager interface.
• No built-in rate limiting middleware -- Account lockout handles brute-force at the application level. For network-level rate limiting, use your reverse proxy or a dedicated middleware.
• No token blacklisting for access tokens -- Access tokens are short-lived by design. The stateless module blacklists refresh token JTIs on revocation.

Security Checklist​

Before deploying:

• Set JwtSecretKey to a strong, random 32+ character value from environment variables
• Set EncryptionKey to a separate strong, random 32-character value
• Configure appropriate AccessTokenTTL (shorter is safer; 15 minutes is a good default)
• Enable HTTPS in production (GoAuth sets Secure flag on cookies)
• Enable account lockout (on by default)
• Enable email verification if your app requires confirmed email addresses
• Use the CSRF module for browser-based applications
• Review audit logs regularly if using the audit module

For more details, see the Stateless Module and Session Module documentation.

What GoAuth Provides​

GoAuth ships with 12 modules that you compose via a three-phase lifecycle:

a, _ := auth.New(&config.Config{...})   // 1. Create
a.Use(twofactor.New())                   // 2. Register modules
a.Initialize(context.Background())       // 3. Initialize

Core (auto-registered) handles user registration, login, password reset, email/phone verification, and profile management. You then pick an authentication strategy:

• Session -- Server-side sessions with a cookie-cache strategy that avoids a DB round-trip on every request.
• Stateless (default) -- JWT access/refresh token pair with configurable TTLs and refresh token rotation.

Session and stateless are mutually exclusive. If you register neither, stateless is used by default.

Optional modules cover the rest:

• OAuth -- Social login with Google, GitHub, Microsoft, and Discord (PKCE supported)
• Two-Factor -- TOTP-based 2FA with encrypted secrets and backup codes
• Notification -- Email/SMS delivery via pluggable senders (SendGrid, SMTP, Twilio, or custom)
• Admin -- User CRUD endpoints with admin auth middleware
• Organization -- Multi-org support with roles and invitations
• Audit -- Security event logging with configurable retention and cleanup
• Captcha -- reCAPTCHA v3 and Cloudflare Turnstile
• CSRF -- Token-based CSRF protection
• Magic Link -- Passwordless authentication via email

Security Defaults​

GoAuth ships with sensible defaults out of the box:

• bcrypt password hashing with configurable cost factor
• HS256 JWT signing with a required 32+ character secret
• AES-256-GCM encryption for sensitive data (TOTP secrets, OAuth tokens)
• SHA-256 refresh token hashing in the database
• Account lockout after 5 failed attempts (15-minute window)
• Password policy enforcement (min 8, max 128 characters)
• TOTP code reuse prevention within the validity window

Framework Adapters​

GoAuth includes adapters for 4 Go web frameworks:

stdhttp.Register(mux, a)         // net/http
ginadapter.Register(router, a)   // Gin
chiadapter.Register(router, a)   // Chi
fiberadapter.Register(app, a)    // Fiber

Event System​

Every auth action emits typed events that you can hook into:

a.On(types.EventAfterSignup, func(ctx context.Context, data interface{}) error {
    user := types.EventDataAs[*types.SignupEventData](data)
    // sync to CRM, send analytics, etc.
    return nil
})

The event bus supports multiple handlers per event, priority ordering, retry policies, and a dead-letter queue for failed handlers. The default backend is an in-memory worker pool (10 workers, 1000 queue); you can provide a custom types.AsyncBackend for external brokers.

Storage​

GoAuth uses GORM under the hood with support for PostgreSQL, MySQL, and SQLite. Storage is type-safe -- Storage.Core(), Storage.Session(), Storage.Stateless() -- with no string-based lookups. An in-memory cache decorator is included, and the storage interface is pluggable for custom backends.

Getting Started​

go get github.com/bete7512/goauth

Check the Quick Start guide to build a working auth system in a few minutes, or browse the Examples for specific use cases.

Follow along on GitHub for updates and to contribute.