Transition a VCF Identity Broker 9.0.x Instance to the VCF Services Runtime Environment

Products

• VMware Cloud Foundation

Issue/Introduction

If your VCF environment has VCF Identity Broker 9.0.x in appliance mode that is deployed on a network or datastore that differs from the one planned for the VCF management services in 9.1, you must perform the following procedure. 

This process is a service-disruptive change and requires a maintenance window.

Environment

• VCF 9.0.x
• VCF 9.1.x

Cause

In VCF 9.1, the VCF Identity Broker transitions from a standalone appliance deployment model to being hosted within the VCF Management Service Environment. When the existing VCF Identity Broker 9.0.x appliance was originally deployed on a network or datastore that does not match the one designated for VCF management services in 9.1, it cannot be migrated in place by the standard upgrade path.

Resolution

Table of contents

Prerequisites
Method 1 - Migrate VCF Identity Broker Configuration Using Backup and Recovery Scripts
Method 2 - Delete and Redeploy VCF Identity Broker 9.1

Prerequisites

1. SDDC Manager is upgraded to 9.1. See Upgrade to SDDC Manager 9.1
2. VCF management services 9.1 is deployed and 9.0.x VIDB is imported. See Deploy VCF Management Services and License Server as Part of VCF Upgrade to 9.1
   
   

Method 1 - Migrate VCF Identity Broker Configuration Using Backup and Recovery Scripts

Use the backup and recovery scripts to export the configuration from the VCF Identity Broker 9.0.x cluster and import it into a newly deployed VCF Identity Broker 9.1.x instance. This preserves your existing IAM configuration, including IDP settings, component configurations, and generic clients, without requiring manual reconfiguration.

Procedure

1. Download the scripts on a host, for example VCF OPs or vCenter, where python is available and connectivity to VCF OPs, VSP Platform Cluster and Fleet LCM is there.

2. Run the backup script against the existing VCF Identity Broker 9.0.x to export the data and certificates. This process takes up to 15 minutes.
   
   ./backup_vidb.sh --cluster-ip <VIDB_9_0_CLUSTER_IP> --backup-dir <PATH_TO_DIR> --user <Cluster user> 



   Parameters

   Parameter	Type	Required	Description	Default
   --cluster-ip <ip>	string	Yes*	9.0 VIDB cluster IP or Primary VIP
   --backup-dir <PATH_OP_BACKUP_DIR>	string	No	Local Directory path where the backup files will be stored	./vidb-backups
   --user <9.0 VIDB Cluster user>	string	No	SSH Cluster user for 9.0 External VIDB	vmware-system-user

    

3. Run the removal script to remove the VCF Identity Broker 9.0.x from the Lifecycle Management.
   
   The SSO will continue to work even after this, only the VIDB reference is removed from Lifecycle page. The next phases should be performed during the maintenance window.
   
    ./delete_vidb_component.sh \
   --ops-fqdn <OPS_FQDN> \
   --fleet-fqdn <FLEET_FQDN> \
   --vidb-fqdn <VIDB_FQDN_AS_SHOWN_IN_FLEET_UI> \
   --user <VCF_OPS_ADMIN_USER> # Optional Default is admin
   
   

   Parameters

   Parameter	Required	Description	Default
   --ops-fqdn	Yes*	VCF Operations FQDN
   --fleet-fqdn	Yes*	Fleet lifecycle FQDN
   --vidb-fqdn	Yes*	VIDB FQDN in Build → Lifecycle → Components
   --user	No	VCF Operation Admin User	admin

   
   
   
4. Power off the VCF Identity Broker 9.0.x virtual machines from the vSphere Client.
   
   Important: Service downtime begins from this step. Ensure you perform all subsequent steps within your scheduled maintenance window. 
   
   
5. (This step is applicable only if VCF Identity Broker 9.0.x appliance was deployed on a network different from the VCF management services in 9.1) Update your DNS to map the VCF Identity Broker FQDN to the new IP address on the network where VCF Management Services is deployed

6. Deploy a new VCF Identity Broker 9.1 from VCF Operations. See Deploy Identity Broker as a Day-N Operation

   Note: Use local user account to log into VCF Operations and use the same FQDN as the 9.0.x VIDB.

7. Run the restore script to import the backed-up configuration into the new 9.1.x instance. This process takes 5 - 30 minutes depending on the size of the configuration.

./restore_and_update_vidb.sh \
     --backup-file <BACKUP_FILE_PATH> \
     --vsp-fleet-fqdn <FLEET_FQDN> \
     --vsp-platform-fqdn <PLATFORM_FQDN> \
     --control-plane-user <vmware-system-user> \ # Optional
     --vsp-platform-user <[e-mail]> \ # Optional
     --vidb-fqdn <VIDB_FQDN> \
     --ops-fqdn <OPS_FQDN> \
     --ops-username <OPS_USERNAME> \ # Optional
     --vidb-cert-file <CERT-FILE-PATH> \
     --vidb-key-file <PRIVATEKEY-FILE-PATH>

    

   Parameters

   Parameter	Required	Description	Default value
   --vsp-fleet-fqdn <fqdn>	Yes*	VSP Fleet LCM FQDN (required only if SKIP_RESTORE=false)
   --control-plane-user <user>	No	VSP Control Plane username (prompted if missing)	vmware-system-user
   --vsp-platform-fqdn <fqdn>	Yes	VSP Service Runtime FQDN
   --vsp-platform-user <user>	No	VSP Service Runtime admin username	[e-mail]
   --vidb-fqdn <fqdn>	Yes	VIDB FQDN
   --ops-fqdn <fqdn>	Yes	VCF Operation FQDN
   --ops-username <user>	No	VCF Operations username	admin
   --backup-file <path>	Yes*	Path to VIDB backup file (required only if SKIP_RESTORE=false)
   --vidb-cert-file <path>	Yes	Path to certificate file for certificate replacement
   --vidb-key-file <path>	Yes	Path to certificate key file for certificate replacement
   --skip-restore	No	Skip database restoration, only do secret rotation & certificate update	false
   -h, --help	No	Show help message

   
   
8. If the existing VCF Identity Broker certificate includes an IP address in the Subject Alternative Name (SAN), you must replace it with a new certificate that contains only the FQDN. See Generate Certificate Signing Requests in VMware Cloud Foundation
9. Verify that all Identity Provider (IDP) integrations, component configurations, permissions, and generic clients are correctly restored, by performing below operations:
   
   
   1. Check Identity Provider Configuration
   2. Check user and group role assignments
   3. Perform SSO login from the VCF Operations & other components

Method 2 - Delete and Redeploy VCF Identity Broker 9.1

If the backup and recovery approach is not feasible, you can remove the existing VCF Identity Broker 9.0.x and deploy a fresh VCF Identity Broker 9.1 in VCF management services. All IAM settings must be reconfigured manually after deployment.

Important: This approach requires you to manually reconfigure all of the following after deployment:

1. Identity Provider (IDP) integration
2. Component configuration for each registered component
3. Permissions for VCF Operations and VCF Automation
4. Any generic OAuth clients that were previously created

Procedure

1. Delete the existing VCF Identity Broker 9.0.x from VCF Operations 9.1 by following the KB - Deletion of Identity Broker from VCF Operations 9.1
   python3 delete_vidb.py \
    --vidb-fqdn <vidb-fqdn> \
    --fleet-fqdn <fleet-lcm-fqdn> \
    --vcf-services-runtime-fqdn <vcf-services-runtime-fqdn> \
    --vcf-services-runtime-username <vcf-services-runtime-username> \ 
    --vcf-operations-fqdn <vcf-operations-fqdn> \
    --vcf-operations-username <vcf-operations-username>



2. Power off the VCF Identity Broker 9.0.x virtual machines from the vSphere Client.
3. Deploy a new VCF Identity Broker 9.1 instance from VCF Operations. See Deploy Identity Broker as a Day-N Operation
   
   Note: Use local user account to log into VCF Operations.
   
   
4. Reconfigure the Identity Provider (IDP) configuration on the new VCF Identity Broker instance.
5. Reconfigure component configuration for all registered components (VC, NSX, VCF Operations, VCF Automation, and any other integrated components).
6. Reconfigure permissions in VCF Operations and VCF Automation for VCF SSO users and groups.
7. Recreate any generic OAuth clients that were previously configured.
8. Validate that authentication and authorization flows are functioning correctly across all integrated components.