Fix #137: Error in after.sql (#140)

* Fix #137: Error in after.sql * Use the original table names from 1.1.0 * mobile_app * mobile_ssl_pinning * Describe manual import Co-authored-by: Zdeněk Černý <[email protected]> * Creating First Admin User * Split migration and cleanup script --------- Co-authored-by: Zdeněk Černý <[email protected]>
wultra · Oct 18, 2023 · fa59987 · fa59987
1 parent 2bbfe64
commit fa59987
Show file tree

Hide file tree

Showing 8 changed files with 121 additions and 81 deletions.
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -2,6 +2,67 @@
 
 Several administrative tasks should be performed regularly while working with Mobile Utility Server to keep the published content up-to-date.
 
+
+## Network
+
+The context path `/admin` for administrative purposes is authenticated, but it should be exposed only in trusted networks.
+
+
+## Creating First Admin User
+
+When calling admin APIs provided by the Mobile Utility Server, basic HTTP authentication is required.
+This why we need to add users and their passwords in the database.
+
+The first user we need to add is basically the main admin user, let's call the user `system-admin`.
+The first user needs to be inserted in the database.
+
+First, we need to generate the password via `openssl`:
+
+```sh
+openssl rand -base64 12
+```
+
+Output will look like this:
+
+```
+DH4v3SCoDRDUAFBD
+```
+
+In order to store the password in the database, we need to encode it using `bcrypt` first.
+You can use the `htpasswd` command to achieve this:
+
+```sh
+htpasswd -bnBC 12 "" DH4v3SCoDRDUAFBD | tr -d ':'
+```
+
+Output will look like this:
+
+```
+$2y$12$GM/J9uvNy1W.eSy1mB2HB.xk2uLYtnjcD3rUEkqPkVCL43b0F9xa.
+```
+
+You can now put this all together and store the user in the database:
+
+```sql
+INSERT INTO mus_user (id, username, password, enabled)
+VALUES (nextval('mus_user_seq'), 'system-admin', '$2y$12$GM/J9uvNy1W.eSy1mB2HB.xk2uLYtnjcD3rUEkqPkVCL43b0F9xa.', true);
+
+INSERT INTO mus_user_authority (id, user_id, authority)
+VALUES (nextval('mus_user_authority_seq'), (SELECT id FROM mus_user WHERE username = 'system-admin'), 'ROLE_ADMIN');
+```
+
+- We stored the hashed password for the `system-admin` user.
+- We used authority `ROLE_ADMIN` for the administrator user who can call services published under `/admin` context.
+  Regular users who only need to call registration and operation APIs can use a restricted `ROLE_USER` authority.
+
+You can now check the changes in the database:
+
+- `mus_user` - New user record with the bcrypt-hashed password.
+- `mus_user_authority` - New user authority record.
+
+At this point, you can open [http://localhost:8080/admin/apps](http://localhost:8080/admin/apps) and use `system-admin` as username and `DH4v3SCoDRDUAFBD`, your password value respectively (plaintext) as the password.
+
+
 ## Adding New Mobile Application
 
 You can easily add a new mobile application by running the following API call:

diff --git a/docs/Mobile-Utility-Server-1.5.0.md b/docs/Mobile-Utility-Server-1.5.0.md
@@ -1,7 +1,7 @@
-# Migration from 1.x.x to 1.5.x
+# Migration from 1.1.x to 1.5.0
+
+This guide provides step-by-step instructions for migrating from PowerAuth Mobile Utility Server version 1.1.x to version 1.5.0.
 
-This guide provides step-by-step instructions for migrating from PowerAuth Mobile Utility Server version 1.x.x to
-version 1.5.x.
 
 ## Prerequisites
 
@@ -11,35 +11,41 @@ version 1.5.x.
     - Oracle: `${repo_root}/docs/sql/oracle`
     - PostgreSQL: `${repo_root}/docs/sql/postgresql`
 
-
 2. **Docker DB Update Script**: Before running the script `docker-db-update.sh`, ensure that you have set up the
    required environment variables. For a list of the required environment variables or additional details, refer to the
    associated documentation [Deployment.md](Deployment.md).
 
+
 ## Migration Steps
 
 1. **Stop the Application**: Ensure that the PowerAuth Mobile Utility Server application is not running. Shut it down if
    it's currently active.
 
-
 2. **Backup the Database**: Before making any changes, it's crucial to **back up your database**. This step ensures you have
    a fallback in case of any unforeseen issues.
 
    > **IMPORTANT**: Ensure that you've backed up your entire database before proceeding
 
+3. **Run Liquibase update**:  Execute [liquibase](https://www.liquibase.com/download) scripts located in `docs\db\changelog\db.changelog-master` 
+- For convenience, you can use supplied Dockerfiles and apply the database changes by execute the `docker-db-update.sh` script. 
+- If direct update via Liquibase is not possible `liquibase update` command can generate required SQL script.
 
-3. **Run Liquibase update**:  Execute [liquibase](https://www.liquibase.com/download) scripts located in `docs\db\changelog\db.changelog-master` For convenience, you can use supplied Dockerfiles and apply the database changes by execute the `docker-db-update.sh` script.
    Please take a look at a list of necessary environmental variables listed
    here [env.list.tmp](../deploy/env.list.tmp).
 
-
-4. **Execute Migration Script**: After applying the Liquibase changes, run the `1.5.x-migration.sql` script
-   located in the sql directory.
-
+4. **Execute Migration Script**: After applying the Liquibase changes, run the `1.5.0-migration.sql` script located in the sql directory.
 
 5. **Start the PowerAuth MUS Application**: Once all the database changes are successfully applied, restart the
    PowerAuth Mobile Utility Server application.
 
+6. **Import Certificates**: Certificates are not possible to migrate automatically.
+It is needed to [Importing Certificate in PEM Format](Configuration.md#importing-certificate-in-pem-format) via API. See [Creating First Admin User](Configuration.md#creating-first-admin-user).
+
+7. **Test Certificate Pinning**: Test that the functionality certificate pinning is working.
+
+8. **Execute Cleanup Script**: When you are sure that the application is working, run the `1.5.0-cleanup.sql` script located in the sql directory.
+
+
 ## Database Changes - detailed description of changes above
 
 The steps detailed above have taken care of migrating the database structure. The following is an overview of the major
@@ -55,53 +61,35 @@ The migration involves transferring data from old tables to new ones. Post data
 -- TABLES
 
 -- For table mobile_app
-INSERT INTO mus_mobile_app SELECT * FROM ssl_mobile_app;
-
--- For table mobile_app_version
-INSERT INTO mus_mobile_app_version SELECT * FROM ssl_mobile_app_version;
+INSERT INTO mus_mobile_app SELECT * FROM mobile_app;
 
--- For table mobile_domain
-INSERT INTO mus_mobile_domain SELECT * FROM ssl_mobile_domain;
-
--- For table user
-INSERT INTO mus_user SELECT * FROM ssl_user;
-
--- For table user_authority
-INSERT INTO mus_user_authority SELECT * FROM ssl_user_authority;
-
--- For table certificate
-INSERT INTO mus_certificate SELECT * FROM ssl_certificate;
-
--- For table localized_text
-INSERT INTO mus_localized_text SELECT * FROM ssl_localized_text;
+-- There is no migration for table certificate
 ```
 
+
 ### Removal of Deprecated Tables and Sequences
 
 After the data migration is successfully completed, the old tables and their associated sequences, which are no longer
 in use, have been removed.
 
 ```sql
 -- Drop old tables
-DROP TABLE ssl_certificate CASCADE;
-DROP TABLE ssl_localized_text CASCADE;
-DROP TABLE ssl_mobile_app CASCADE;
-DROP TABLE ssl_mobile_app_version CASCADE;
-DROP TABLE ssl_mobile_domain CASCADE;
-DROP TABLE ssl_user CASCADE;
-DROP TABLE ssl_user_authority CASCADE;
+DROP TABLE mobile_ssl_pinning CASCADE;
+DROP TABLE mobile_app CASCADE;
 
 -- Drop old sequences
-DROP SEQUENCE ssl_certificate_seq CASCADE;
-DROP SEQUENCE ssl_mobile_app_seq CASCADE;
-DROP SEQUENCE ssl_mobile_app_version_seq CASCADE;
-DROP SEQUENCE ssl_mobile_domain_seq CASCADE;
-DROP SEQUENCE ssl_user_authority_seq CASCADE;
-DROP SEQUENCE ssl_user_seq CASCADE;
-
+DROP SEQUENCE mobile_ssl_pinning_seq CASCADE;
+DROP SEQUENCE mobile_app_seq CASCADE;
 ```
 
+
 ### Conclusion
 
-Upon successfully executing the provided SQL commands and scripts, the migration process is complete. Ensure to verify
-and test the updated database to confirm the successful migration from version 1.x.x to 1.5.x.
+Upon successfully executing the provided SQL commands and scripts, the migration process is complete.
+Ensure to verify and test the updated database to confirm the successful migration from version 1.1.0 to 1.5.0.
+
+
+## API
+
+There is a new context path `/admin` for administrative purposes.
+It is authenticated, but it should be exposed only in trusted networks.
diff --git a/docs/sql/oracle/1.5.0-cleanup.sql b/docs/sql/oracle/1.5.0-cleanup.sql
@@ -0,0 +1,7 @@
+-- Drop old tables
+DROP TABLE mobile_ssl_pinning CASCADE CONSTRAINTS;
+DROP TABLE mobile_app CASCADE CONSTRAINTS;
+
+-- Drop old sequences
+DROP SEQUENCE mobile_ssl_pinning_seq;
+DROP SEQUENCE mobile_app_seq;
diff --git a/docs/sql/oracle/1.5.0-migration.sql b/docs/sql/oracle/1.5.0-migration.sql
@@ -0,0 +1,7 @@
+-- Migrate data
+-- TABLES
+
+-- For table mobile_app
+INSERT INTO mus_mobile_app SELECT * FROM mobile_app;
+
+-- There is no migration for table certificate
diff --git a/docs/sql/oracle/1.5.x-migration.sql b/docs/sql/oracle/1.5.x-migration.sql
diff --git a/docs/sql/postgresql/1.5.0-cleanup.sql b/docs/sql/postgresql/1.5.0-cleanup.sql
@@ -0,0 +1,7 @@
+-- Drop old tables
+DROP TABLE mobile_ssl_pinning CASCADE;
+DROP TABLE mobile_app CASCADE;
+
+-- Drop old sequences
+DROP SEQUENCE mobile_ssl_pinning_seq CASCADE;
+DROP SEQUENCE mobile_app_seq CASCADE;
diff --git a/docs/sql/postgresql/1.5.0-migration.sql b/docs/sql/postgresql/1.5.0-migration.sql
@@ -0,0 +1,7 @@
+-- Migrate data
+-- TABLES
+
+-- For table mobile_app
+INSERT INTO mus_mobile_app SELECT * FROM mobile_app;
+
+-- There is no migration for table certificate
diff --git a/docs/sql/postgresql/1.5.x-migration.sql b/docs/sql/postgresql/1.5.x-migration.sql