Lokstra Auth

Modular Authentication and Authorization framework for Lokstra.

📖 Overview

Lokstra Auth is a modular authentication and authorization framework built on top of Lokstra Framework. Designed with a 4-layer architecture that enables high flexibility and composability.

🏗️ Architecture: 4 Layers

Lokstra Auth divides the authentication and authorization process into 4 independent layers:

1. Credential Layer (credential/) ✅ COMPLETE

The first layer is responsible for receiving and validating credentials from various sources:

• ✅ Basic Auth - Username/password with bcrypt
• ✅ OAuth2 - Google, GitHub, Facebook integration
• ✅ Passwordless - Magic Link and OTP via email
• ✅ API Key - Key-based authentication with SHA3-256 hashing
• ✅ Passkey - WebAuthn/FIDO2 support

Status: Production ready with 5 authenticator types Documentation: credential/README.md

2. Token Layer (token/) ✅ COMPLETE

The second layer manages token lifecycle and data extraction:

• ✅ JWT Manager - Access + Refresh token with rotation
• ✅ Simple Token - Opaque token management
• ✅ Token Store - In-memory token storage for testing
• ✅ Claim extraction and validation
• ✅ Custom token formats

Status: Production ready with 2 token manager types Documentation: token/README.md

3. Subject Layer (rbac/) ✅ COMPLETE

The third layer transforms claims into complete identity context:

• ✅ Simple Resolver - Direct claim to identity mapping
• ✅ Enriched Resolver - Identity enrichment with external data
• ✅ Cached Resolver - Performance optimization with caching
• ✅ Identity Store - In-memory user data storage
• ✅ Role and permission loading
• ✅ Multi-source data aggregation

Status: Production ready with 3 resolver types Documentation: rbac/README.md

4. Authorization Layer (authz/) ✅ COMPLETE

The fourth layer performs access evaluation and policy enforcement:

• ✅ RBAC - Role-Based Access Control with wildcard support
• ✅ ABAC - Attribute-Based Access Control with rules
• ✅ ACL - Resource-level Access Control Lists
• ✅ Policy-Based - Flexible policy evaluation with combining algorithms
• ✅ Resource-level permissions
• ✅ Thread-safe implementations

Status: Production ready with 4 authorization models Documentation: authz/README.md

🚀 Quick Start

Installation

go get github.com/primadi/lokstra-auth

Simple Example: Complete Authentication Flow

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/primadi/lokstra-auth/credential/basic"
    "github.com/primadi/lokstra-auth/token/jwt"
    "github.com/primadi/lokstra-auth/identity/simple"
    authz "github.com/primadi/lokstra-auth/authz"
    "github.com/primadi/lokstra-auth/authz/rbac"
)

func main() {
    ctx := context.Background()

    // Layer 1: Setup authentication
    userProvider := basic.NewInMemoryUserProvider()
    passwordHash, _ := basic.HashPassword("MySecure@Pass123")
    userProvider.AddUser(&basic.User{
        ID:           "user-001",
        Username:     "john.doe",
        PasswordHash: passwordHash,
    })
    
    validator := basic.NewValidator(basic.DefaultValidatorConfig())
    authenticator := basic.NewAuthenticator(userProvider, validator)

    // Layer 2: Setup token management
    jwtConfig := jwt.DefaultConfig("your-secret-key")
    tokenManager := jwt.NewManager(jwtConfig)

    // Layer 3: Setup subject resolution
    resolver := simple.NewResolver()
    roleProvider := simple.NewStaticRoleProvider(map[string][]string{
        "user-001": {"admin", "user"},
    })
    contextBuilder := simple.NewContextBuilder(
        roleProvider,
        simple.NewStaticPermissionProvider(map[string][]string{}),
        simple.NewStaticGroupProvider(map[string][]string{}),
        simple.NewStaticProfileProvider(map[string]map[string]any{}),
    )

    // Layer 4: Setup authorization
    rbacEvaluator := rbac.NewEvaluator(map[string][]string{
        "admin": {"*"}, // Admin has all permissions
        "user":  {"read:posts", "create:posts"},
    })

    // Use it!
    // 1. Authenticate
    authResult, _ := authenticator.Authenticate(ctx, &basic.BasicCredentials{
        Username: "john.doe",
        Password: "MySecure@Pass123",
    })
    fmt.Println("✅ Authenticated:", authResult.Subject)

    // 2. Generate token
    token, _ := tokenManager.Generate(ctx, authResult.Claims)
    fmt.Println("✅ Token generated")

    // 3. Verify token
    verifyResult, _ := tokenManager.Verify(ctx, token.Value)
    fmt.Println("✅ Token verified")

    // 4. Build identity
    subject, _ := resolver.Resolve(ctx, verifyResult.Claims)
    identity, _ := contextBuilder.Build(ctx, subject)
    fmt.Println("✅ Identity built, Roles:", identity.Roles)

    // 5. Check authorization
    decision, _ := rbacEvaluator.Evaluate(ctx, &authz.AuthorizationRequest{
        Subject:  identity,
        Resource: &authz.Resource{Type: "posts", ID: "123"},
        Action:   authz.ActionRead,
    })
    fmt.Println("✅ Authorization:", decision.Allowed)
}

More Examples

See examples/ directory for complete working examples:

• Basic Flow: examples/complete/01_basic_flow/
• Multi-Credential: examples/complete/02_multi_auth/

📝 Detailed Examples

Basic Authentication Example

import (
    "github.com/primadi/lokstra-auth/credential/basic"
)

// Create authenticator
userStore := basic.NewInMemoryUserStore()
auth := basic.NewAuthenticator(&basic.Config{
    UserStore: userStore,
})

// Register user
hashedPassword, _ := basic.HashPassword("mypassword")
userStore.AddUser(&basic.User{
    ID:       "user123",
    Username: "john",
    Password: hashedPassword,
})

// Authenticate
creds := &basic.Credentials{
    Username: "john",
    Password: "mypassword",
}

result, err := auth.Authenticate(ctx, creds)
if result.Success {
    fmt.Println("Logged in as:", result.Subject)
}

OAuth2 Authentication Example

import (
    "github.com/primadi/lokstra-auth/credential/oauth2"
)

// Create OAuth2 authenticator
auth := oauth2.NewAuthenticator(nil) // Uses default providers

// Authenticate with Google access token
creds := &oauth2.Credentials{
    Provider:    oauth2.ProviderGoogle,
    AccessToken: "ya29.a0AfH6SMBxxxxx...",
}

result, err := auth.Authenticate(ctx, creds)
if result.Success {
    email := result.Claims["email"].(string)
    name := result.Claims["name"].(string)
    // ...
}

Passwordless Authentication Example

import (
    "github.com/primadi/lokstra-auth/credential/passwordless"
)

// Create passwordless authenticator
auth := passwordless.NewAuthenticator(&passwordless.Config{
    TokenStore:   passwordless.NewInMemoryTokenStore(),
    UserResolver: myUserResolver,
    TokenSender:  myEmailSender,
})

// Request magic link
err := auth.InitiateMagicLink(ctx, "[email protected]", "user123", "https://myapp.com")
// Email sent with magic link

// Verify magic link token
creds := &passwordless.Credentials{
    Email:     "[email protected]",
    Token:     "token-from-email",
    TokenType: passwordless.TokenTypeMagicLink,
}

result, err := auth.Authenticate(ctx, creds)

API Key Authentication Example

import (
    "github.com/primadi/lokstra-auth/credential/apikey"
)

// Create API key authenticator
keyStore := apikey.NewInMemoryKeyStore()
auth := apikey.NewAuthenticator(&apikey.Config{
    KeyStore: keyStore,
})

// Generate API key
expiresIn := 30 * 24 * time.Hour
keyString, apiKey, err := auth.GenerateKey(
    ctx,
    "user123",                    // User ID
    "Production API Key",         // Key name
    []string{"read", "write"},    // Scopes
    &expiresIn,
)

// Authenticate with API key
creds := &apikey.Credentials{
    APIKey: keyString,
}

result, err := auth.Authenticate(ctx, creds)
if result.Success {
    scopes := result.Claims["scopes"]
    // ...
}

📦 Project Structure

lokstra-auth/
├── credential/      # ✅ Layer 1: Credential Input (COMPLETE)
│   ├── contract.go     # Core interfaces
│   ├── basic/          # Username/password
│   ├── oauth2/         # OAuth2 (Google, GitHub, Facebook)
│   ├── passwordless/   # Magic Link & OTP
│   ├── apikey/         # API key authentication
│   └── README.md       # ✅ Complete documentation
├── token/           # ✅ Layer 2: Token Verification (COMPLETE)
│   ├── contract.go     # Core interfaces
│   ├── jwt/            # JWT with access+refresh tokens
│   ├── simple/         # Simple token manager
│   └── README.md       # ✅ Complete documentation
├── rbac/         # ✅ Layer 3: Subject Resolution (COMPLETE)
│   ├── contract.go     # Interface definitions
│   ├── simple/         # Simple resolver
│   ├── enriched/       # Enriched resolver with external data
│   ├── cached/         # Cached resolver for performance
│   └── README.md       # ✅ Complete documentation
├── authz/           # ✅ Layer 4: Authorization (COMPLETE)
│   ├── contract.go     # Interface definitions
│   ├── rbac/           # Role-based access control
│   ├── abac/           # Attribute-based access control
│   ├── acl/            # Access control lists
│   ├── policy/         # Policy-based authorization
│   └── README.md       # ✅ Complete documentation
├── middleware/         # ✅ Lokstra Framework Integration
│   ├── auth.go         # Token verification middleware
│   ├── permission.go   # Permission check middleware
│   └── role.go         # Role check middleware
├── examples/           # ✅ Working Examples
│   ├── credential/  # Credential layer examples
│   │   ├── 01_basic/       # Basic auth flow
│   │   ├── 02_multi_auth/  # Multi-authenticator
│   │   ├── 03_oauth2/      # ✅ OAuth2 example
│   │   ├── 04_passwordless/# ✅ Passwordless example
│   │   └── 05_apikey/      # ✅ API Key example
│   ├── token/       # ✅ Token layer examples
│   ├── rbac/     # ✅ Subject layer examples
│   ├── authz/       # ✅ Authorization layer examples
│   │   ├── 01_rbac/        # RBAC examples
│   │   ├── 02_abac/        # ABAC examples
│   │   └── 03_acl/         # ACL examples
│   └── complete/       # Complete 4-layer integration
│       ├── 01_basic_flow/  # Basic authentication flow
│       └── 02_multi_auth/  # Multi-credential demo
└── README.md           # This file

📚 Documentation

Layer Documentation

• ✅ Layer 1: Credential - Complete - Basic, OAuth2, Passwordless, API Key
• ✅ Layer 2: Token - Complete - JWT (Access+Refresh), Simple, Store
• ✅ Layer 3: Subject - Complete - Simple, Enriched, Cached resolvers
• ✅ Layer 4: Authorization - Complete - RBAC, ABAC, ACL, Policy-based

Examples

• ✅ Basic Authentication - Username/password flow
• ✅ Multi-Authenticator - Multiple auth methods
• ✅ OAuth2 Auth - Provider integration guide
• ✅ Passwordless Auth - Magic Link & OTP
• ✅ API Key Auth - Full API key lifecycle
• ✅ JWT Token Management - Access & refresh tokens
• ✅ Subject Resolution - Identity enrichment & caching
• ✅ Authorization Examples - RBAC, ABAC, ACL examples
• ✅ Complete Flow - All 4 layers integrated
• ✅ Multi-Credential Demo - Multiple auth methods with RBAC

✨ Features

Credential Layer (credential/)

• ✅ 5 Authenticator Types: Basic, OAuth2, Passwordless, API Key, Passkey
• ✅ Provider Support: Google, GitHub, Facebook OAuth2
• ✅ Passwordless Methods: Magic Link (15min TTL), OTP (5min TTL)
• ✅ API Key Features: SHA3-256 hashing, scopes, expiry, revocation
• ✅ Passkey Support: WebAuthn/FIDO2 authentication
• ✅ Multi-Authenticator: Handle multiple auth methods simultaneously
• ✅ Extensible: Custom authenticators via interface
• ✅ In-Memory Stores: Testing-ready implementations

Token Layer (token/)

• ✅ JWT generation with access + refresh tokens
• ✅ Automatic token rotation
• ✅ Token verification and validation
• ✅ Simple opaque token management
• ✅ Token store for testing
• ✅ Configurable token expiry
• ✅ Custom claims support

Subject Layer (rbac/)

• ✅ Simple subject resolver (direct mapping)
• ✅ Enriched resolver (external data integration)
• ✅ Cached resolver (performance optimization)
• ✅ Identity store for user data
• ✅ User/subject resolution from tokens
• ✅ Identity context building
• ✅ Claims enrichment with roles, permissions, profile
• ✅ Multi-source data aggregation

Authorization Layer (authz/)

• ✅ Role-Based Access Control (RBAC) with wildcards
• ✅ Attribute-Based Access Control (ABAC) with conditional rules
• ✅ Access Control Lists (ACL) for fine-grained permissions
• ✅ Policy-based authorization with multiple combining algorithms
• ✅ Permission and role checking helpers
• ✅ Resource-level access control
• ✅ Thread-safe implementations
• ✅ Flexible policy evaluation

Integration

• ✅ Modular design - use any layer independently
• ✅ Composable - combine layers as needed
• ✅ Production-ready implementations
• ✅ Comprehensive examples
• ✅ Complete documentation

🔐 Security Features

1. Password Security

   • Bcrypt hashing (cost factor 10)
   • Constant-time comparison

2. Token Security

   • JWT with HS256/RS256
   • Configurable expiration
   • Refresh token rotation

3. API Key Security

   • SHA3-256 hashing
   • One-time display
   • Constant-time comparison
   • Automatic expiry checking

4. Passwordless Security

   • One-time use tokens
   • Time-based expiration
   • Cryptographically secure random generation
   • Automatic cleanup

5. OAuth2 Security

   • Token validation with provider
   • Email verification checking
   • HTTPS-only in production

6. Passkey Security

   • WebAuthn/FIDO2 standard compliance
   • Public key cryptography
   • Phishing-resistant authentication

🧪 Testing

Each layer comes with in-memory implementations for testing:

// Basic Auth testing
userStore := basic.NewInMemoryUserStore()
userStore.AddUser(&basic.User{...})

// Passwordless testing
tokenStore := passwordless.NewInMemoryTokenStore()

// API Key testing
keyStore := apikey.NewInMemoryKeyStore()

// Run examples
go run examples/credential/05_apikey/main.go
go run examples/credential/04_passwordless/main.go
go run examples/complete/02_multi_auth/main.go

🎯 Design Principles

1. Modularity - Each layer can be used independently
2. Composability - Layers can be combined as needed
3. Extensibility - Easy to add new providers or strategies
4. Type Safety - Leveraging Go interfaces for type-safe operations
5. Lokstra Integration - Built on top of Lokstra Framework
6. Production Ready - Following security best practices
7. Developer Friendly - Clear APIs and comprehensive documentation

📋 Requirements

• Go 1.21 or higher
• Lokstra Framework v0.3.4+

🗺️ Roadmap

Layer 1: Credential ✅

• Basic authenticator
• OAuth2 authenticator (Google, GitHub, Facebook)
• Passwordless authenticator (Magic Link, OTP)
• API Key authenticator
• Passkey/WebAuthn authenticator
• Multi-authenticator support
• Complete documentation
• Working examples

Layer 2: Token ✅

• JWT token manager
• Access + Refresh token support
• Simple token manager
• Token store implementation
• Complete documentation
• Working examples

Layer 3: Subject ✅

• Simple subject resolver
• Enriched resolver with external data
• Cached resolver for performance
• Identity store implementation
• Identity context builder
• Complete documentation
• Working examples

Layer 4: Authorization ✅

• RBAC authorizer with wildcards
• ABAC authorizer with rules
• ACL manager for resource permissions
• Policy-based authorization
• Policy store implementation
• Multiple combining algorithms
• Complete documentation
• Working examples

Integration ✅

• Complete 4-layer examples
• Multi-credential demo
• Comprehensive documentation
• Auth runtime orchestrator
• Builder API
• Lokstra middleware
• Testing utilities
• Benchmark suite

📄 License

See LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Built with ❤️ using Lokstra Framework