8 Installing SPMS Rest API/Web Application Server

Prerequisites

  • The Time zone on both the Web application server and API server must be the same. It is recommended that you use the database server time zone.

  • The SPMS Database must be on version 20.2. If you are running a previous version, upgrade the database to 20.2 before continuing.

  • The Web application server and API server do not require IIS.

  • Java JDK version 11.0.7 installation is required.

  • A tool for manipulating certificates. As an example, this document uses OpenSSL. Other tools are available. We recommend you to select a tool that suits your security requirements. Whichever tool you use, ensure that it is virus scanned and virus-free, up to date, and patch with the latest security fixes. Otherwise, you could compromise your environment.

  • The API and Web application access uses a Secure Socket Layer and Transport Layer Security (SSL/TSL) cryptographic protocol. You must set up a keystore (.jks format) that contains the private key and certificate.

  • The keystore must have the default option value as:“-alias server -keyalg RSA -keysize 2048”

  • The minimum PowerShell version required is 5.1.

  • A public (.txt file) and private key (.jks format) for setting up secure OAUTH. As an example, this document explains how OpenSSL is used to generate a public and private key

  • Ensure that the 'Path' in the 'System Variable' (Environment variable) is entered like the following example: '%SYSTEMROOT%\System32\WindowsPowerShell\v1.0\'.

Preparing the Java Environment

Before you install the SPMS Version 20.2 API/Apps server, do the following:

  1. Ensure the JDK is installed.

  2. Ensure that you have a tool for manipulating certificates installed.

Set JAVA_HOME or JRE_HOME variable

  1. Search Environment Variables in the search box (next to the Windows start button) then select Edit to edit the system environment variable.

  2. Click the Environment Variables button.

  3. Under System Variables, click New.

  4. In the Variable Name field, enter either of the following:

    • JAVA_HOME if you have the JDK (Java Development Kit) installed

    • JRE_HOME if you have the JRE (Java Runtime Environment) installed.

  5. Browse the Directory and select “C:\Program Files\Java\[java version]”

  6. Click OK to apply the changes.

Set JAVA Path

  1. Search Environment Variables then select Edit to edit the system environment variable.

  2. Click the Environment Variables button.

  3. Find the ‘Path’ from the System Variable and click Edit then select New.

  4. Browse directory “C:\Program Files\Java\[java version]\bin”

  5. Click OK to apply the changes.

Installation Process

Installation is a three-step process, where

  • Step 1: Create a Java keystore containing certificates purchased from a reputable Certificate Authority

  • Step 2: Generate security keys for OAuth

  • Step 3: Install the software

Step 1: Create the Java Keystore for SPMS API/Apps Server

Background

Java Keystore is required to store private keys and certificates used by the SPMS Version 20.2 API/Apps server. Java’s Keytool is used to create a Java Keystore. Java’s Keytool is distributed as part of the Java JDK. Java Keystore files can be generated on any machine. They need not be on the same server where the SSL/TLS certificate will be installed.

Important: In this section, we use OpenSSL to demonstrate the process. You should select a certification manipulation tool that meets your organization’s security policy.

Recommendations

It is recommended that you generate a new Keystore following the process outlined in this section. Installing a new certificate to an existing Keystore often ends in installation errors or the SSL/TLS certificate not working properly. Before you begin this process, backup and remove any old Keystores.

The act of generating a self-signed Digital Certificate to identify the SPMS API/Apps Server is not recommended for the production environment. It increases the risk of an unscrupulous party impersonating the SPMS API/Apps to steal sensitive information. However, for limited, non- production testing of SPMS API/Apps, you could use a self-signed certificate despite the increased security risk. However, do so at your own risk: this is not recommended.

Generate a new Java Keystore using Java Keytool

  1. Navigate to the directory where you plan to manage your Keystore and SSL/TLS certificates.

  2. Run the following command:

    keytool -genkey -alias server -keyalg RSA -keysize 2048 -keystore <SITE_NAME>.jks –ext SAN=dns:<SITE_NAME>

  3. In the command above, <SITE_NAME> is the name of the domain you want to secure with the SSL/TLS certificate. When using a Domain wildcard certificate, do not include the asterisk (*) character in the SITE_NAME as the asterisk (*) character is not a valid Keytool command character. The command will generate the Keystore with the public and private key pair and a self-signed certificate for the server.

  4. After that, you will be prompted to create a password for the new Keystore.

  5. Now, enter the SSL/TLS certificate information for the self-signed certificate.

    1. When prompted for the first and last name, enter the Fully Qualified Domain Name (FQDN) for the site you wish to secure with the SSL/TLS certificate. For example, www.yourdomain.com or mail.yourdomain.com. If the SSL/TLS certificate is a Domain wildcard type, the FQDN is *.yourdomain.com.

    2. Enter the Common Name (CN), for example, The FQDN.

    3. Enter the Organizational Unit (OU), for example, Cruise Operation

    4. Enter the Organization (O), for example, Cruise Company

    5. Enter the Locality (L). E.g. Redwood City

    6. Enter the State or Province Name (S), for example, California

    7. Enter the Country Name (C), for example. US

    8. After that, you will be prompted to verify all the information entered. Type ‘y’ or ‘yes’ to confirm.

    9. Finally, you will be asked to enter the Keystore password. The new Keystore file <SITE_NAME>.jks is now available in the current working directory.

Generate a Certificate Signing Request (CSR) using Java Keytool

  1. Navigate to the directory where the Keystore was generated earlier.

  2. Run the following command:

    keytool -certreq -alias server -file csr.txt -keystore <SITE_NAME>.jks –ext SAN=dns:<SITE_NAME>

  3. In the command above, <SITE_NAME> is the name of the Keystore generated in earlier section. The CSR will manifest itself as an output file based on the Certificate Info you entered earlier. You will also need to enter the Keystore password to proceed.

  4. The CSR output file is located in the same current working directory, for example, <SITE_NAME>.txt.

Backing Up the Keystore

Save and back up the Keystore file to a safe, secure location.

Importing SSL/TLS Certificate to the Keystore

After receiving your SSL/TLS certificate from Certificate Admin, you must import the SSL/TLS Certificate file to the same Java Keystore under the same alias name (for example, alias server) used to generate your CSR. If you try to install the certificate to a different keystore or under a different alias, the import command will not work.

  1. Navigate to the directory where the Keystore was generated earlier.

  2. Run this command:

    keytool -import -alias server -file <CERT_NAME>.p7b -<SITE_NAME>.jks

  3. In the command above, <CERT_NAME> is the name of the SSL/TLS Certificate. <SITE_NAME> is the name of the Keystore generated in earlier section.

  4. You will get a confirmation message that displays “Certificate reply was installed in keystore.” Type ‘y’ or ‘yes’ to proceed.

  5. This will load all the necessary Certificates to the Keystore.

  6. The Keystore is now ready to be used by the Tomcat/Tomcat Embedded Server.

Step 2: Create the Key Pair for SPMS API Authentication

Background

OAuth 2.0 is the user authorization mechanism used by SPMS API. It requires a generation of an asymmetric key pair to work. The asymmetric key pair is used to securely sign and read contents found in the Security token. Security of the API relies on the security token. API calls made without a valid Security token will be rejected. In detail, the security token contains a checksum. This checksum ensures that the token is not tampered with. The checksum is calculated by adding up the bytes in the security token and is signed by the private key. A third party can check the validity of a token by recalculating the checksum, decrypting the original checksum with the public key, and comparing the two. Any differences between the two checksums indicate that the token has been tampered with.

Note:

We provide the process below as an example. You can use other certificate manipulation tools to generate the public and private keys. Whichever tool you use, ensure that you download them from a reliable source and that the downloaded tool is security checked, virus scanned, and checksum checked. Without such due diligence, you may compromise the security of your installation.

Generating a new Key Pair using Java Keytool & OpenSSL

  1. Navigate to the directory where you plan to manage your Keystore.

  2. Run the following command:

    keytool -genkeypair -alias spms -keyalg RSA -keypass <YOUR_PASSWORD> -keystore oauth-private-key.jks -storepass <YOUR_PASSWORD>

  3. You will be prompted to key in the Certificate info. Enter all the questions required and enter ‘yes’ to confirm the provided information is correct.

    1. What is your first and last name?

      • [Unknown]: <user's name>

    2. What is the name of your organizational unit?

      • [Unknown]: <department name>

    3. What is the name of your organization?

      • [Unknown]: <company name>

    4. What is the name of your City or Locality?

      • [Unknown]: <city name>

    5. What is the name of your State or Province?

      • [Unknown]: <state name>

    6. What is the two-letter country code for this unit?

      • [Unknown]: <country name>

    7. Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?[no]: yes

  4. Run the following command to generate the public key to a file.

    keytool -list -rfc --keystore oauth-private-key.jks | openssl x509 -inform pem -pubkey -noout > oauth-public-key.txt

  5. Backup the public key file (.txt), private key file (.jks), and the password safely.

Step 3: Install Cruise Property Management

You can perform a custom installation or a typical installation. A custom installation allows you to exclude the products that you do not need. If you select to perform a typical installation, manually remove or disable the features that you do not need after the installation. Note that if one of the older versions is already installed, the Setup silently uninstall the previous version before installing 20.2.

The installation requires the user performing the installation to have Administrator privileges.

Installing Cruise Property Management 20.2

  1. Log in as a Microsoft Windows Administrative user.

  2. Start the installation program by right-clicking the Cruise Property Management 20.2.exe and selecting Run as Administrator.

    Figure 8-1 Cruise Property Management Installation Wizard Welcome Page


    This figure shows the SPMS Platform Property Management Installation Wizard Welcome page.

  3. Click Next and navigate to the Custom Setup window. If you want to perform a custom installation, select the option to set the feature as “This feature will not be available.”

    Figure 8-2 Cruise Property Management Installation - Custom Setup


    This figure shows the Cruise Property Management Installation - Custom Setup.
  4. Click Next to update the settings window for the fields below:

    1. Database connection String: <DBMachineName>:<DBPort>/<SID>

    2. Database User: DB username.

    3. Database Password: DB Password.

    4. Database Keystore: DB Keystore password for database encryption. Minimum password’s length is eight characters.

    5. API URL: API Server’s URL.

    6. API Port: API Server’s port. If you need to install multiple instances of the API’s, enter the ports in comma separated format. By default the Install Shield populates ports 7443, 8443. Ensure the ports populated are available for successful installation. Refer to Cross Origin Resources Sharing (CORS) policy to support secure cross-origin requests.

    7. Allow All APP Servers: Server machines with APP installed that are allowed to access the API,* meaning all the servers are allowed.

    8. Keystore File Path: Keystore file path that contains .JKS file extension.

    9. Keystore password: Keystore’s password.

    10. Mobility App Port: Mobility App port. If you need to install multiple instances of Mobility App, enter the ports in comma separated format. By default Install Shield populates ports 7090, 8090. If these ports are unavailable, you need to select an unused port for the installation.

    11. Administration App Port: Administration App’s port. If you need to install multiple instances of Mobility App, enter the ports in comma separated format. By default, Install Shield populates port 24001, 24002. If these ports are unavailable, you need to select an unused port for the installation.

    Figure 8-3 Cruise Property Management Installation - Database Settings


    This figure shows the Cruise Property Management Installation - Database Settings

  5. When the Allow All APP Servers check box is selected, the message box above appears, alerting you of the chosen option.

    Figure 8-4 Allow All APP Servers Notification


    This figure shows the Allow All APP Servers Notification prompt
  6. Click Next to update the OAuth Configuration settings for the following fields:

    1. OAuth Public Key File: OAuth public key file in .txt format.

    2. OAuth Private Key File: OAuth private key file in jks format.

    3. Password: Password required for OAuth Private Key file.

  7. Click Next to update the OPI Configuration settings.

    1. Enable OPI: Use the check box to enable or disable OPI Integration.

    2. OPI Socket Port: The port on which OPI connects to the SPMS client.

    3. OPI Key: OPI Key used in the secure communication between SPMS clients and OPI.

    4. OPI Date Mask: Date format used in the processing of the date.

    5. OPI Time Mask: Time format used in the processing of the time.

    6. OPI EFT Timeout: The amount of time SPMS clients wait for the response from the OPI.

    7. OPI Merchant ID: Merchant ID configured in the OPI.

  8. Click Next to update the Passport Scanner settings.

    1. Enable Passport Scanner: Use the checkbox to enable or disable Passport Scanner integration.

    2. Hardware ID: Hardware ID configured at the Passport Scanner side.

    3. Register Url: Url to register with Passport Scanner for access token retrieval.

    4. ProcessImage API Url: Image processing API URL.

    5. AccountId: AccountId configured on the Passport Scanner side.

    6. Access Secret: Secret key used to secure the communication with the Passport Scanner.

    7. Access Secret Keystore: Used to encrypt the Access Secret.

    8. API Key: Key configured in Passport Scanner application.

    9. Proxy Host: Proxy Host if a Proxy server is used.

    10. Proxy Port: Proxy Port if a Proxy server is used for the traffic.

  9. Click Install to begin installation.

    Figure 8-5 Cruise Property Management Ready Install


    This figure shows SPMS Platform Property Management Ready Install.

    Note:

    For a better end user experience, at the end of the installation a config.txt file containing all the configurations, excluding the passwords is created and added to folder UserProfle/AppData/Local/Oracle Hospitality Cruise. This file is reloaded upon upgrade/re-install, so that end user does not have to re-enter the configuration.

  10. During the install, a couple of PowerShell windows will launch and close automatically.

  11. At the end of the installation, the system creates three new services in Windows Services, which are: Oracle Hospitality Cruise SPMS Platform Administration, Oracle Hospitality Cruise SPMS Platform Mobility, and Oracle Hospitality Cruise SPMS Platform API.

    Figure 8-6 Cruise Property Management Window Services


    This figure shows the Cruise Property Management Window Services

  12. The system also creates three sub-folders under Oracle Hospitality Cruise – ‘PropertyManagementAPI’, ‘PropertyManagementAPP’ and PropertyManagementScripts.

Uninstalling Cruise Property Management 20.2

  1. Start the installation program by right-clicking the Cruise Property Management 20.2.exe and selecting Run as Administrator. If SPMS 20.2 is already installed, the Setup starts in Un-Installation mode, allowing you to remove it.

  2. Click Remove and wait until uninstall is complete.

    Figure 8-7 Cruise Property Management Installshield - Remove Program


    This figure shows the SPMS NextGen 20.1 Installshield - Remove Program.
  3. The system removes the following:

    1. PropertyManagementAPI, PropertyManagementAPP and PropertyManagementScripts folders under Oracle Hospitality Cruise.

    2. Windows Services: Oracle Hospitality Cruise SPMS Platform Administration, Oracle Hospitality Cruise SPMS Platform Mobility and Oracle Hospitality Cruise SPMS Platform API.

Applying Cruise Property Management Patch 20.2 x Upgrade

This Patch Upgrade Setup distributes the latest Administration, Mobility, and API application files required by the Cruise Property Management. You must have an Administrative privilege to be able to perform this task.

  1. Log in as a Microsoft Windows Administrative user.

  2. Start the installation program by right-clicking the Cruise Property Management Patch 20.2.x.exe and select Run as Administrator.

  3. Click Next to continue the installation.

  4. Click Install to begin installation.

  5. During the install, a PowerShell window will be launched and closed automatically.

  6. Click Finish to close the installation wizard.

At the end of the installation, the system will create a sub-folder under Oracle Hospitality Cruise — Platform Patch 20.2.x’ and back up the existing folder for Administration and Mobility application.

Cruise Property Management for High Availability (HA)

To set up a High Availably environment for SPMS API and the associated web applications (Mobility and Administration), Oracle recommends:

  1. Running multiple instances of SPMS API Services on the same server (to protect against failure of a single instance on that server).

  2. Running multiple instances of the SPMS Mobility/Administration Web Application on the same server (to protect against failure of a single instance on that server).

  3. Setup of multiple servers with the same configurations as 1 and 2 (to protect against a single server failing).

  4. Use a High Availability (HA) Oracle database environment (such as Oracle RAC).

  5. Provide multiple instances of the load balancer and connect them together through technology like the Virtual Router Redundancy Protocol (VRRP).

  6. Route all requests between the browser and the API through the load balancers.

  7. Route all requests between the browser and the administration/mobile app through the load balancers.

  8. Set up rate limiting on the load balancer to prevent Distributed Denial of Service (DDOS) attacks.

Important:

Before you change any of the Database Encryption Key/Password and if you have SPMS REST API Server installed, you must uninstall the Cruise Property Management and reinstall the application after the password change.