Installation

Module layout

IAM ships as a small family of backend libraries plus two frontend packages. Dependency direction: starter → rest → core → engine/api.

Module	What it is
iam-spring-boot-starter	The one you depend on. Code-free aggregator: auto-configuration + REST + the Spring starters IAM needs
iam-spring-boot-autoconfigure	@AutoConfiguration classes and the dev-mode secret generator
iam-rest	REST controllers, OpenAPI, exception advice
iam-core	Entities, services, permission resolution, security, migrations, SPI
iam-engine	Pure decision engine — DENY-wins evaluation + decision traces, no Spring, no I/O
iam-api	Spring-free contract: @RequiresPermission/@FieldFiltered/@Audited, DTOs, enums, exceptions
iam-bom	Bill of materials aligning all module versions
@mpofusindie/iam-react	React provider, hooks, guard components (npm)
Admin UI	Standalone React dashboard for users/roles/permissions

Gradle

dependencies {
    implementation(platform("dev.mpofusindie:iam-bom:2.0.0"))
    implementation("dev.mpofusindie:iam-spring-boot-starter")

    // Your database driver + Flyway support (IAM runs the migrations, you pick the vendor)
    runtimeOnly("org.postgresql:postgresql")
    runtimeOnly("org.flywaydb:flyway-core")
    runtimeOnly("org.flywaydb:flyway-database-postgresql")
}

Not on Maven Central yet

Until 2.0.0 is published, build the libraries from a clone (./gradlew publishToMavenLocal) and add mavenLocal() to your repositories { } — nothing resolves without it.

MySQL instead

runtimeOnly("com.mysql:mysql-connector-j")
runtimeOnly("org.flywaydb:flyway-core")
runtimeOnly("org.flywaydb:flyway-mysql")

…and set iam.database.vendor: mysql. Details in Database Vendors.

IAM’s migrations and your Flyway

IAM migrates its own schema through a dedicated Flyway instance: history table iam_flyway_history, migrations from classpath:db/iam/migration/<vendor>. Your spring.flyway.* configuration stays entirely yours — hosts with their own migrations use plain Spring Boot defaults (db/migration, flyway_schema_history) with no extra location entries. IAM’s run is ordered after your Flyway and before Hibernate starts, so ddl-auto: validate works out of the box. Opt out with iam.database.migrations-enabled: false if you apply IAM’s SQL through your own pipeline (note: spring.flyway.enabled: false disables only your Flyway, never IAM’s).

Redis (only if you opt in)

The starter deliberately does not ship Redis. The default cache and rate-limit stores are in-memory. If you set iam.cache.store: redis or iam.rate-limit.store: redis, add:

implementation("org.springframework.boot:spring-boot-starter-data-redis")

Business modules: depend on the contract only

In a multi-module host, only the application module needs the starter. A business module that just declares which permissions its endpoints require depends on iam-api alone — a Spring-free jar carrying @RequiresPermission, @FieldFiltered, and @Audited (plus DTOs, enums, and exceptions):

// a business module's build.gradle.kts
dependencies {
    implementation(platform("dev.mpofusindie:iam-bom:2.0.0"))
    implementation("dev.mpofusindie:iam-api")   // annotations compile here; enforcement
                                                // arrives at runtime via the app's starter
}

Control-plane modules: depend on the engine, deliberately

There is a second consumer persona: the ONE module in a multi-tenant host that provisions tenants (a platform-tenancy-style module). Provisioning is engine work, so that module depends on iam-core — this is intended, not a workaround:

// the control-plane module's build.gradle.kts — the only non-app module that sees iam-core
dependencies {
    implementation(platform("dev.mpofusindie:iam-bom:2.0.0"))
    implementation("dev.mpofusindie:iam-core")
}

Its front door is the IamTenantProvisioning facade — createTenant(name, slug) + provision(tenantId) — which covers the whole create-and-provision flow without touching repository ports, Hibernate, or Flyway machinery (see Multi-Tenancy). The tiering rule: business modules → iam-api; control-plane/infrastructure modules → iam-core. Keep the iam-core dependency fenced to that one module.

What the starter pulls in

spring-boot-starter-web, -data-jpa, -security, -validation, -aop — exposed transitively so a host app’s build stays minimal. Nothing else: no Redis, no vendor drivers, no optional infrastructure. Every additional capability is opt-in with a documented dependency.

Frontend

npm install @mpofusindie/iam-react

See the React Library guide for IAMProvider and the guard components.

Compatibility

• Spring Boot 3.4+, Java 17+ (built with Kotlin 1.9)
• PostgreSQL 13+ (default) or MySQL 8.0.13+
• Hibernate 6.6 (from Boot’s dependency management)