Upgrading from pre-5.5 KMIP Server to a Multi-Tenant KMIP Server

KeyControl supports a multi-tenant KMIP server from version 5.5 onwards, see About Multi-Tenant KMIP.

KeyControl 5.5 and later versions only support fresh multi-tenant KMIP installations.
In KeyControl 5.5.1 and later, it is possible to upgrade from the legacy KMIP server to a multi-tenant KMIP server.

For instructions to upgrade KeyControl from an earlier version to 5.5, a version in which non-multi-tenant KMIP is supported only for new installations but not for upgrades, see Configuring a KeyControl KMIP Server when Upgrading to Version 5.5.

Multi-Tenant KMIP allows KeyControl Security Administrators to isolate different tenant environments for security and compliance. KeyControl-managed user accounts and KeyControl Security Administrators do not have access to the KeyControl KMIP Tenant GUI.

Impacts of the KMIP database migration

The KMIP migration process exports existing KMIP objects and import it into a database in KeyControl. The length of the process depends on the number of KMIP objects in your system and can take several hours.
During migration, KMIP clients won’t be able to create new KMIP objects and the current KMIP environment is in read-only mode.
KeyControl Security Administrators should also ensure that clients don’t change the state of existing KMIP objects. Changes clients tried to do to existing objects during migration may not get transferred to the multi-tenant KMIP server.
Migrating from a pre-5.5. KMIP server to a multi-tenant KMIP server resets the Initial Date and Last Change Date attributes to the time of the migration for all KMIP objects.
KMIP server audit logs from before the migration are not transferred to tenant audit logs. KMIP audit logs generated after migration will only be available in the KeyControl KMIP Tenant GUI.
Email notifications are not sent about KMIP operations after the migration.
The KeyControl KMIP Tenant GUI does not show any alert about expiring KMIP client certificates. Users should monitor and periodically update client certificates that are about to expire.
The number of KMIP tenants (entitlements) is 0 when KMIP Server is used. When the KMIP Server is upgraded to multi-tenant KMIP, the value changes to 1 because KeyControl starts counting the KMIP Server as a tenant. See Checking the Maximum Number of KMIP Tenants.
If multi-tenant KMIP tenant is configured to use local user authentication, all KeyControl managed Security Administrator accounts will be migrated to a KMIP tenant. Security Administrators will be able to use their KeyControl account credentials to log in to the KeyControl KMIP Tenant GUI. KMIP tenant authentication does not support two-factor authentication (2FA). If any Security Administrator account is configured with 2FA, they can log in to the KeyControl KMIP Tenant GUI after migration by just providing the password.

Before You Begin

Ensure that client certificates used by KMIP clients are listed in the Client Certificates tab.

If a client is using a certificate that is deleted from the KeyControl webGUI, the client won’t be able to access the keys after migration. If the certificate has been deleted, reconfigure clients with a new certificate generated from the KeyControl webGUI.
If multi-tenant KMIP is configured with managed authentication, KMIP tenants can be configured with LDAP directory settings. The LDAP directory settings can be configured in the KeyControl KMIP Tenant GUI or in a different LDAP configuration. If you wish to use a different AD configuration, ensure that SMTP server is configured, see Setting Email Server Preferences.

Procedure

To migrate KMIP objects to a multi-tenant KMIP server, the KeyControl Security Administrator needs to create a tenant by specifying tenant authentication and an initial KMIP administrator account that will have access to the KeyControl KMIP Tenant GUI.

Log into the KeyControl webGUI using an account with Security Admin privileges.
In the top menu bar, click KMIP.
To start the migration, click the Get KMIP Multi-tenancy Now the link in KMIP page.
Click Get Started Now.
On the About tab, enter the name and optional description for the KMIP tenant.

The tenant name cannot be edited after the KMIP tenant is created.
Click Next.

In the Authentication tab, select the KMIP Tenant User authentication type.

Field	Description
Local User Authentication	Authenticates KMIP tenant users to the KeyControl KMIP Tenant GUI using password stored in KeyControl.
Managed Authentication	Uses an external authentication services like AD, OpenLDAP, or OIDC to authenticate users.

Click Next.
On the Admin tab, select the initial user account who will have administrative access to the KeyControl KMIP Tenant GUI.

If Local User Authentication is selected, specify the local user account details. It will create a new local user exclusive to the KMIP tenant.

Field	Description
User Name	The login name for the KMIP tenant-managed user account.
Full Name	The full name of the user associated with the account.
Email	If your system is configured to send email alerts, they will be sent to this email address.
Password	Password for the user.
Confirm Password	Confirm password of the user.
Password Expiration	The maximum number of days that a password can be used before it expires. When the password has expired, the user is prompted to change it the next time they log in to the KeyControl KMIP Tenant GUI.

If Managed Authentication is selected, select the Directory Service that you want to use for the KMIP tenant. This can be the LDAP Server already configured in KeyControl or you can provide new LDAP server information for this KMIP tenant.

If you choose Other LDAP, please complete the following:

Click the blue + (Plus sign) in the Directory Service Domain field.

Enter the following and then click Save & Close:

Field	Description
Domain Name	Enter the LDAP domain controller IP address or hostname.
Domain Netbios Name	Enter the netbios or subdomain of the DNS domain.
Domain Controllers	Enter the domain controller that you want to use. You can have one or two domain controllers.

Optionally click the Show Advanced Domain settings link to enter a UID attribute.

Tip: This is the attribute of the user or group object that would be queried during search.

Choose whether to use a User or Group for the Admin user. This user or group is automatically assigned the Administrator role.

You can only add one user or one group at this time. Additional administrators can be added after the KMIP tenant is created by editing the admin access policy.

Tip: You need the CN and DN attributes of the non-system domain for the user or group. Retrieve the following attributes from the AD or OpenLDAP administrator and make sure that they are set correctly for the KMIP tenant:

Active Directory: cn and distinguishedName.
OpenLDAP: cn and dn.

Choose the email address to use for communication.

Ensure you have SMTP configured in KeyControl if you choose to proceed with this option. See Setting Email Server Preferences.
If you selected Other LDAP, you have to log in to that KeyControl KMIP Tenant GUI at this point.
1. The Confirm KMIP tenant login dialog is displayed.
2. Select Log in.
  
  TheKeyControl KMIP Tenant GUI opens in a new tab.
3. Log in to theKeyControl KMIP Tenant GUI, then log out.
4. Switch back to the migration screen.
5. Click Close in the Confirm KMIP tenant login dialog.
Click Continue.
In Migrating KMIP objects, click Continue to start migration.

You can track the KMIP migration status in the KMIP page.
When the migration completed, the Complete KMIP Multi-tenancy Setup dialog is displayed.

Click Complete Setup to switch to use multi-tenant KMIP server.

Important: The KMIP server is restarted when you click Complete Setup.

What to Do Next

Start using the multi-server KMIP feature, see Accessing the KeyControl KMIP Tenant GUI.