1. Installation Guide
  2. Installing SPMS Rest API/Web Application Server

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.3.2. If you are running a previous version, upgrade the database to 20.3.2 before continuing.

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

  • Java JDK version 17.0.4 and above is required.

  • A tool for generating certificates. As an example, this document uses a custom tool JSON Web Key (JWK) for our internal team to generate JWK. Other tools are available. We recommend that you 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 (verify-jwk.json) and private key (sign-jwk.json) for setting up secure OAUTH. As an example, this document explains how 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.3.3 API/Apps server,

  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.3 API/Apps server. A 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. You will be prompted to create a password for the new Keystore.

  5. 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). For example Redwood City

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

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

    8. You will be prompted to verify all the information entered. Type ‘y’ or ‘yes’ to confirm.

    9. Enter enter the Keystore password when prompt. 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 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.

Note:

Before importing the SSL/TLS certificate, make sure the certificate chain is in appropriate format and valid. You can use OpenSSL tool to check on the validity as follows: 

openssl pkcs7 –print_certs –in <cert_name>.p7b

  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 indicates 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 JSON Web Key Generator

  1. Go to https://mkjwk.org/ for the JSON Web Key generator tool.

  2. Select the RSA tab.

  3. Select the right Key Size in bits, required for RSA key types. Recommended size is 2048 and above.

  4. Select the Key Use as signature.

  5. Select the Key ID as specify and enter any string, for example sign-rsa.

  6. In the ShowX.509, select No

  7. Copy the ‘Public Key’ and “Public and Private Keypair Set” into a separate files with .json extension and save.

  8. Sample public and private keys are shown below.

    Sample Public key:
    {
    "keys": [
        {
            "kty": "RSA",
            "e": "AQAB",
            "use": "sig",
            "kid": "sign-rsa",
            "alg": "RS256",
            "n": "g88SjdDsfdHd64fdf..."
        }
    ]
}
    Sample Private key: 
    {
    "keys": [
        {
            "p": "5BjdvhhdGjjjdsUI...",
            "kty": "RSA",
            "q": "k-7TihGsdfjnjLLf8...",
            "d": "e4t4J7dfk7jddPo78...",
            "e": "AQAB",
            "use": "sig",
            "kid": "sign-rsa",
            "qi": "UlYwJ6Jsdfsdfc...",
            "dp": "CDz5rYYsdffffI1...",
            "alg": "RS256",
            "dq": "fBAEeUP98HHdf...",
            "n": "g88SjLLjsdf881IP..."
        }
    ]

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 choose to perform a typical installation, manually remove or disable the features that you do not need after the installation.

Note:

If one of the older versions such as 20.1, 20.2 is already installed, the Setup prompts a message if you would like to uninstall them before installing 20.3.3. If you select No, the setup exits from the installation.

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

Installing Cruise Property Management 20.3.3

  1. Log in as a Microsoft Windows Administrative user.

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

    Figure 8-1 Cruise Property Management Installation Wizard Welcome Page


    This figure shows the SPMS Platform Property Management Installation Wizard Prerequisite Page

  3. Click Install to apply the LongPathRegistryCheck to enable Long Paths setting in the registry. At the prompt continue by clicking ‘Yes’ and a message appears, notifying if the change is successfully or not. This setting is required for a successful 20.3.3 install. By default, Windows only support file path length of 260 characters. With this setting, it allow Windows to support beyond 260 characters.

    Figure 8-2 Cruise Property Management Installation Wizard — Welcome Page


    This figure shows the Cruise Property Management Installation Wizard — Welcome Page

  4. 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”. Unlike previous versions, the default folder to install has changed from “C:\Program Files (x86)\Oracle Hospitality Cruise\PropertyManagementAPI\” to “C:\Program Files (x86)\Oracle Hospitality Cruise\”.

    If you choose to install it in a different folder from the default, you need to grant the folder full permission so that the user can start the APIs or Apps.

  5. To grant the folder permission,

    • Access the Properties dialog box.

    • Select the Security tab.

    • Click Edit.

    • In the Group or user name section, select the user(s) you wish to set permissions for.

    • In the Permissions section, select the appropriate checkboxes for the permission level.

    • Click Apply.

    • Click OK.

    Figure 8-3 Cruise Property Management Installation - Custom Setup


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

    • Database connection String: <DBMachineName>:<DBPort>/<SID>

    • Database User: DB Password.

    • Database Keystore: DB Keystore’s password for database encryption. Minimum password length is 8 characters.

    • API URL: API Server’s URL.

    • 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 port 7443, 8443. If these ports are unavailable or used, you need to choose an unused port for the installation.

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

    • Keystore File Path: Keystore file path which contain .JKS file extension.

    • Keystore password: Keystore password.

    • App Port: Web App port. If you need to install multiple instances, enter the ports in comma separated format. By default, Install shield populates port 7090, 8090. If these ports are unavailable or used, you need to choose an unused port for the installation.

    Figure 8-4 Cruise Property Management Installation Settings


    This figure shows the Cruise Property Management Installation - Database Settings

  7. When the option Allow All APP Servers is checked, the message box above shall prompt, alerting the user of the chosen option.

    Figure 8-5 Allow All APP Servers Notification


    This figure shows the Allow All APP Servers Notification prompt

  8. Click Next to update the OAuth Configuration settings for the fields below:

    • OAuth Public Key File: OAuth public key file in .json file extension.

    • OAuth Private Key File: OAuth private key file in .json file extension.

  9. Click Next to update the OPI Configuration settings.

    • Enable OPI: checkbox to enable or disable OPI Integration.

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

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

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

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

    • OPI EFT Timeout: The time SPMS clients wait for the response from the OPI.

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

  10. Click Next to update the Passport Scanner settings.

    • Enable Passport Scanner: checkbox to enable or disable Passport Scanner Integration

    • Hardware ID: Hardware Id provided by the vendor

    • Register URL: Url provided by the vendor to retrieve the access token

    • ProcessImage API URL: API Url provided to process the scanned image

    • Account Id: Account Id provided by the vendor

    • Access Secret: Access secret used for the authentication registration

    • Access Secret Keystore: Access Secret Keystore password

    • API Key: API Key provided by the vendor

    • Proxy Host Proxy Host Fully Qualified domain name or IP

    • Proxy Port: Proxy Host port

  11. Click Install to begin installation.

    Figure 8-6 Cruise Property Management Ready Install


    This figure shows the 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 UserProfile/AppData/Local/Oracle Hospitality Cruise. This file is reloaded on upgrade/re-install, so that end user does not have to re-enter the configuration

  12. During the install, a couple of PowerShell windows will launch and closed automatically.

  13. API’s configuration is stored in the Application.yaml in yaml format.

  14. At the end of the installation, the system creates two (2) new Windows Services and they are Oracle Hospitality Cruise SPMS Platform WebApp and Oracle Hospitality Cruise SPMS Platform API.

    Figure 8-7 Cruise Property Management Window Services


    This figure shows the Cruise Property Management Window Services

  15. The system will also create three (3) sub-folders under Oracle Hospitality Cruise – ‘PropertyManagementAPI’, ‘PropertyManagementAPP’ and PropertyManagementScripts

Uninstalling Cruise Property Management 20.3.x

  1. Start the installation program by right-clicking the Cruise Property Management 20.3.3.0.exe and select Run as Administrator. If SPMS 20.3.3 is already installed, the Setup starts in Maintenance mode, allowing you to reinstall.

  2. Select the available option and wait until uninstall is complete, where a Removal Complete page shall prompt. In the case of Reinstall, follow the prompts presented to uninstall and install.

    Figure 8-8 Cruise Property Management 20.3.x Installshield - Reinstall Program


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

    1. From the Oracle Hospitality Cruise folder: PropertyManagementAPI’, ‘PropertyManagementAPP’ and ‘PropertyManagementScripts’ folder.

    2. Windows Services: Oracle Hospitality Cruise SPMS Platform WebApp and Oracle Hospitality Cruise SPMS Platform API.

Applying Cruise Property Management Patch 20.3 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.3.x.exe and select Run as Administrator.

  3. Click Next to continue the installation.

  4. Click Install to begin installation.

  5. Click Finish to close the installation wizard.

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

Note:

From 20.3.3.1 onward, the API’s configuration file application.yaml will be replaced by application.properties.

Cruise Property Management for High Availability (HA)

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

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

  • 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).

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

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

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

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

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

  • 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.