Best practice for User Provisioning between Microservice DB and Keycloak in a DDD/Hexagonal Architecture #45914

nursultanaslan · 2026-01-31T17:13:34Z

nursultanaslan
Jan 31, 2026

I'm building a microservices system using Java Spring Boot, DDD, and Hexagonal Architecture.

Current Stack:

BFF Service: Orchestrates frontend requests.
Customer Service: Manages domain-specific data in PostgreSQL.
Keycloak: Handles Authentication and Identity. (Authorization Service)

The Problem: When a new customer registers, I need to:

Create a record in my customer-service PostgreSQL DB.
Provision the user in Keycloak (so they can log in).

Here is CreateCustomerUseCase:


public CustomerResponse createCustomer(@Valid CreateCustomerRequest request) {
    Customer customer = customerMapper.toDomain(request);
    customer = customerRepository.save(customer);
    return customerMapper.toResponse(customer);
}

I am struggling with the most robust way to sync these two. I considered an event-driven approach where customer-service publishes a CustomerCreated event, but I'm unsure who should consume it to talk to Keycloak's Admin API.

Questions:

1-) Is it a good practice to handle Keycloak provisioning inside an Infrastructure Adapter in the customer-service itself?
2-) How do I ensure Data Consistency if Keycloak is down during registration? Should I use the Transactional Outbox Pattern?

codewithmahad · 2026-10-24T10:33:25Z

codewithmahad
Oct 24, 2026

Hi, I think your idea of using an infrastructure adapter is reasonable, especially since you're already following Hexagonal Architecture.

I would keep the Keycloak integration behind a port in your application layer, with an infrastructure adapter responsible for calling the Keycloak Admin API. That keeps the domain independent of Keycloak-specific implementation details.

The bigger concern is consistency between PostgreSQL and Keycloak.

A regular database transaction cannot atomically commit changes to PostgreSQL and an external Keycloak API. If the database operation succeeds but the Keycloak request fails, you could end up with a customer who cannot log in.

For an asynchronous registration process, I would consider this approach:

Save the customer with a PENDING status.
In the same PostgreSQL transaction, save an outbox event describing the provisioning request.
Let a background worker consume the event and call the Keycloak Admin API.
When provisioning succeeds, store the Keycloak user ID and update the customer status to ACTIVE.
If Keycloak is temporarily unavailable, retry with backoff and keep the customer in PENDING until the operation can be completed or requires intervention.

The important part is making provisioning idempotent. For example, if the Keycloak request succeeds but the worker crashes before updating PostgreSQL, a retry should reconcile the existing identity rather than create a duplicate.

Regarding which service should consume the event, I'd keep it within the customer service if identity provisioning is part of that service's responsibility. A separate identity-provisioning service makes more sense if multiple domains need the same capability.

The BFF would not be my first choice for owning this process.

So yes, an infrastructure adapter is appropriate, and the Transactional Outbox Pattern is a good fit if eventual consistency is acceptable for your registration flow.

The remaining design decision is whether a newly registered customer can stay in PENDING temporarily, or whether your business requirements need immediate registration success or failure.

0 replies

Navigation Menu

Repository navigation

Best practice for User Provisioning between Microservice DB and Keycloak in a DDD/Hexagonal Architecture #45914

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Best practice for User Provisioning between Microservice DB and Keycloak in a DDD/Hexagonal Architecture #45914

Uh oh!

nursultanaslan Jan 31, 2026

Replies: 1 comment

Uh oh!

codewithmahad Oct 24, 2026

nursultanaslan
Jan 31, 2026

codewithmahad
Oct 24, 2026