Ògiri Security

Ògiri is a Spring Boot security library for token-based authentication with pluggable sub-token support. It handles token issuance, validation, rotation, and cleanup without locking you into a specific database or persistence layer.

Why Ògiri?

Database Freedom — Use JPA, MongoDB, Redis, or any custom persistence
Zero Configuration — Works out of the box with sensible defaults
Flexible Tokens — Support for sub-tokens (device, chat, API) alongside main tokens
Production Ready — BCrypt hashing, automatic rotation, batch request detection
Optional Caching — Drop in ogiri-caffeine or ogiri-redis to eliminate per-request DB reads; explicit opt-in, zero impact if absent

Getting Started

Add the dependency and implement two interfaces:

KotlinJava

// 1. Add dependency (choose one)
implementation("com.quantipixels.ogiri:ogiri-jpa:2.0.0")  // For JPA (recommended)
// OR
implementation("com.quantipixels.ogiri:ogiri-core:2.0.0") // For custom persistence

// 2. Connect to your user system
@Component
class MyUserDirectory(private val userService: UserService) : OgiriUserDirectory {
  override fun findById(id: Long) = userService.getById(id)
  override fun findByUsername(username: String) = userService.getByUsername(username)
  override fun findByEmail(email: String) = userService.getByEmail(email)
  override fun loadUserByUsername(username: String) = userService.getByUsername(username) ?: throw UsernameNotFoundException("User not found: $username")
  override fun recordSuccessfulLogin(userId: Long) { userService.recordLogin(userId) }
}

// 3. Declare public routes
@Component
class MyRouteRegistry : OgiriRouteRegistry {
  override fun routes() = listOf(OgiriRoute.post("/api/auth/**"))
}

// 1. Add dependency (choose one)
// implementation("com.quantipixels.ogiri:ogiri-jpa:2.0.0")  // For JPA (recommended)
// OR
// implementation("com.quantipixels.ogiri:ogiri-core:2.0.0") // For custom persistence

// 2. Connect to your user system
@Component
public class MyUserDirectory implements OgiriUserDirectory {
  private final UserService userService;

  public MyUserDirectory(UserService userService) {
    this.userService = userService;
  }

  @Override public OgiriUser findById(Long id) { return userService.getById(id); }
  @Override public OgiriUser findByUsername(String username) { return userService.getByUsername(username); }
  @Override public OgiriUser findByEmail(String email) { return userService.getByEmail(email); }
   @Override public OgiriUser loadUserByUsername(String username) {
    OgiriUser user = userService.getByUsername(username);
    if (user == null) throw new UsernameNotFoundException("User not found: " + username);
    return user;
  }
  @Override public void recordSuccessfulLogin(Long userId) { userService.recordLogin(userId); }
}

// 3. Declare public routes
@Component
public class MyRouteRegistry implements OgiriRouteRegistry {
  @Override
  public List<OgiriRoute> routes() {
    return List.of(OgiriRoute.post("/api/auth/**"));
  }
}

That's it. Ògiri auto-configures the security filter chain.

Full Quickstart Guide - Complete setup in 5 minutes with Kotlin and Java examples.

Documentation

Getting Started

Quickstart - Get running in 5 minutes

Integration & Configuration

Configuration - All configuration properties
Database Integration - JPA, MongoDB, Redis, custom adapters
Sub-tokens - Device, chat, API tokens

Reference

Authentication Flow - Request lifecycle and headers
Sample Applications - Java and Kotlin examples

Contributing

Development Guide - Build, test, contribute
Changelog - Release history

Requirements

Java 17+
Spring Boot 3.5+
Your choice of database

License

Apache License 2.0