AR Server REST API architecture and overview - Start here

Version 32
    Share This:

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    PRODUCT:

    Remedy AR System Server


    APPLIES TO:

    AR server 9x with REST API



    DETAILS:

     

    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 AR server is an embedded version, hence it is trimmed down to the bare minimal to address these requests.Once Jetty receives a request it will translate into an API Call (create Entry, set entry, etc). Filters on 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 create entry using the token.  
     
    Login process 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 
        

    Some login process details

       
     A single JWT token is valid for about an hour (variable AR_SERVER_INFO_EA_SYNC_TIMEOUT controls this) Therefore if you have a token you can attempt a call and if that call returns an error 623 you would need a new token.  
    A single token can also be used across multiple AR servers that are in the same AR server group.  
     
    In order to decode a token just use a base64 decoder and some information will be visible such as  
    Sample token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJDVEZZXC9aN2ZyYTRRRUZydFRNUG5WOWFtXC9yZlpzRDhtckw2K1BhYkgycjBIYzVCbkl3cXVrbHdaSjdySGNBTkU3WWs5ODhqT1B3QWJWbnFXRDBRK0psdjJqcHdWeGZYQ3VNb29nRXluNXl0TXB2eUxuS0J4VXc9PSIsIm5iZiI6MTUyMjY5MDkyMCwiaXNzIjoiY2xtLWF1cy0wMjIzMDcuYm1jLmNvbSIsImV4cCI6MTUyMjY5NDY0MCwiX2NhY2hlSWQiOjY4NTYsImlhdCI6MTUyMjY5MTA0MCwianRpIjoiSURHQUE1VjBHRVFDQUFQR0s5WDJQRk5ZRFI3Q1ZaIn0.BtZtaYwmF4pgjT8zOQCEuV1juzRGkcZsYpJZ88pOObE  
     
    once decoded from base64  
     
    "alg":"HS256"} {"sub":"CTFY\/Z7fra4QEFrtTMPnV9am\/rfZsD8mrL6+PabH2r0Hc5BnIwquklwZJ7rHcANE7Yk988jOPwAbVnqWD0Q+Jlv2jpwVxfXCuMoogEyn5ytMpvyLnKBxUw==","nbf":1522690920,"iss":"clm-aus-022307.bmc.com","exp":1522694640,"_cacheId":6856,"iat":1522691040,"jti":"IDGAA5V0GEQCAAPGK9X2PFNYDR7CVZ"} The expiration is exp field and it is in epoch 
       

    How to enable rest api

      
      By default the initial configuration would not work (prior to 9104), changes are required.The basic change would be to 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  
     
    Manual procedure is located here:    https://docs.bmc.com/docs/display/public/ars91/Configuring+the+REST+API 
    Manual process depicted on video here    https://www.youtube.com/watch?v=mKvQpAQ5iOo&feature=youtu.be 
     
    Using the sample configuration will save some steps  
    To use the sample https configuration and keystore 
      
     
    For AR server 9x prior to 9104 
      
       
    1. Make a backup of jetty-selector.xml
    2.  
    3. Copy the zip file contents into C:\Program Files\BMC Software\ARSystem\jetty\etc
    4.  
    5. Restart AR Server
      
      For AR server 9104 (if you want to enable http nothing is required, port 8008 is opened by installer configuration. The following steps are required for https)   
        
    1. Make a backup of jetty/etc folder
    2.   
    3. Copy the zip file contents from 9104 sample into C:\Program Files\BMC Software\ARSystem\jetty\etc
    4.   
    5. Restart AR Server
    6.   
    7. The sample files will open port 9443 this can be changed in files etc\jetty-http.xml and etc\jetty.xml
    8.  
      
      

    What is postman

      
      Postman is an http client focused on building and executing REST API calls in JSON format. BMC uses it heavily to demonstrate features, but it is just a testing / debugging client. 
      

    Besides being a client for testing are there any best practices while using postman?

      
      Yes, the main recommendation is to use "environments" and "collections", environments will save variables for reuse like: jwt tokens, server names, ports.  "Collections" will save request which can get complex.  
    KB How to use Collections and Environments on postman:    https://selfservice.bmc.com/casemgmt/sc_KnowledgeArticle?sfdcid=  000128813

    Can postman do every operation supported by REST API on AR server ?
      
     
    No, uploading attachments is the major limitation. Java, javascript and other sample codes are available to perform this task  
      KB How to send attachments via the Remedy REST API: https://selfservice.bmc.com/casemgmt/sc_KnowledgeArticle?sfdcid=000131309 
      
      

    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://selfservice.bmc.com/casemgmt/sc_KnowledgeArticle?sfdcid=000133102

      

    Is jetty opening ports?

      

    On any browser access http://arserver:unsecureRESTPort/ and https://arserver:secureRESTPort/
    In both cases 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
     

      

    Frequent Questions

      

    Can AR server consume 3rd party REST API services?
    No, for the time being only publishing form AR server is in the product scope

    How can I consume AR server REST API from browser code? 
    There are 2 current options
    a. Install an http proxy like j2ep  Setting a proxy in tomcat, that will bypass the CORS problem
    b. Install an http server on jetty 
    Both options work but are unsupported.

    Either of these options will remove the CROSS-Origin problem (browser security feature) and then you can use this KB to call AR server REST API from eg: midtier
    http:// https://selfservice.bmc.com/casemgmt/sc_KnowledgeArticle?sfdcid=000129562 

    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>

      

     

      

     

     


    Article Number:

    000134172


    Article Type:

    Product/Service Description



      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles