Set up Secure Sockets Layer (SSL)

Service Manager supports Secure Hypertext Transfer Protocol (HTTPS), which encrypts and decrypts message requests and responses. Service Manager uses Secure Sockets Layer (SSL) for encryption only and relies on the server to authenticate each operator's user name and password. Service Manager supports SSL for the following connections:

  • SSL on the Service Manager server to encrypt all communications between clients and the server
  • SSL on the Mobile Applications client to verify the client's identity and limit server connections to these identified clients

For detailed information about how to enable SSL and SSO in Service Manager, refer to the Service Manager Help Center and the Setting up Single Sign-on in Service Manager knowledge article.

Enable SSL on the Service Manager server

Service Manager clients send the operator’s user name and password in each request as part of an HTTP Basic Authorization header. In order to protect these operators’ user names and passwords, you can enable SSL on the Service Manager server.

Enabling SSL on the Service Manager server includes three major steps:

  1. Purchase a certificate for the Service Manager server from a certificate authority, or create a certificate by yourself.
  2. Create a server keystore. For detailed steps, refer to the Setting up Single Sign-on in Service Manager knowledge article.
  3. Add SSL parameters to the sm.ini file.

    Note Ignore the SSO parameters in the table at this point.

Enable SSL on the Mobile Applications client

In order to restrict access to the server to only clients that are known and identified by the server, you can enable SSL on Service Manager clients. Enabling SSL on clients requires creating or purchasing signed certificates for each Service Manager client. Service Manager Mobile Applications can share a single signed certificate for all handset connections. If you enable SSL on the client, we recommend that you also enable SSL on the server to encrypt all communications between clients and the server.

To enable SSL on the Mobile Applications client, follow these steps:

  1. Purchase a certificate for the Mobile Applications client host from the same certificate authority for the Service Manager server certificate, or create a certificate by yourself.
  2. Create a client keystore. For detailed steps, refer to the Setting up Single Sign-on in Service Manager knowledge article.
  3. Import the client certificate to a trusted clients keystore. For example, trustedclients.keystore.
  4. Copy the trusted clients keystore (trustedclients.keystore) to the Service Manager server's RUN folder.
  5. Open webapp-9.60.xxxx.war in an archive management program.
  6. Copy the cacerts file to the WEB-INF directory.
  7. Extract the web.properties file from the WEB-INF directory to your local system, and then open this file in a text editor.
  8. Locate the following codes and configure the parameters as follow:

    endpoint=https://full.qualified.domain.name:13443/SM/ui
    
    cacerts=
    keystore=
    keystorePassword=
    Required parameters for Mobile Applications client SSL configurations
    Parameter Default value Description
    endpoint https://full.qualified.domain.name:13443/SM/ui

    Change full.qualified.domain.name to the domain name of your Service Manager server.

    Change 13443 to your SSL port number.

    cacerts The default value is null. Add the name of your cacerts file.
    keystore The default value is null.

    Add the name of the keystore file.

    keystorePassword The default value is null.

    Add the password of the keystore file. We recommend adding a strong password for the keystore. After you restart the Mobile Applications client, the keystore password is encrypted and the original keystorePassword= code is automatically updated to *keystorePassword=<encrypted string>.

    Note The preceding asterisk (*) implies that the keystore password is encrypted. To change the password, remove the asterisk and replace the encrypted string with the new password.

  9. Save the file and add the updated file back to the WEB-INF directory of the webapp-9.60.xxxx.war archive.
  10. Restart the Service Manager Mobile Applications client.

Set up SSL between the smartphone browser and Mobile Applications

You can set up SSL to allow smartphone browsers and web servers to communicate over a secure connection. The data being sent is encrypted by one side, and decrypted by the other side before processing. This is a two-way process, meaning that both the server and the browser encrypt all traffic before sending out the data.

After SSL is set up on the web servers, browsers which support secure flag only send cookies with the secure flag when the request is going to an HTTPS page, that is, the browser does not send a cookie with the secure flag set over an unencrypted HTTP request.

You need to set up SSL on the web server or web application server where the Mobile Applications client is deployed, and update the port number mapping for the Mobile Applications client as necessary.

Set up SSL on you web server

For details, refer to the documentation of your web server.

Note It is recommended to enable HTTPOnly and Secure cookies on your web application server to help prevent malicious JavaScript injection and make the browser (or other http clients) only send cookies over SSL connections. For more information, see https://softwaresupport.softwaregrp.com/km/KM02233778.

Set up SSL on Tomcat

Configuring Tomcat to use SSL is only necessary when Tomcat is run as a stand-alone web server. When Tomcat is primarily run as a Servlet/JSP container behind another web server, such as Apache or Microsoft IIS, it is necessary to configure the primary web server to handle the SSL connections from users. Typically, this server negotiates all SSL-related functionality, and then pass on any requests destined for the Tomcat container only after decrypting those requests. Likewise, Tomcat returns cleartext responses that are encrypted before being returned to the user's browser. In this case, Tomcat knows that communications between the primary web server and the client are taking place over a secure connection, but it does not participate in the encryption and decryption processes.

For information about how to set up SSL on Tomcat, refer to Apache Tomcat SSL Configuration HOW-TO document.

Note Since you have already got your certificates for the server as described in the previous step in the Enable SSL on the Mobile Applications client section, you only need to perform the steps in the Edit the Tomcat Configuration File section in Apache Tomcat SSL Configuration HOW-TO document.

Set up SSL on WebSphere 8.5.5

You can set the Secure flag within the WebSphere Application Server administrative interface. The Restrict cookies to HTTPS Sessions check box is available through the WebSphere Admin Console: Application servers > [Your server] > Session management > Enable Cookies link. For details, refer to the WebSphere 8.5.5 SSL configuration documentation.

Update the port number mapping for the Mobile Applications client

To update the port number mapping for the Mobile Applications client, follow these steps:

  1. Go to Tomcat webapps directory of Mobile Applications.

  2. Open WEB-INF\spring\security.xml with a text editor.

  3. Locate the following codes, and then update the default security ports as necessary.

    <security:http auto-config='true'>
            <security:port-mappings>
                <security:port-mapping http="8080" https="8443"/>
            </security:port-mappings>
            <security:intercept-url pattern="/**"  requires-channel="https"/>
     </security:http>

    Note Remember to update the port number to the same as the configuration in your web server or web application server.

  4. Save the changes.