How to migrate to a new LDAP backend

This guide outlines the process of migrating the LDAP backend of a Connect2id server with zero downtime. You may want to do this as part of a hardware upgrade, or moving to another LDAP directory implementation.

The Connect2id server persists two types of objects to LDAP storage:

  1. Client registrations (client IDs, secrets and metadata)
  2. Long-lived authorisations (sticky code or implicit grants)

There are two general migration procedures:

1. With direct replication from old to new LDAP backend

Use this procedure if dynamic replication can be set up between the LDAP backend that is about to be deprovisioned and the new LDAP backend. This typically works when migrating between LDAP servers of the same make, e.g. between two OpenLDAP instances. Also for situations when the two LDAP servers support the same sync protocol (rare).

Note that each LDAP backend may actually consist of multiple nodes, for high-availability and load balancing.

  1. Create new LDAP backend.
  2. Set up replication from old to new LDAP backend.
  3. Wait until steady state is reached, i.e. the bulk of the LDAP data has been copied to the new LDAP backend.
  4. Create new Connect2id server nodes pointing to the new LDAP backend. For zero service downtime ensure they join the existing Connect2id server cluster (so that sessions and cached data get carried over). That the newly provisioned Connect2id server nodes point to the new LDAP backend doesn't matter.
  5. Wait until the Infinispan cache objects (sessions, etc) have been replicated to the new Connect2id server nodes.
  6. Redirect the HTTP proxy / load balancer to new Connect2id server nodes. The old Connect2id server nodes will no longer serve requests after this point.
  7. Wait until all LDAP records (client registrations and persisted authorisations) written to the old LDAP backend during the switchover to the Connect2id server nodes have been replicated to the new one.
  8. Shut down the old Connect2id server nodes, one by one.
  9. Shut down the old LDAP backend.

2. Without direct replication

This procedure is intended for situations when replication between the old and the new LDAP backends cannot be established. This is often the case if you're migrating to another LDAP server make.

  1. Create new LDAP backend.
  2. Export the data from the LDAP backend that is about to be deprovisioned to LDIF.
  3. Import the LDIF into the new LDAP backend.
  4. Create new Connect2id server nodes pointing to the new LDAP backend. For zero service downtime ensure they join the existing Connect2id server cluster (so that sessions and cached data get carried over). That the newly provisioned Connect2id server nodes point to the new LDAP backend doesn't matter.
  5. Wait until the Infinispan cache objects (sessions, etc) have been replicated to the new Connect2id server nodes.
  6. Redirect the HTTP proxy / load balancer to new Connect2id server nodes. The old Connect2id server nodes will no longer serve requests after this point.
  7. Shut down the old Connect2id server nodes, one by one.
  8. Export a second LDIF with any LDAP objects that have been added, modified or deleted since the first LDIF export (this is essentially a diff).
  9. Import the second diff LDIF into the new LDAP backend.
  10. Shut down the old LDAP backend.