diff --git a/docs/Configuration.md b/docs/Configuration.md index 1e1ef8e1..4b567933 100644 --- 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 index 8777ac8d..3ab0cc56 100644 --- 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,27 +61,12 @@ 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 @@ -83,25 +74,22 @@ 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. \ No newline at end of file +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 new file mode 100644 index 00000000..c39aca85 --- /dev/null +++ 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 new file mode 100644 index 00000000..b450a12e --- /dev/null +++ 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 deleted file mode 100644 index f1ad7c03..00000000 --- a/docs/sql/oracle/1.5.x-migration.sql +++ /dev/null @@ -1,19 +0,0 @@ --- Migrate data --- TABLES - --- For table mobile_app -INSERT INTO mus_mobile_app SELECT * FROM ssl_mobile_app; - --- For table certificate -INSERT INTO mus_certificate SELECT * FROM ssl_certificate; - - - --- Drop old tables -DROP TABLE ssl_certificate CASCADE CONSTRAINTS; -DROP TABLE ssl_mobile_app CASCADE CONSTRAINTS; - --- Drop old sequences -DROP SEQUENCE ssl_certificate_seq; -DROP SEQUENCE ssl_mobile_app_seq; - diff --git a/docs/sql/postgresql/1.5.0-cleanup.sql b/docs/sql/postgresql/1.5.0-cleanup.sql new file mode 100644 index 00000000..4ed48c54 --- /dev/null +++ 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 new file mode 100644 index 00000000..b450a12e --- /dev/null +++ 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 deleted file mode 100644 index 025435b6..00000000 --- a/docs/sql/postgresql/1.5.x-migration.sql +++ /dev/null @@ -1,18 +0,0 @@ --- Migrate data --- TABLES - --- For table mobile_app -INSERT INTO mus_mobile_app SELECT * FROM ssl_mobile_app; - --- For table certificate -INSERT INTO mus_certificate SELECT * FROM ssl_certificate; - - - --- Drop old tables -DROP TABLE ssl_certificate CASCADE; -DROP TABLE ssl_mobile_app CASCADE; - --- Drop old sequences -DROP SEQUENCE ssl_certificate_seq CASCADE; -DROP SEQUENCE ssl_mobile_app_seq CASCADE;