Data migration

This guide outlines a safe strategy for migrating Connect2id server data between two instances using the available server web APIs.

The target Connect2id server version must be v6.6 or newer. Earlier Connect2id server versions have API support for importing data that is limited to client registrations only.

This strategy can also be used to migrate data from a Connect2id server version 5.x (or older) to v6.6+.

Step 1. Copy JWK set

Copy the JWK set file from the source to the target Connect2id server, and all other configuration files where applicable.

To perform the next steps both source and target Connect2id server must be up and running.

Step 2. Migrate client registrations

The registrations of the clients is the most important piece of data. Without that clients won’t be able to use the Connect2id server at all, and must be registered again.

Export all existing client registrations from the source Connect2id server with an HTTP request like this:

GET /clients HTTP/1.1
Host: source.c2id.com
Authorization: Bearer SQvs1wv1NcAgsZomWWif0d9SDO0GKHYrUN6YR0ocmN0

The Connect2id server will return a JSON array of the registered clients.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

[
  { "client_id" : "s6BhdRkqt3", ... },
  { "client_id" : "joaix93Kf4", ... },
  ...
]

Post each client registration to the target Connect2id server. Use the preferred_client_id and preferred_client_secret parameters to force the Connect2id server to not provision new client credentials (the default behaviour), and use the provided values instead.

Example request:

POST /c2id/clients HTTP/1.1
Host: target.c2id.com
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "preferred_client_id"     : "123456",
  "preferred_client_secret" : "ahL7AhthchiNg6beAo5HeijeThae3deiChab7ajiVuip2eodesoBie0ufohtiiK4",
  ...
}

Step 3. Migrate authorisation records

The next step is to migrate the existing long-lived (persisted) authorisations. Without that all refresh tokens that were issued to clients will become invalid and users with remembered consent will need to authorise their apps again.

Export all long-lived authorisations from the source Connect2id server:

GET /authz-store/rest/v2/authorizations HTTP/1.1
Host: source.c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

The Connect2id server will return a JSON array of the long-lived authorisations. Note that with a large user base this can be a potentially time-consuming operation.

HTTP/1.1 200 OK
Content-Type: application/json

[
  { ... },
  { ... },
  ...
]

Recreate each authorisation on the target Connect2id server.

Example request:

POST /authz-store/rest/v2/authorizations?import=true HTTP/1.1
Host: target.c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub": "alice",
  "cid": "123",
  ...
}

Step 4. Migrate end-user sessions

The final step is the migration of the subject (end-user) sessions with the IdP. If that step is skipped all session cookies will become invalid and all users will be forced to authenticate on the next visit to the login page.

Export all sessions from the source Connect2id server:

GET /session-store/rest/v2/sessions HTTP/1.1
Host: source.c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

The Connect2id server will return a JSON object of all sessions keyed by their session identifier (SID). Note that this can be a potentially time-consuming operation.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "cg62csZGqGufdeth1eK1HlFqWKkVRmP3YBT5cTl7s0" : { ... },
  "juM8ubaijo8hahPhUQuai7yeli9thaiRgeNee6rose" : { ... },
  ...
}

Recreate each session on the target Connect2id server.

If the source Connect2id server is v5 or older use the Legacy-SID header parameter to explicitly specify the identifier of the posted session. The target Connect2id server must also be configured to accept legacy SIDs, i.e. SIDs without HMAC protection.

POST /session-store/rest/v2/sessions HTTP/1.1
Host: target.c2id.com
Legacy-SID: cg62csZGqGufdeth1eK1Hl
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub"  : "alice",
  ...
}

If the source Connect2id server is v6 or newer use the SID-Key header parameter to specify the identifier of the posted session. The SID-Key value is obtained by stripping the appended HMAC from the exported SID (delimited with a dot . character). The target Connect2id server will recompute the exact same SID HMAC provided it has been provisioned with the identical HMAC key.

POST /session-store/rest/v2/sessions HTTP/1.1
Host: target.c2id.com
SID-Key: cg62csZGqGufdeth1eK1Hl
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json

{
  "sub"  : "alice",
  ...
}