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

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

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

What is postman

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

1. Scripting: A whole scenario can be run with a single script: eg login, store the token in memory, reuse it for further operations and logout. 
2. Command line: Usable when graphic clients are not feasible
3. Java based
4. SSL strict enforcement: This would help to prepare for SSL during development

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 from 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>

For further REST API material