github
/
OpenID-Connect-Java-Spring-Server
mirror of https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated Upgrading 1.0 to 1.1 (markdown)

master
jricher 2014-10-07 19:54:28 -07:00
parent a085ba43fe
commit e68fb7d1d5
1 changed files with 25 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
Upgrading-1.0-to-1.1.md

@ -1,4 +1,4 @@
The **1.1** version of MITREid Connect contains several changes from the **1.0** version series that will require a manual upgrade process. There is not currently any automated upgrade process, though one is being developed. The **1.1** version of MITREid Connect contains several changes from the **1.0** version series that will require a manual upgrade process.
## Project Layout ## Project Layout
@ -6,25 +6,39 @@ The project now contains four modules instead of three. The `openid-connect-serv
## Data Model ## Data Model
The underlying data model has changed between 1.0 and 1.1, and updates to the database are required. The underlying data model has changed between 1.0 and 1.1, and updates to the database are required. Two methods are available for managing this update with different tradeoffs.
If you are running the server with a persistent database store, you will need to run the database upgrade script found in [openid-connect-server-webapp/src/main/resources/db/upgrade](https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server/tree/master/openid-connect-server-webapp/src/main/resources/db/upgrade). Upgrade scripts are included for both MySQL and HSQL databases. These are designed to be run in-place on the database in question. The safest process is as follows: **Existing data**
Due to an upstream library change, existing authorizations are incompatible between 1.0 and 1.1 and must be revoked before upgrade. Otherwise, all authorization grants, clients, whitelists, blacklists, and scopes may remain in place following the instructions above.
### Database Update Scripts
The database update method can be used to update a persistent database store in place. To do so, run the database upgrade script found in [openid-connect-server-webapp/src/main/resources/db/upgrade](https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server/tree/master/openid-connect-server-webapp/src/main/resources/db/upgrade). Upgrade scripts are included for both MySQL and HSQL databases. These are designed to be run in-place on the database in question.
The recommended process is as follows:
1. Shut down the version 1.0 server 1. Shut down the version 1.0 server
1. Connect to the MySQL or HSQL database as a user with appropriate rights 1. Connect to the MySQL or HSQL database as a user with appropriate rights
1. Run the appropriate upgrade script 1. Run the appropriate upgrade script
1. Deploy the version 1.1 server 1. Deploy the version 1.1 server
## Existing data ### Data Import/Export
Due to an upstream library change, existing authorizations are incompatible between 1.0 and 1.1. This effectively means that **all active access tokens must be revoked** (or translated using some form of external process) during the upgrade process. Note that this includes any **Registration Access Tokens** used for dynamically registered clients. As of version **1.0.17** and **1.1.10**, there is an admin-accessible API that can export data from a running system and import data from a saved export. The **1.0** server can import and export data from other **1.0** servers, and the **1.1** server can import and export data from both **1.0** and **1.1** servers. This process is meant to be run on a clean server installation, and it does not involve loss of any database information.
Otherwise, all authorization grants, clients, whitelists, blacklists, and scopes may remain in place following the instructions above. 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.
## Data Import/Export
As of version **1.0.17**, there is an admin-accessible API that can export data from a running system. 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.
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. 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.
A version of the import/export API is currently in the works for the 1.1 branch, which will allow for import of 1.0 data into the 1.1 database. The recommended process is as follows:
1. Log into the 1.0 server as an administrator
1. Export the server state by performing a `GET` request on `/api/data`, save as a JSON file
1. Shut down the 1.0 server
1. Connect to the MySQL or HSQL database as a user with appropriate rights
1. Clear the database, remove all tables related to OIDC
1. Initialize the database with the empty schema
1. Deploy the version 1.1 server
1. Log into the 1.1 server as an administrator
1. Import the server state from the saved JSON file by performing a `POST` request with the data