feat(KeyCloak) : Migrate KeyCloak-SW360 Database Communication

[bibhuti230185]

Migrate KeyCloak-SW360 Database Communication to Direct CouchDB Access

Overview

This PR migrates KeyCloak’s database communication from Thrift via the SW360 application to a direct CouchDB connection using library functions. This decouples KeyCloak from the SW360 application, allowing both to run independently and improving performance.

Changes

• Integrated CouchDB library functions for direct access in KeyCloak
• Reused existing Thrift-based data models (to be migrated later)
• Implemented and verified direct connectivity between KeyCloak and CouchDB
• Developed functional tests for read, write, import, and update operations
• Ensured KeyCloak can operate without the SW360 application running
• Updated documentation for new architecture and configuration

Test Cases (all completed)

• KeyCloak can read data from CouchDB via the new direct connection
• KeyCloak can write/update data in CouchDB via the new direct connection
• KeyCloak can perform import operations directly to CouchDB
• KeyCloak can perform update operations directly to CouchDB
• KeyCloak interacts with CouchDB successfully when the SW360 application is not running

Impact

• Simplifies communication architecture
• Improves performance and reliability
• Enables independent operation of KeyCloak and CouchDB

Closes #3405

Suggest Reviewer

@GMishx

[GMishx]

Few optimization suggestions.

[GMishx]

Few more things left out.

[GMishx]

Changes looks good.

[GMishx]

@bibhuti230185 , please rebase the branch to resolve the conflicts

[GMishx]

I just tested the branch. Have some findings to be looked into @bibhuti230185 :

1. While building the KeyCloak server, it printed following warning. Please have a look.

   2025-11-09 13:30:00,859 WARN  [io.quarkus.arc.deployment.SplitPackageProcessor] (build-10) Detected a split package usage which is considered a bad practice and should be avoided.
   Following packages were detected in multiple archives: 
   - "okhttp3" found in [/opt/keycloak-26.4.0/lib/../providers/okhttp-4.12.0.jar, /opt/keycloak-26.4.0/lib/../providers/okhttp-urlconnection-4.12.0.jar]
   

2. While updating the user in KeyCloak, the data was never synced back to CouchDB. When I checked the log I saw the following:

   Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,632 INFO  [org.eclipse.sw360.keycloak.event.listener.Sw360CustomEventListenerProviderFactory] (executor-thread-19) Creating Sw360CustomEventListenerProvider
   Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,632 INFO  [org.eclipse.sw360.keycloak.event.listener.service.Sw360UserService] (executor-thread-19) Initializing SW360 user service for event listener with CouchDB connection to: http://localhost:5984
   Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,639 INFO  [org.eclipse.sw360.keycloak.event.listener.service.Sw360UserService] (executor-thread-19) SW360 user service initialized successfully for event listener
   Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,649 ERROR [org.eclipse.sw360.keycloak.event.listener.service.Sw360KeycloakAdminEventService] (executor-thread-19) CustomEventListenerSW360::onEvent(_,_)::Json mapping error--> com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of type `java.lang.String` from Object value (token `JsonToken.START_OBJECT`)
   Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]:  at [Source: REDACTED (`StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION` disabled); line: 1, column: 407] (through reference chain: org.eclipse.sw360.keycloak.event.model.UserEntity["federatedIdentities"]->java.util.ArrayList[0])
   Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,945 INFO  [org.eclipse.sw360.keycloak.event.listener.Sw360CustomEventListenerProviderFactory] (executor-thread-19) ID of Sw360CustomEventListenerProviderFactory: sw360-add-user-to-couchdb
   

3. I cannot start the sync from User federation > sw360-user-storage-jpa > Action > Sync all users

[bibhuti230185]

@GMishx , Thanks for the review.
1( for "Following packages were detected in multiple archives: " : While running Keycloak sync , key cloak is expecting all these independent libraries as we have true . Removing these throws runtime error and going with excludeTransitive as false brings all jars to keycloak provider making it fail to deploy.
2) and 3) : to specify our Couch DB details we have Priority: SPI config > Environment variables > Properties file > Defaults. As per the log the default setting from properties is selected and connection is failing. Can you try to specify the couch db connection details either thru SPI or thru env and retest.

[GMishx]

1. okay, I guess we can live with that.
2. and 3) Are you sure about that, I see the following in the logs as expected making me think the connection was successful:

Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,632 INFO  [org.eclipse.sw360.keycloak.event.listener.service.Sw360UserService] (executor-thread-19) Initializing SW360 user service for event listener with CouchDB connection to: http://localhost:5984
Nov 09 13:48:21 ip-10-142-7-233 kc.sh[3631745]: 2025-11-09 13:48:21,639 INFO  [org.eclipse.sw360.keycloak.event.listener.service.Sw360UserService] (executor-thread-19) SW360 user service initialized successfully for event listener

[bibhuti230185]

Please add the following SPI configuration and restart the keycloak server

SW360 SPI Configuration

Event listener SPI for adding users to CouchDB

spi-events-listener-sw360-add-user-to-couchdb-couchdb-url=
spi-events-listener-sw360-add-user-to-couchdb-couchdb-username=
spi-events-listener-sw360-add-user-to-couchdb-couchdb-password=
spi-events-listener-sw360-add-user-to-couchdb-couchdb-database=sw360users

User storage SPI for reading users from SW360 database

spi-storage-sw360-user-storage-jpa-couchdb-url=
spi-storage-sw360-user-storage-jpa-couchdb-username=
spi-storage-sw360-user-storage-jpa-couchdb-password=
spi-storage-sw360-user-storage-jpa-couchdb-database=sw360users

[GMishx]

@bibhuti230185 , I just tested using the SPI variables in my config and the update of user still failed with following error:

Nov 14 07:54:13 ip-10-142-7-233 kc.sh[32384]: 2025-11-14 07:54:13,339 INFO  [org.eclipse.sw360.keycloak.event.listener.service.Sw360UserService] (executor-thread-4) SW360 user service initialized successfully for event listener
Nov 14 07:54:13 ip-10-142-7-233 kc.sh[32384]: 2025-11-14 07:54:13,380 ERROR [org.eclipse.sw360.keycloak.event.listener.service.Sw360KeycloakAdminEventService] (executor-thread-4) CustomEventListenerSW360::onEvent(_,_)::Json mapping error--> com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of type `java.lang.String` from Object value (token `JsonToken.START_OBJECT`)
Nov 14 07:54:13 ip-10-142-7-233 kc.sh[32384]:  at [Source: REDACTED (`StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION` disabled); line: 1, column: 408] (through reference chain: org.eclipse.sw360.keycloak.event.model.UserEntity["federatedIdentities"]->java.util.ArrayList[0])

And syncing all users still fails with message 'Synchronization ignored as it's already in progress.' and nothing else happens.