/
Run migration for existing users tor unified login in Eureka

Run migration for existing users tor unified login in Eureka

Owned by Serhii_Nosko
Last updated: Mar 26, 2025

How to enable feature for Unified login for Keycloak based Eureka environments

The feature to enable login for users from member tenants should be enabled by making modifications to the following two modules:

  1. mod-users-keycloak

    • Set the SINGLE_TENANT_UX variable to true.

  2. mod-consortia-keycloak

    • Set the SINGLE_TENANT_UX variable to true. Additionally, the following environment variable must be added:
      KC_IDENTITY_PROVIDER_BASE_URL

Example PR with enabling the feature for Rancher based envs: https://github.com/folio-org/pipelines-shared-library/pull/847/files

After enabling this feature, the user will see a single login page, and the system will automatically determine the tenant the user should be logged into.

image-20250326-085809.png

How to decide is migration needed

This type of migration is different from the earlier migration we performed to create Keycloak users from existing users. The new migration is a separate process designed to establish a Custom Login Flow in Keycloak within the central tenant, create Keycloak Identity Providers, and generate identity links between users in the member tenant and shadow users in the central tenant. These links are created for existing users in the tenant with type=staff.

If a new tenant is added to the consortium, no migration is required, as Keycloak Identity Provider and users links will be migrated automatically during the invocation of the POST /consortia/<<uuid>>/tenant API call.

However, if a tenant has already been added to the consortium, a migration must be performed to establish the Custom Login Flow in Keycloak within the central tenant, and create Keycloak Identity Providers with creating links for existing users in each member tenant .

How to perform migration

To perform that migration need to invoke these 2 REST calls.

For central tenant to create Custom Login Flow (without request body):

POST /consortia/<<consortiumId>>/tenants/<<centralTenantId>>

It is synchronus process, so to verify is operation successful http response codes should be used.

For each member tenant, but without central tenant:

POST /consortia/<<consortiumId>>/tenants/<<memberlTenantId>> { "createProvider": true, "migrateUsers": true }

This is an asynchronous process, and there is no endpoint available to verify its state. In case a user from a member tenant is unable to log in, only the logs in mod-consortia-keycloak and mod-users-keycloak can be used for troubleshooting. If necessary, this endpoint can be re-run.

The migration process handles only staff users. Even for the largest tenants, the number of staff users typically does not exceed 100, so the migration should take seconds rather than minutes.

Note: all http requests should be executed with central tenant context with populating header x-okapi-tenant = <<centralTenantId>>

How to verify migration

To verify the migration, find a user in the member tenant and use their username and password to log in from the Central Login page. The system will automatically identify the user's primary tenant, which will be displayed in the Switch Affiliation menu.

Related content