If you build multi-tenant Quarkus services, you’ve probably repeated the same logic in multiple codebases:
- read
tenantIdfrom a header (API gateways / service-to-service) - or from a JWT claim (auth-centric flows)
- or from a cookie (browser apps)
- and then wire it into your persistence strategy (Hibernate ORM multitenancy, datasource routing, etc.)
I built a small Quarkus multitenant plugin/extension that standardizes tenant resolution so every service follows the same contract and you don’t keep re-implementing edge cases.
👉 Full deep-dive (architecture + implementation + publishing to Maven Central):
https://medium.com/@mstauroy/building-a-generic-multitenancy-extension-for-quarkus-from-idea-to-maven-central-7c4045c404a3
What this extension solves (in plain terms)
Tenant resolution is the missing “glue” between the HTTP request and whatever tenant isolation strategy you use downstream.
This extension gives you:
- a consistent way to resolve
tenantId - configurable strategy: Header / JWT / Cookie
- a clean place to validate & normalize tenant ids
- a shared runtime API you can extend with your own resolver
It’s intentionally lightweight: it focuses on tenant resolution, not on re-implementing Quarkus security or ORM internals.
When you should use it (and when you shouldn’t)
Use it if:
- you have multiple services and you want a single tenant contract
- you keep duplicating tenant parsing logic across codebases
- you need consistent behavior for “missing tenant” / “invalid tenant”
You may not need it if:
- your scenario is purely OIDC multitenancy (tenant-aware auth provider selection) and tenant id never needs to be resolved independently
- you already have a centralized gateway that injects tenant id consistently and you never read from JWT/cookie
Quick start (Maven Central)
Add the runtime module you need.
### HTTP runtime
<dependency>
<groupId>io.github.mathias82</groupId>
<artifactId>quarkus-multitenancy-http-runtime</artifactId>
<version>0.1.15</version>
</dependency>
### ORM runtime
<dependency>
<groupId>io.github.mathias82</groupId>
<artifactId>quarkus-multitenancy-orm-runtime</artifactId>
<version>0.1.15</version>
</dependency>
Header strategy
quarkus.multi-tenant.http.enabled=true
quarkus.multi-tenant.http.strategy=header
quarkus.multi-tenant.http.header-name=X-Tenant
Call it:
curl -H "X-Tenant: tenant1" http://localhost:8080/api/users
JWT strategy (tenant inside claims)
quarkus.multi-tenant.http.enabled=true
quarkus.multi-tenant.http.strategy=jwt
# example claim name (adjust to your token)
quarkus.multi-tenant.http.jwt-claim=tenant_id
Cookie strategy (browser clients)
quarkus.multi-tenant.http.enabled=true
quarkus.multi-tenant.http.strategy=cookie
quarkus.multi-tenant.http.cookie-name=tenantId
Demo (run locally)
If you want to see it working end-to-end with multiple datasources, there’s a demo project in the repo.
docker-compose up -d
mvn quarkus:dev
GitHub repo: https://github.com/mathias82/quarkus-multitenancy
Notes & best practices
A few things I learned while building this:
- Decide precedence (Header vs JWT vs Cookie) once and document it.
- Validate tenant ids (empty/length/pattern) to avoid weird bugs and security issues.
- Make “missing tenant” behavior consistent across services (400 vs 401 vs default tenant).
Read the full article
If you want the full breakdown (idea → extension modules → design choices → Maven Central publishing), the complete write-up is on Medium:
https://medium.com/@mstauroy/building-a-generic-multitenancy-extension-for-quarkus-from-idea-to-maven-central-7c4045c404a3
If you’re using tenant resolution in Quarkus today, I’d love to hear what works best for you (header vs JWT vs cookie) and what constraints you have.
Top comments (2)
👏Nice, clear overview of building a reusable multitenancy extension for Quarkus. A practical approach that can be very useful for SaaS-focused teams. Thank you Matthaios!
thank you for your comment!