Overview

This document provides a comprehensive guide for migrating from the Okapi-based deployment to the Eureka platform. It outlines the steps necessary to ensure a smooth transition for authentication users and permission-to-role mappings. The goal is to minimize downtime and ensure data integrity throughout the migration process.

Pre-requisites

1. Ensure all user data is backed up.

2. Communicate the upcoming changes to all users and provide a timeline.

Migration Algorithms

Users migration

This migration is used to migrate all existing users with credentials to Keycloak to make them available to authenticate in Eureka platform.

It can be run using the following API:

1. This migration retrieves all users from mod-users by the following query: id=* NOT permissions==[]

2. It splits retrieved userIds by chunks and then for each chunk perform the following operations:

   1. Find users by a chunk of userIds

   2. Removes all users without usernames

   3. Create a users in Keycloak

      1. Password can be configured as username by default, by using environment variable for mod-users-keycloak: DEFAULT_PASSWORDS_ON_MIGRATION

      2. If email is not valid according to Keycloak - user will be created without email

Permissions migration

This migration is used to migrate existing permission for users as roles assigned to corresponding users and containing the same authorization permission as original Okapi-based platform.

This migrations must be run after users migration. This migration process does NOT intend to create roles for individual user-defined permission sets. Resulting roles will have system-generated names, and are likely to not be organized in an ideal way. The goal is to get the system to a state where users who were able to perform certain actions on Okapi, are still able to perform those same actions on Eureka. The expectation is that some cleanup/refactoring (e.g. renaming, splitting, etc.) will need to be done afterwards.

It can be run using the following API:

1. It loads all Keycloak users from the tenant realm

2. It loads all user permissions from mod-permissions using GET /users/{userId}/permissions API

3. It creates unique sets of permissions and then generate a sha1 hash-based role name for this permission set

   1. Each role is created in Keycloak

   2. Authorization permissions are created for roles based on found capabilities by permission name

   3. All corresponding users are assigned to this role

Migration Process

Common Pitfalls

Migration Verification

Verification can be done selectively by picking users and verifying that they have the same access as before in the Okapi-based platform using the following steps:

1. Logging as selected users if they have a generated password, if not - the password must be set using mod-login-keycloak API

2. Perform API calls to evaluate that user has the same access to the Folio as before