Migrating Your Jazz Authorization Server From Derby To An Enterprise Database

Authors: DavidNoecker, MirkoHartwig
Build basis: Jazz Authorization Server 6.0.x+
Updated for: Jazz Authorization Server 7.1+

This document describes the procedure for preparing and migrating the Jazz Authentication Server (JAS) database from one database vendor to another.

Prerequisites

• Administrative credentials for all Jazz applications and JAS
• All applications are operational prior to starting the procedure
• Target database (Db2 or Oracle) is available
• Adequate backups are taken for JAS and all Jazz application repositories

Migrating the Jazz Authentication Server (JAS) Database Between Vendors

Step 1: Prepare JAS SSO migration data (applications online)

While all servers are running, generate SSO migration data for each application.
You must start with JTS, followed by all other Jazz applications (for example, CCM, RM, QM).

On the JTS server, run:

./repotools-jts.sh -prepareJsaSsoMigration adminUserId=<your Admin User> adminPassword=<your Admin Password> repositoryURL=https://[public-url]:[port]/jts  toFile=JTS_output.json 

Repeat this step for each additional application using the corresponding repotools-xxx.sh command. Example for CCM:

./repotools-ccm.sh -prepareJsaSsoMigration adminUserId=<your Admin User> adminPassword=<your Admin Password> repositoryURL=https://[public-url]:[port]/ccm toFile=CCM_output.json 

Important: Ensure a .json file is generated for every installed application. Use the correct repotools command for each application.

Step 2: Stop Jazz Authentication Server (JAS)

Shut down the JAS server before changing the database configuration.

Step 3: Configure JAS to use the new database vendor

Update the JAS database configuration to point to the new database vendor by following the appropriate IBM documentation:

• Db2: Setting up a Jazz Authorization Server Db2 database
• Oracle: Setting up a Jazz Authorization Server Oracle database

This includes updating the appConfig.xml file and any required JDBC settings.

Step 4: Start JAS and verify database connectivity

1. Start the JAS server.
2. Verify that JAS can connect to the new database by accessing the following URL:

https://<jas-host>:<port>/oidc/endpoint/jazzop/registration

A response similar to { "data": [] } indicates that JAS is running and connected successfully to the new database.

Step 5: Stop all Jazz applications

Stop all Jazz applications (JTS, CCM, RM, QM, and others).
Note: Applications must be offline to run the migration commands.

Step 6: Migrate SSO data to the new JAS database

Migrate SSO data. Start with JTS, and run:

 ./repotools-jts.sh -migrateToJsaSso authServerUrl=https://[jas-url]:9643/oidc/endpoint/jazzop authServerUserId=<your Admin User> authServerPassword=<your Admin Password> 
jtsSsoDataFile=JTS_output.json 

Migrate each remaining application. Example for CCM:

./repotools-ccm.sh -migrateToJsaSso authServerUrl=https://[jas-url]:9643/oidc/endpoint/jazzop authServerUserId=<your Admin User> authServerPassword=<your Admin Password> 
jtsSsoDataFile=JTS_output.json appSsoDataFile=CCM_output.json

Step 7: Restart all applications

Start all servers, beginning with JTS, followed by the remaining Jazz applications.

Step 8: Validate application availability

Verify that all applications start successfully and that users can authenticate through JAS.

Step 9: Re-register LQE, LDX, and Report Builder (if required)

After migration, Lifecycle Query Engine (LQE), Lifecycle Query Engine Data Index (LDX), and Report Builder (JRS) may not be available for SSO. To enable JAS SSO for these applications, unregister and re-register them in JTS:

• LQE: Enabling Lifecycle Query Engine for Jazz Security Architecture single sign-on
• Report Builder: Enabling Report Builder for Jazz Security Architecture single sign-on

Note for Report Builder SSO a following steps may be needed:

1. Shut down JTS

2. Edit server.startup file on JTS:

- Linux: add

"JAVA_OPTS="$JAVA_OPTS -Dcom.ibm.team.forceRegisterApp.enabled=true"" 

- Windows: add

 "set JAVA_OPTS=%JAVA_OPTS% -Dcom.ibm.team.forceRegisterApp.enabled=true" 

3. Save changes

4. Restart JTS and register RS again

For now, this procedure has been tested internally and at multiple client sites. Also see: Defect 463705: Documentation on Jazz Authorization Server DB configuration missing in Knowledge Centre.

Related topics: Deploying and starting Jazz Authorization Server, Setting up a cluster of Jazz Authorization Servers

External links:

• IBM

Additional contributors: ShubjitNaik, PaulEllis, TobiasBurkhardt