Ògiri

Reusable Spring Boot security components for token-based authentication with pluggable sub-tokens.

📖 Full Documentation | Quickstart | Migration Guide

Features

• Database-agnostic - Works with JPA, MongoDB, Redis, or any custom persistence
• Auto-configured - Spring Boot auto-configuration with customization options
• Token rotation - Configurable rotation with batch request detection
• Sub-tokens - Pluggable sub-tokens for chat, device, API, etc.
• Secure by default - BCrypt hashing, timestamp validation, grant-based authorization

Installation

Server (Kotlin/Java)

See the Maven Central badge above for the latest version. Replace VERSION in all snippets below.

With JPA Support (Recommended):

// See badge above for latest version
implementation("com.quantipixels.ogiri:ogiri-jpa:VERSION")

With JDBC Support (no ORM):

// See badge above for latest version
implementation("com.quantipixels.ogiri:ogiri-jdbc:VERSION")

Core Only (Custom Persistence):

// See badge above for latest version
implementation("com.quantipixels.ogiri:ogiri-core:VERSION")

Optional lookup caches:

// See badge above for latest version
implementation("com.quantipixels.ogiri:ogiri-caffeine:VERSION") // in-process
implementation("com.quantipixels.ogiri:ogiri-redis:VERSION")    // distributed

Maven (JPA):

<!-- See badge above for latest version -->
<dependency>
  <groupId>com.quantipixels.ogiri</groupId>
  <artifactId>ogiri-jpa</artifactId>
  <version>VERSION</version>
</dependency>

Requirements: Java 17+, Spring Boot 3.5+

Client (TypeScript/JavaScript)

TypeScript/JavaScript client for browser and Node.js:

npm install ogiri-security-client
# or
pnpm add ogiri-security-client

The TypeScript client handles token storage, automatic rotation, and request interception. See ogiri-client/ for usage examples and API documentation.

Quick Start

1. Implement user directory:

Connect your user database by implementing OgiriUserDirectory. Note that loadUserByUsername is inherited from Spring Security's UserDetailsService and must throw UsernameNotFoundException if the user does not exist.

@Component
class MyUserDirectory(private val userService: UserService) : OgiriUserDirectory {
  override fun findById(id: Long): OgiriUser? = userService.getById(id)
  override fun findByUsername(username: String): OgiriUser? = userService.getByUsername(username)
  override fun findByEmail(email: String): OgiriUser? = userService.getByEmail(email)

  override fun loadUserByUsername(username: String): OgiriUser =
      userService.getByUsername(username) ?: throw UsernameNotFoundException("User not found: $username")

  override fun recordSuccessfulLogin(userId: Long) { userService.recordLogin(userId) }
}

2. Declare public routes:

@Component
class MyRouteRegistry : OgiriRouteRegistry {
  override fun routes() = listOf(OgiriRoute.post("/api/auth/**"), OgiriRoute.get("/api/health"))
}

3. Extend OgiriTokenService with your token type:

@Service
class MyTokenService(
    repository: MyTokenRepository,       // your concrete Spring Data repository
    passwordEncoder: PasswordEncoder,
    userDirectory: OgiriUserDirectory,
    identifierPolicy: IdentifierPolicy,
    subTokenRegistry: OgiriSubTokenRegistry,
    properties: OgiriConfigurationProperties,
) : OgiriTokenService<MyToken>(
    repository, passwordEncoder, userDirectory,
    identifierPolicy, subTokenRegistry, properties,
) {
  override fun tokenFactory(...): MyToken = MyToken().apply { /* set fields */ }
}

Optional extension points (OgiriAuditHook, OgiriRateLimitHook, OgiriTokenLookupCache) are wired automatically via setter injection when the corresponding beans are present — no constructor changes needed.

4. Issue tokens on login:

@PostMapping("/api/auth/login")
fun login(@RequestBody request: LoginRequest, response: HttpServletResponse) {
  val user = authenticate(request.username, request.password)
  response.appendAuthHeaders(tokenService.createNewAuthToken(user.id, "web"))
}

Done! Ògiri auto-configures the security filter chain.

See the full Quickstart Guide for complete examples in both Kotlin and Java.

Documentation

Topic	Description
Quickstart	5-minute integration guide
Interface Design	Architecture and design philosophy
Configuration	Token rotation, cleanup, batch windows
Database Integration	JPA, JDBC, MongoDB, Redis examples
Sub-tokens	Device, chat, API tokens
Authentication Flow	Request lifecycle, headers
Migration Guide	Upgrade guide (see docs for version notes)
Sample Applications	Java and Kotlin examples

Development

Requirements: Java 17 (Java 25 is not supported — Kotlin compiler and Spotless/google-java-format incompatibilities).

Kotlin/Java:

./gradlew build                  # Build and test all modules
./gradlew test                   # Run tests only
./gradlew :ogiri-core:test       # Run core module tests only
./gradlew spotlessApply          # Format code

TypeScript client:

cd ogiri-client
pnpm install                     # Install dependencies
pnpm build                       # Build for production
pnpm test                        # Run tests
pnpm test -- --coverage          # Run tests with coverage

Always use pnpm (not npm or yarn) for TypeScript/Node.js operations in this repository.

Git hooks (optional):

lefthook install

See development guide for contributor guidelines.

License

Apache License 2.0 - See LICENSE for details.