t1k:nakama:auth

Field	Value
Module	`base`
Version	`1.6.2`
Effort	`low`
Tools	—

Keywords: auth, authentication, firebase, hooks, nakama, provider

How to invoke

/t1k:nakama:auth

Nakama Auth Development

Overview

Authentication uses an adapter pattern with a Provider interface. The factory reads env vars to select the active provider. Before-hooks intercept authentication requests to validate external tokens, and after-hooks handle new user creation.

Key Patterns

Provider Interface (pkg/auth/)

type Provider interface {
    VerifyToken(ctx context.Context, token string) (VerifiedClaims, error)
}

type VerifiedClaims struct {
    UserID string
    Email  string
    // ... other claims
}

Factory Pattern (internal/auth/)

func NewProvider(env map[string]string, logger runtime.Logger) (auth.Provider, error) {
    if env["FIREBASE_AUTH_ENABLED"] == "true" {
        return firebase.New(ctx, env, logger)
    }
    // ... other providers
}

Before Hook (block unwanted auth methods)

initializer.RegisterBeforeAuthenticateCustom(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateCustomRequest) (*api.AuthenticateCustomRequest, error) {
    // Validate token via Provider
    claims, err := provider.VerifyToken(ctx, in.Account.Id)
    if err != nil {
        return nil, runtime.NewError("invalid token", 16) // UNAUTHENTICATED
    }
    // Modify request with verified claims
    return in, nil
})

After Hook (new user setup)

initializer.RegisterAfterAuthenticateCustom(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, out *api.Session, in *api.AuthenticateCustomRequest) error {
    if out.Created {
        // Initialize new user data
    }
    return nil
})

Gotchas

Only AuthenticateCustom should be allowed — block other auth methods in before-hooks
Firebase provider caches JWKS keys — respect TTL from FIREBASE_JWKS_CACHE_TTL
Before-hooks that return (nil, nil) BLOCK the request silently
Before-hooks that return (in, nil) ALLOW the request to proceed
Provider errors should map to code 16 (UNAUTHENTICATED)
Token expiration: Always validate token expiration server-side. Never trust client-provided timestamps.
Firebase Admin SDK init: Initialize once at plugin load (InitModule), not per-request. Repeated init causes memory leaks.
Auth bypass via custom ID: Custom authenticators must validate ALL fields. Missing validation = auth bypass vulnerability.
Rate limiting: Nakama doesn’t rate-limit auth by default. Implement per-IP rate limiting to prevent brute force.

Checklist

Provider implements auth.Provider interface
Factory handles provider selection via env vars
Before-hook validates tokens and maps errors correctly
After-hook initializes new user data on out.Created
Unwanted auth methods blocked (return nil, error)
Token verification errors return UNAUTHENTICATED (code 16)