Upgrading

MITREid Connect strives to keep data schemas and most major dependencies steady within a release stream. Upgrades within a stream can usually be accomplished by simply replacing the component with its new version.

Spring Versions

The Spring and Spring security version dependencies often change between version streams. This necessitates changes to the schema references for any configuration files. See the default configuration files in the main project for examples of the proper references.

Data Model

The underlying data model changes between version streams, and updates to the database are required. As such, existing data must be exported and re-imported during an upgrade if it is desired to be retained. There are no supported means for modifying the database directly.

Data Import/Export

MITREid Connect's data API can be used to support backup/restore and upgrades. Each version stream of MITREid Connect can import data exports from previous versions, but not from future versions. For example, a 1.3 server can import data from 1.2 or 1.1, but 1.2 can't import from 1.3.

To access this API, log in as an administrator and send a GET request to /api/data to return the JSON object representing the server's current state. NOTE WELL: this export includes information including tokens, authentication objects, client secrets, and other sensitive security information. Therefore, the data export must be protected.

To re-import this data, log in as an administrator on a newly-installed server and send a POST request to /api/data with a content type of application/json and the fully-formed JSON document exported from the API. This import MUST be done on an empty database with full schema or else you risk newly imported objects conflicting with existing objects.

The recommended process is as follows:

1. Log into the old server as an administrator
2. Export the server state by performing a GET request on /api/data, save as a JSON file
3. Shut down the old server
4. Connect to the MySQL or HSQL database as a user with appropriate rights
5. Clear the database, remove all tables related to OIDC
6. Initialize the database with the empty schema
7. Deploy the version new server
8. Log into the new server as an administrator
9. Import the server state from the saved JSON file by performing a POST request to /api/data with the data exported