Remedy AR System Server: REST API Architecture and Overview - Start Here - INCLUDES VIDEO

Knowledge Article

Remedy AR System Server: REST API Architecture and Overview - Start Here - INCLUDES VIDEO
AR Server REST API architecture and overview
Remedy AR System Server
MidTier
AR server 9x with REST API
Remedy AR System Server
MidTier
AR server 9x with REST API
Remedy AR System Server
MidTier
AR server 9x with REST API
This knowledge article may contain information that does not apply to version 21.05 or later which runs in a container environment. Please refer to Article Number 000385088 for more information about troubleshooting BMC products in containers.
 

Architecture

AR server has a Jetty server that will receive REST API calls. AR server will need one or 2 more ports to receive HTTP/HTTPS requests.
The Jetty server used in the AR server is an embedded version, hence it is trimmed down to the bare minimum to address these requests. Once Jetty receives a request it will translate into an API Call (create Entry, set entry, etc). Filters on the AR server will trigger in the same way as with any other API call
User-added image
The authentication mechanism requires a single step to gather a token that will time out (no matter what). This token should be retrieved to be able to make subsequent requests
eg. Authenticate, get token, then perform operations like get entries, update,  create an entry using the token, then logout releasing the token

Login process is depicted here: https://docs.bmc.com/docs/display/public/ars91/Login+information
For a broader description of architecture and features https://docs.bmc.com/docs/display/public/ars9000/BMC+Remedy+AR+System+REST+API+overview


How to enable REST API

By default REST API is turned on by default on port 8008 without SSL

If you want jetty to publish REST API using SSL, use the attached sample configuration. It includes a self-signed certificate and a jetty-selector.xml file that will open both HTTP and HTTPS ports. Note that valid certificates should be created for production usage as this certificate was created for a BMC testing machine

 

To enable SSL on Jetty  for AR server 9x prior to 9104 - using the sample configuration


For AR server 9x prior to 9104
  1. Make a backup of jetty-selector.xml
  2. Copy the zip file contents into C:\Program Files\BMC Software\ARSystem\jetty\etc
  3. Restart AR Server


To enable SSL on Jetty  For AR server  9104 and above - using the sample configuration

  1. Make a backup of the jetty/etc folder
  2. Copy the zip file contents from the 9104 sample into C:\Program Files\BMC Software\ARSystem\jetty\etc
  3. Restart AR Server
  4. The sample files will open port 9443 which can be changed in files etc\jetty-http.xml and etc\jetty.xml
  5. To enable SSL on Jetty use this KB:


What clients can be used to test REST API

We recommend using HttpTestTool / TestHttpClient for this purpose 
Several scripts and webinars explain how to use the tool and perform multiple operations. Other clients such as Soap UI, curl, Invoke-WebRequest, or postman can be used too.

Webinar https://community.bmc.com/s/news/aA33n000000ClBGCA0/connect-with-bmc-helix-itsm-and-remedy-invoking-itsm-rest-services-webinar

Articles for individual use cases. Each one contains a collection of scripts (also available in this article)

How to use Remedy filters calling 3rd party REST services


Frequent Questions

What REST API features are available on each Remedy Version?


Can the AR server consume 3rd party REST API services?
Yes, since 1908

How can I consume AR server REST API from code running on a browser? 
The Jetty port needs to be accessible from a browser
    1. Lift CORS restriction from your web application domain 
        https://community.bmc.com/s/article/REMEDY-REST-API-CORS-setup-for-Swagger-UI
    2. Use a swagger app or similar code from your browser

    Other options that do not require the jetty port to be accessible from your browser can be done but are not supported by BMC
 

When a vulnerability is found on REST API ports, how can I change or configure Ciphers?

The jetty-selector.xml file attached to this article has been reviewed (Aug 23rd) to comply with OWASP recommendations. https://www.owasp.org/index.php/Securing_tomcat
for other jetty-selector rules https://wiki.eclipse.org/Jetty/Howto/CipherSuites
This sample configuration adds 

                <Set name="ExcludeCipherSuites">
                    <Array type="java.lang.String">       
                         <Item>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>SSL_RSA_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>SSL_DH_anon_WITH_3DES_EDE_CBC_SHA</Item>
                         <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_DH_anon_WITH_DES_CBC_SHA</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>SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA</Item>
                         <Item>TLS_KRB5_WITH_3DES_EDE_CBC_SHA</Item>
                         <Item>TLS_KRB5_WITH_3DES_EDE_CBC_MD5</Item>
                         <Item>TLS_KRB5_WITH_DES_CBC_SHA</Item>
                         <Item>TLS_KRB5_WITH_DES_CBC_MD5</Item>
                         <Item>TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA</Item>
                         <Item>TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5</Item>
                    </Array>
                </Set>


How to gather evidence on REST API activity

How to enable a separate log for REST API, what will be displayed (including API SQL and filter logs)? 
KB How to create REST API and Jetty-specific log https://community.bmc.com/s/article/How-to-turn-logging-for-restapi-problems


Is Jetty opening ports?

On any browser that can reach jetty ports access http://arserver:unsecureRESTPort/ and https://arserver:secureRESTPort/
In both cases, the browser would display a 404 error. that means the port is open and listening
Further reference:
                https://docs.bmc.com/docs/display/ars9000/Operations+on+entry+objects

 

For further REST API material
Attachment(s):
full_etc folder_https_enabled_9104.zip
jetty-selector_sweet32_checked.zip
httpTestTool including webinar scripts and command lines