Building an IAM from scratch: architecture lessons

Building an IAM platform is not implementing login. It is designing contracts among identity, authorization, audit, and the experience of the developer who integrates. At Gatekeeper ID we learned that in practice: every shortcut in tenant isolation or token validation becomes an incident or a support ticket months later.

Decision 1: do not reinvent OAuth2

Keycloak (and similar systems) as the authorization server per tenant gave us correct OIDC, JWKS, refresh, and social brokers without writing RFCs. Our difference stayed in the layer above: the integration API, the console, the SDK, and onboarding automation — not the JWT parser.

Decision 2: the tenant at the center

Every request carries tenant context. Isolated realms, API keys per customer, standardized headers. Isolation tests are a required suite — not an optional checklist.

Decision 3: the integrator’s experience

Java developers do not want to configure 40 admin screens. They want a Maven dependency, YAML, and an annotation. That is why the Spring Boot SDK and the public OpenAPI are first-class. The console serves operations; the docs serve the people who code.

Problems that appeared

Multi-tenant social login

Redirect URIs, OAuth clients, and secrets per tenant — automation in the backend, not manual copy and paste.

RBAC that has to evolve

Customers ask for finer permissions after the MVP. We modeled roles to permissions early so we would not break tokens in production.

Observability

Login failed — was it the password, a rate limit, the wrong tenant, or the external identity provider? A correlation id from the gateway to the Keycloak realm.

Mistakes we would avoid today

• Underestimating the time for documentation and runnable examples
• Implicit permissions in the token with no versioning
• An admin console coupled too tightly to the native Keycloak UI

What Gatekeeper delivers today

• Login, registration, refresh, Google social login
• A console for users, groups, roles, and permissions
• A Java SDK with @GatekeeperProtected
• An HMAC API for server-side integration
• Multi-tenant from the first customer

Conclusion

IAM is a platform product. If you do not sell IAM as the business, buying or using an opinionated solution almost always beats an internal build. If you do sell it, invest in tenant, developer experience, and audit before marketing features.

Comparison: Keycloak vs Gatekeeper. Foundations: why not to build login from scratch.