oneauth

OneAuth

A Go authentication library providing unified local and OAuth-based authentication with support for multiple authentication methods per user account.

The library is organized into focused subpackages (core/, keys/, admin/, apiauth/, localauth/, httpauth/). The core module is lightweight (~6 dependencies: jwt, scs, x/crypto, x/oauth2). Heavy backends (GORM, GAE/Datastore, SAML, gRPC) live in separate sub-modules so consumers only pull what they need.

Features

• Unified authentication — Password and OAuth through a single interface
• Multi-provider support — One account accessible via password, Google, GitHub, etc.
• API authentication — JWT access tokens, refresh tokens, API keys
• Multi-tenant JWT — KeyStore interface for per-client signing keys with algorithm confusion prevention
• Federated auth — App registration, resource-scoped token minting, custom claims
• Flexible storage — File-based, GORM (SQL), and GAE/Datastore implementations
• Client SDK — Token management, auto-refresh, credential persistence for CLI tools
• gRPC support — Auth context utilities and interceptors

Quick Start

go get github.com/panyam/oneauth

import (
    "github.com/panyam/oneauth/core"
    "github.com/panyam/oneauth/localauth"
    "github.com/panyam/oneauth/stores/fs"
)

// Initialize stores
storagePath := "/path/to/storage"
userStore := fs.NewFSUserStore(storagePath)
identityStore := fs.NewFSIdentityStore(storagePath)
channelStore := fs.NewFSChannelStore(storagePath)
tokenStore := fs.NewFSTokenStore(storagePath)

// Create authentication callbacks
createUser := localauth.NewCreateUserFunc(userStore, identityStore, channelStore)
validateCreds := localauth.NewCredentialsValidator(identityStore, channelStore, userStore)

// Configure local authentication
localAuth := &localauth.LocalAuth{
    CreateUser:          createUser,
    ValidateCredentials: validateCreds,
    EmailSender:         &core.ConsoleEmailSender{},
    TokenStore:          tokenStore,
    BaseURL:             "https://yourapp.com",
    HandleUser:          yourSessionHandler,
}

// Set up HTTP routes
mux := http.NewServeMux()
mux.Handle("/auth/login", localAuth)
mux.Handle("/auth/signup", http.HandlerFunc(localAuth.HandleSignup))

See Getting Started for the full setup guide.

Architecture

OneAuth separates authentication into three layers:

User: john@example.com
├── Identity: john@example.com (verified)
├── Channel: local    (password hash)
├── Channel: google   (OAuth tokens)
└── Channel: github   (OAuth tokens)

• User — A unique account with profile information
• Identity — An email or phone number with verification status (shared across channels)
• Channel — An authentication mechanism storing provider-specific credentials

Verifying an email through any channel (e.g., Google OAuth) verifies it for all channels.

See Architecture for design decisions, data model diagrams, and token lifecycle.

API Authentication

Protect API endpoints with JWT middleware:

import "github.com/panyam/oneauth/apiauth"

middleware := &apiauth.APIMiddleware{
    KeyStore:        keyStore,        // multi-tenant (per-client keys)
    TokenQueryParam: "token",         // ?token= fallback for WebSocket clients
}

mux.Handle("/api/data", middleware.ValidateToken(handler))
mux.Handle("/api/write", middleware.RequireScopes("write")(handler))
mux.Handle("/api/public", middleware.Optional(handler))

// Access claims in handlers
userID := apiauth.GetUserIDFromAPIContext(r.Context())
custom := apiauth.GetCustomClaimsFromContext(r.Context())

See API Authentication for JWT lifecycle, custom claims, multi-tenant validation, and middleware configuration.

Federated Auth (App Registration)

For systems where multiple applications register and mint scoped JWTs:

import (
    "github.com/panyam/oneauth/admin"
    "github.com/panyam/oneauth/apiauth"
    gormstore "github.com/panyam/oneauth/stores/gorm"
)

// Resource server validates tokens from any registered app
keyStore := gormstore.NewGORMKeyStore(db)
middleware := &apiauth.APIMiddleware{KeyStore: keyStore}

// Apps register via admin API and mint tokens for their users
token, err := admin.MintResourceToken(clientID, clientSecret, userID, scopes, customClaims)

See Architecture — Federated Auth for the full flow.

Store Implementations

All stores implement the same interfaces defined in core/ (UserStore, IdentityStore, ChannelStore, TokenStore, RefreshTokenStore, APIKeyStore) and keys/ (KeyStorage).

See Stores for interface definitions and usage examples.

Client SDK

For CLI tools and programmatic clients:

import (
    "github.com/panyam/oneauth/client"
    "github.com/panyam/oneauth/client/stores/fs"
)

store, _ := fs.NewFSCredentialStore("", "myapp")
authClient := client.NewAuthClient("https://api.example.com", store)
authClient.Login("user@example.com", "password", "read write")

// Auto-refresh on 401 or before expiry
resp, _ := authClient.HTTPClient().Get("https://api.example.com/resource")

Documentation

Guides

Reference

Requirements

• Go 1.21+
• golang.org/x/crypto/bcrypt — password hashing
• github.com/golang-jwt/jwt/v5 — JWT tokens
• golang.org/x/oauth2 — OAuth providers (optional)
• gorm.io/gorm — GORM stores (optional)
• cloud.google.com/go/datastore — GAE stores (optional)

License

See LICENSE file for terms and conditions.