Resolving duplicate users before upgrade on Cloud Pak for Integration

If you are upgrading API Connect in Cloud Pak for Integration and the API Connect pre-upgrade check indicates duplicate user accounts in the registry, resolve them before you proceed with the upgrade.

Before you begin

This task applies only when you are upgrading API Connect in Cloud Pak for Integration from 2023.2 (or earlier) to 16.1 (or later). Be sure to run the pre-upgrade check as explained in Pre-upgrade preparation and checks on OpenShift to determine whether duplicate user records exist in your deployment.

About this task

Cloud Pak for Integration uses Keycloak as an OIDC provider to authenticate users instead of IAM (Identity and Access Management). Due to differences in how Keycloak and IAM treat usernames, you might need to manually delete duplicate user accounts to ensure that users can log in after the upgrade. Review the following scenarios to determine whether you need to manually delete any user accounts.

In a user registry, each user is uniquely identified by their username. If a registry allows for case-sensitive usernames, then two user records with matching usernames that use different cases (for example, Alice and ALICE) can exist and they point to two different users. If the registry is case-insensitive, then Alice and ALICE point to the same user.

If the user registry that is backing IAM supports case-sensitive usernames, then IAM uses the case of the username from that registry. For example, if IAM is backed by an LDAP directory that contains ALICE as the username, then IAM also uses ALICE as the username.

Keycloak supports only lowercase letters for usernames, so ALICE from the LDAP directory is stored with the preferred_name alice in Keycloak.

Assuming ALICE is the username in the LDAP directory and was used by IAM before the API Connect upgrade, then API Connect might contain either alice or ALICE in its database after the upgrade, depending on how that user logged in to API Connect after the upgrade:

If the user logged in using the Automation UI in Cloud Pak for Integration, then API Connect created a lowercase username (alice).
If the user logged in using the API Connect toolkit, or an invitation from API Connect, then API Connect created a username that matches the case that was used in the underlying registry (ALICE).

It is possible that two user records now exist for the same user because one might be in lowercase letters and the other might be in uppercase or mixed-case letters. To determine whether duplicate user records exist and then resolve them, complete the following steps.

Procedure

Review the results of the pre-upgrade check to determine whether your deployment includes duplicate users.

If duplicate user records are detected, the script returns a response similar to the following example (note the duplicated username setting):

** Checking for duplicate users in the common-services user registry **
Command: apicops-v10 duplicate-users
*****************************
getDuplicateUsers::getDuplicateUsers Entering
Found duplicate user entries: [
    {
        "username": "alice",
        "id": "291339db-acd9-493d-98c2-cfd47185588e",
        "name": "alice",
        "title": "alice",
        "first_name": "ALICE",
        "last_name": "CAPS",
        "email": "alice@gmail.com",
        "identity_provider": "common-services",
        "created_at": "2023-11-22T21:43:51.000Z",
        "updated_at": "2023-11-28T19:17:42.000Z",
        "last_login_at": "2023-11-28T19:17:42.000Z",
        "url": "/api/user-registries/118b7e20-3f97-40ce-bc00-936f202d52a4/6f69a530-4192-4610-ba1f-15ea9711284e/users/291339db-acd9-493d-98c2-cfd47185588e"
    },
    {
        "username": "ALICE",
        "id": "6325084d-91a0-4c1e-9743-d615105ce4e3",
        "name": "ALICE-from-common-services-of-type-standard",
        "title": "ALICE from common-services of type standard",
        "first_name": "ALICE",
        "last_name": "ALICE",
        "email": "alice@gmail.com",
        "identity_provider": "common-services",
        "created_at": "2023-11-22T21:59:41.000Z",
        "updated_at": "2023-11-22T21:59:48.000Z",
        "last_login_at": "2023-11-22T21:59:48.000Z",
        "url": "/api/user-registries/118b7e20-3f97-40ce-bc00-936f202d52a4/6f69a530-4192-4610-ba1f-15ea9711284e/users/6325084d-91a0-4c1e-9743-d615105ce4e3"
    }
]
================================================
 WARNING:
================================================
 Duplicate user records have been detected in the common-services user registry.
 Duplicate records will NOT be fixed by the system and might cause unexpected behavior. 
 Please refer to product documentation on steps to clean up the duplicate entries.
================================================
*****************************

************************************************
** Finished: apicops-v10 version:pre-upgrade **
************************************************

In this example, duplicate records were detected, with the username "alice" and "ALICE".

If your results do not indicate any duplicate users, skip the rest of this task. If the results indicate any duplicates, continue with the remaining steps to resolve the user records.

Decide which user account you want to preserve; the other account is considered to be the duplicate.

You can retain either account. The choice is a matter of convenience. For example, if one of the accounts functions as the owner of organizations, you might find it simpler to retain that account to avoid having to transfer ownership to the other account. You do not have to rename the account because you delete the duplicate account; the username of the preserved account is converted to lowercase during the upgrade. For example, if you choose to preserve user "ALICE" and you delete the record for "alice" then the username for "ALICE" will be converted to "alice" the first time the user logs in after the upgrade.
If needed, transfer ownership of assets to the account that you want to preserve:
1. Transfer ownership of catalogs.
  
  For instructions, see Transfer Catalog Owner on GitHub.
2. Transfer ownership of spaces within catalogs.
  
  For instructions, see Transfer Space Owner on GitHub.
3. Transfer ownership of a provider organization.
  
  For instructions, see Transfer Org Owner on GitHub.
Add any missing roles to the account that you want to preserve.

Check the roles that are assigned to the duplicate account. If the account that you want to preserve does not include those roles, assign them now. For instructions, see Assigning roles to members in this documentation.
Delete the duplicate user account.

For instructions, see Removing a user from a user registry in this documentation.