This documentation supports the 20.02 version of Remedy Action Request (AR) System.

To view an earlier version, select the version from the Product version menu.


Configuring the REST API by using SSL certificates

The primary reason for using Secure Sockets Layer (SSL) certificates is to keep sensitive information sent across the internet encrypted so that only the intended recipient can understand it. This security is important because the information you send on the internet is passed from computer to computer to get to the recipient. Any computer between you and the destination can utilize your user name, passwords, and other sensitive information if the information is not encrypted with an SSL certificate.

In addition to encryption, a proper SSL certificate also provides authentication. With authentication, you can be sure that you are sending information to the right recipient and not to an unknown user. You can ensure authentication by using an SSL certificate from a trusted SSL provider.

The keytool utility is used to obtain a digitally signed certificate to replace the self-signed certificate. This utility is available with Oracle JDKs. The Java keytool is a key and certificate management utility. It allows users to manage their own public or private key pairs and certificates. The Java keytool stores the keys and certificates, which is called as keystore. A keystore contains the private key and any certificates necessary for authentication. The keystore is located in the <jre_home>/bin directory of your Java installation file.

Configuring the Jetty web server

You can create new keystores either by configuring REST API for HTTPS connection or by configuring REST API for HTTP connection.

For information on troubleshooting Jetty startup issues, see BMC Knowledge Base article ID 000134172.

Configuring REST API for HTTPS connection

Follow the steps given below to configure REST API for HTTPS connection.

  1. Import the existing signed primary certificate into an existing Java keystore:  

    keytool -import -trustcacerts -alias mydomain -file mydomain.crt -keystore keystore.jks

    If you do not have a certificate, create a new keystore by using a new password to secure the certificate:

    keytool -keystore keystore -alias jetty -genkey -keyalg RSA
    

    After the keystore has been created, you must provide six parameters that form a distinguished name for a certificate associated with the key.

    • CN—Common Name of the certificate owner (usually the name of the host)
    • OU—Organizational Unit of the certificate owner
    • O—Organization to which the certificate owner belongs
    • L—Locality name of the certificate owner
    • ST—State or province of the certificate owner
    • C—Country of the certificate owner

      Note

      The keystore file is created in the current directory of the command window.

  2. Obfuscate the SSL connector keystore password for greater security. 
    For more information, see Obfuscating the password.
  3. Update the jetty-http.xml file with the new password for the keystore.

    Note

    * In <Set name="KeyStorePath"><Property name="jetty.home" default="." />/etc/keystore</Set>, remove <Property name="jetty.home" default="." />.

    * Replace /etc/keystore/ with the actual path to the keystore.

    <Call name="addConnector">
        <Arg>
          <New class="org.eclipse.jetty.server.ServerConnector">
            <Arg name="server"><Ref refid="Server" /></Arg>
    		<Arg type="java.lang.Integer" name="acceptors">2</Arg>
    		<Arg type="java.lang.Integer" name="selectors">-1</Arg>
            <Arg name="factories">
              <Array type="org.eclipse.jetty.server.ConnectionFactory">
                <Item>
                  <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                    <Arg name="config"><Ref refid="httpConfig" /></Arg>
                  </New>
                </Item>
              </Array>
            </Arg> 
            <Set name="host"><Property name="jetty.http.host" /></Set>
            <Set name="port"><Property name="jetty.http.port" default="8008" /></Set>  
    		<!--Uncomment to Enable Connector Statistics -->
    		<!--<Call name="addBean">
    			<Arg>
    				<New id="ConnectorStatistics" class="org.eclipse.jetty.server.ConnectorStatistics"/>
    			</Arg>
    		</Call> -->
           </New>
        </Arg>
      </Call>
    	 
    	
    	<!-- Uncomment this to add SSL support for REST API,
             replace the values to match your environment -->	
      <!-- <New id="httpsConfig" class="org.eclipse.jetty.server.HttpConfiguration">
            <Call name="addCustomizer">
                <Arg>
                    <New class="org.eclipse.jetty.server.SecureRequestCustomizer" />
                </Arg>
            </Call>
    		<Set name="sendServerVersion">false</Set>
        </New>
    	
      <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
        <Set name="KeyStorePath"><absolute path of keystore file></Set>
    	<Set name="KeyManagerPassword">OBF:1uh41zly1x8g1vu11ym71ym71vv91x8e1zlk1ugm</Set>
        <Set name="KeyStorePassword">OBF:1uh41zly1x8g1vu11ym71ym71vv91x8e1zlk1ugm</Set>
        <Set name="TrustStorePath"><absolute path of keystore file></Set>
        <Set name="TrustStorePassword">OBF:1uh41zly1x8g1vu11ym71ym71vv91x8e1zlk1ugm</Set>
    	<Set name="IncludeCipherSuites">
    	  <Array type="String">
    	      <Item>TLS_DHE_RSA.*</Item>
    	      <Item>TLS_ECDHE.*</Item>
    	  </Array>
    	</Set>
    	<Set name="ExcludeCipherSuites">
    	   <Array type="String">
    	    <Item>SSL_RSA_WITH_DES_CBC_SHA</Item>
    	    <Item>SSL_DHE_RSA_WITH_DES_CBC_SHA</Item>
    	    <Item>SSL_DHE_DSS_WITH_DES_CBC_SHA</Item>
    	    <Item>SSL_RSA_EXPORT_WITH_RC4_40_MD5</Item>
    	    <Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
    	    <Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
    	    <Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item>
    	
    	    <Item>.*NULL.*</Item>
    	    <Item>.*RC4.*</Item>
    	    <Item>.*MD5.*</Item>
    	    <Item>.*DES.*</Item>
    	    <Item>.*DSS.*</Item>
    	    <Item>.*_DHE_RSA_.*</Item>
    	
    	   </Array>
    	</Set>
    	<Set name="ExcludeProtocols">
    	     <Array type="java.lang.String">
    	         <Item>SSL</Item>
    	         <Item>SSLv2</Item>
    	         <Item>SSLv2Hello</Item>
    	         <Item>SSLv3</Item>
    	     </Array>
    	</Set> 	    
      </New>
      
      <New id="sslConnectionFactory" class="org.eclipse.jetty.server.SslConnectionFactory">
            <Arg name="sslContextFactory">
                <Ref refid="sslContextFactory" />
            </Arg>
            <Arg name="next">http/1.1</Arg>
      </New>
    
      <New id="sslConnector" class="org.eclipse.jetty.server.ServerConnector">
        <Arg name="server"><Ref refid="Server" /></Arg>
        <Arg name="factories">
            <Array type="org.eclipse.jetty.server.ConnectionFactory">
                <Item><Ref refid="sslConnectionFactory" /></Item>
                <Item>
                    <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                      <Arg name="config"><Ref refid="httpsConfig" /></Arg>           
                    </New>
                </Item>
            </Array>
        </Arg>
    	<Set name="port">8443</Set>        
      </New> 
    	
    	<Call name="setConnectors">
            <Arg>
                <Array type="org.eclipse.jetty.server.ServerConnector">
                    <Item>
                        <Ref refid="sslConnector" />
                    </Item>
                </Array>
            </Arg>
        </Call> 
          -->
    </Configure>
  4. Make sure that the arserver.conf file or the arserverd.config file includes the bouncycastle option for JMS messaging to work.
    See the following example:

    jvm.option.21=-Dorg.apache.activemq.broker.BouncyCastlePosition=100

    Important

    Use the next available number for the jvm.option.##, which is relevant to your installation.

  5. Restart the AR System server.

After you restart the AR System sever, the following warning is displayed and you may experience runtime errors.

WARN:oejob.JettyBootstrapActivator:main: OSGi support for java.util.ServiceLoader may not be present.

Perform the following steps to turn-on the logging for jetty:

  • Enable jetty log level in the arserver.config file for Windows and in the arserverd.conf file for  Linux. Use the following JVM option:
    -Dorg.eclipse.jetty.LEVEL=DEBUG
  • Enable extra Jetty Related logs in the Jetty/etc/Jetty.xml file. Refer to the following code sample:

    <Call
    class="org.eclipse.jetty.util.log.Log"
    name="getRootLogger">
            <Call
    name="setDebugEnabled">
                <Arg
    type="boolean">false</Arg>
            </Call>

    Here, set the boolean argument of the setDebugEnabled property to true.

Once you enable the logging, the jetty logs are displayed on the server console or in the armonitor.log file. For more information, see the knowledge article on BMC Communities  How to turn logging on for RESTAPI problems Open link

After you create a self-signed certificate, browsers and other programs issue warnings to users about an insecure certificate each time the user authenticates. You can prevent the certificate warning by adding the self-signed certificate to the Trusted Root Certification Authorities store. 

Obfuscating the password

The Jetty passwords are stored as clear text, obfuscated, check-summed, or in encrypted form. For the keystore/ key/ truststore passwords, you must obfuscate the passwords. The class org.eclipse.jetty.util.http.security.Password is used to generate all types of secure passwords. Create password at <install directory> \lib\start\startlevel1 location. The following command is used to create a new password:

The username parameter in the following command is optional.

Syntax
java org.eclipse.jetty.util.security.Password [<user>] <password>


Example
java -cp jetty-util-9.4.11.v20180605.jar org.eclipse.jetty.util.security.Password username password

The version-specific jar file is located in the <AR System Install directory>\lib\start\startlevel1 folder. Use the same file in the command.

If you are using a reverse proxy, uncomment the below section from the jetty-http.xml file.

<Call name="addCustomizer">
        <Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
      </Call>

Configuring REST API for HTTP connection

Follow the steps given below to configure REST API for HTTP connection.

  1. Locate the Jetty sub directory from the AR System installation directory. 
  2. From the jetty-http.xml file, uncomment the following HTTP connector if you use a reverse proxy that handles HTTPS and change the default port to 8008 according to your need.

      <Call name="addConnector">
        <Arg>
          <New class="org.eclipse.jetty.server.ServerConnector">
            <Arg name="server"><Ref refid="Server" /></Arg>
    		<Arg type="java.lang.Integer" name="acceptors">2</Arg>
    		<Arg type="java.lang.Integer" name="selectors">-1</Arg>
            <Arg name="factories">
              <Array type="org.eclipse.jetty.server.ConnectionFactory">
                <Item>
                  <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                    <Arg name="config"><Ref refid="httpConfig" /></Arg>
                  </New>
                </Item>
              </Array>
            </Arg> 
            <Set name="host"><Property name="jetty.http.host" /></Set>
            <Set name="port"><Property name="jetty.http.port" default="8008" /></Set>  
    		<!--Uncomment to Enable Connector Statistics -->
    		<!--<Call name="addBean">
    			<Arg>
    				<New id="ConnectorStatistics" class="org.eclipse.jetty.server.ConnectorStatistics"/>
    			</Arg>
    		</Call> -->
           </New>
        </Arg>
      </Call>	 
  3. Restart the AR System server.

Related topic

Integrating AR System forms with a third-party application by using the REST API

 


Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Ariel Manka

    Documentation issue: In "Configuring REST API for HTTPS connection" point 3 instructions note says: "n /etc/keystore, remove ." Yet, in the example below code shows: "/etc/keystore"

    Apr 19, 2022 11:43
    1. Anagha Deshpande

      Hello Ariel,

      Thanks for bringing this to our notice.

      We have updated the example.

      Regards,

      Anagha

      May 10, 2022 05:00
  2. Conrad Pereira

    Hi,

    After Obfuscating the password section above, the below information is missing in the above documentation, which I believe should be performed, as the Jetty over SSL would not work without this.

    Make sure arserver.conf or arserverd.config includes the bouncycastle option. Add the option using the following statement as an example: jvm.option.21=-Dorg.apache.activemq.broker.BouncyCastlePosition=100 Note: Use the next available number for the jvm.option.## relevant to your installation.

    The Bouncy Castle Crypto package is a Java implementation of cryptographic algorithms. The package is organized so that it contains a light-weight API suitable for use in any environment (including the newly released J2ME) with the additional infrastructure to conform the security algorithms to the JCE framework.

    Jan 31, 2023 08:38
    1. Rejean Rivest

      Thank you so much for this comment. I had this issue on different server and turns out the missing line was the problem. I don't think I would have found this configuration otherwise

      Feb 27, 2023 10:10
    1. Anagha Deshpande

      Hello Conrad,

      We have updated the topic.

      Apr 04, 2023 05:00
  3. Andreas Mitterdorfer

    Please can you clarify: If you are using a reverse proxy, uncomment the below section from the jetty-http.xml file. ... Call name="addCustomizer

    This is in the https section of jetty-http.xml file. Do we need to add it when using http only with reverse proxy and if so, how & where?

    Mar 10, 2023 05:46
    1. Anagha Deshpande

      Hello Andreas,

      For http, you need not add any proxy. The required tag is already added to the jetty.xml file under httpConfig. It is referred by the jetty-http.xml file.

      Regards,

      Anagha

      Apr 04, 2023 04:59