How to Use the Secret Key Authentication with REST API?

CA Service Desk Manager's REST API supports Secret Key Authentication. For more information, see REST HTTP Methods -REST Secret Key Authentication. This article gives a high-level overview and other considerations while implementing the Secret Key Authentication in CA SDM REST API.
casm1401
CA Service Desk Manager's REST API supports Secret Key Authentication. For more information, see REST HTTP Methods -REST Secret Key Authentication. This article gives a high-level overview and other considerations while implementing the Secret Key Authentication in CA SDM REST API.
Prerequisites and Considerations
Consider the following before you implement the Secret Key Authentication in CA SDM REST API: 
  1. Ensure there is communication between the client (a third-party program of your choice) and the SDM REST server. You must first consider implementing the HTTPS between these two components. You can secure the CA SDM REST Tomcat using an SSL certificate and use that certificate + HTTPS URL when connecting from the client.
  2. CA SDM must be configured to Support
    HMAC_ALGORITHM
    . Login to CA SDM,
    Administration
    ,
    Options Manager, Web Services, hmac_algorithm
    .
    This option can be set to a preferred value. Install the option (In this case, it is set to
    hmacSHA1
    ). Follow the required steps that you usually perform while installing a CA SDM Option. 
  3. The CA SDM
    secret_key
    is a 40-character alphanumeric sequence and is dynamically generated by CA SDM during REST access key creation. This
    secret_key
    is encrypted before it is stored in the CA SDM database (
    usp_rest_access table
    ).
  4. The
    secret_key
    needs to be used thereafter by the client to be able to properly authenticate itself as a valid client against the CA SDM REST server. This is performed by the client program which sends a Signed Header as part of its requests.
  5. The signature, a Keyed-Hash based Message Authentication Code (
    HMAC - Hash-based Message Authentication Code
    ) is calculated using the following:
    1. the
      Secret_Key
    2. the header fields (for example:
      date
      ,
      accept
      ) provided by
      NX_STRING_TO_SIGN_FIELDS
      (if the option is not installed in the same order.
    3. the cryptographic hash function provided by NX.env variable
      NX_HMAC_ALGORITHM
      (supported algorithms are
      HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512
      and
      HmacMD5
      ).
  6. Client sends the request data, the signature and the Access Key to CA SDM.
  7. CA SDM uses the Access Key to look up the Secret Key from persistence store.
  8. CA SDM uses the request data and the Secret Key to generate the signature using the same hash algorithm the Client used.
  9. If the signature generated by CA SDM matches the signature sent by the Client, then the request is considered authentic, otherwise the request is discarded and CA SDM returns an error response.
  10. The installation folder contains few samples in 
    $NX_ROOT/samples/sdk/rest/java/test2_auths
    withREADME.txt in 
    $NX_ROOT/samples/sdk/rest/java‘SampleSDMAuth.java’, ‘SampleUsingSecretKey.java’ and ‘HMACUtil.java
    ’.
Create Access Key and Secret from CA SDM REST API: 
The client must obtain an access_key and secret_key from SDM REST API. This is done by doing a
POST to /caisd-rest/rest_access
. Below procedure was created by using the Postman extension of Chrome. For more instructions on how to use Postman, check out this article or search for Postman on the Google Chrome webstore. 
 
  1. First the client needs to obtain an access_key and secret_key from CA SDM REST API.
    This is done by doing a POST to
    /caisd-rest/rest_access.
    1. Set your Authorization Type to: Basic Auth
    2. Populate a Username / Password with correct values
    3. Click on
      Update Request
      button.
  2. Change the
    Type now
    to  
    No Auth
     and click the
    Save
    button.
  3. Switch to the
    Headers
    tab and ensure that the Authorization shows up as Basic with a base-64 encrypted string next to it.
  4. Change string "
    Basic
    " to "
    SDM
    ",  leave the rest of the base64 string as is.
    There is a space character after Base,  leave it as is.
  5. Click
    Save
    .
    Basically , the Authorization header must be in the format: the string "SDM" space and the base-64 encoded username/password of a CA SDM User.
     In the above example its like this:
  6. Click 
    Send
     to send the POST to the CA SDM REST server. 
    POST /caisd-rest/rest_access HTTP/1.1
    Host: YourSDMHostName:8553
    Authorization: 
    SDM
     
    cnVkcmEwMjpJbmRUciFwMjAxNw==
    Content-Type: application/xml
    x-obj-attrs: access_key,secret_key,content-type,date
    Cache-Control: no-cache
     
    <rest_access></rest_access>
  7. CA SDM Server gives the following response:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <rest_access id="400502" REL_ATTR="400502" COMMON_NAME="845787692">
    <link href="http://localhost:8050/caisd-rest/rest_access/400502" rel="self"/>
    <access_key>845787692</access_key>
    <expiration_date>1503521363</expiration_date>
    <secret_key>2504166E48DC19294B86773F798DEE7996D3973E</secret_key>
     
    </rest_access>
  8. Use the
    secret_key
    as well as the
    access_key
    to make rest of the REST operations that we need.
    For this, do the HMAC encryption of the string that you need to request. This is done by creating a Pre-Request script section of Postman. For example - try to get some attributes from the "cnt"  object of SDM REST API as following:
    var str = "GET\n/caisd-rest/cnt"
    var secret = "2504166E48DC19294B86773F798DEE7996D3973E";
    postman.setGlobalVariable("hmac", encodeURIComponent(CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA1(str, secret))));
    Here the secret key is what we got as a response for
    step 6
    above.
    You can leave the rest of the information as is. This is basically going to encrypt the resource string:
    GET\n/caisd-rest/cnt
    and the secret key together and encode it using the
    HmacSHA1
    algorithm.
  9. Navigate to the
    Authorization
    tab and change the
    Authorization
    to look like the following:
    SDM 845787692:{{hmac}}
    Here, it is a literal string of CA SDM followed by a space, followed by the access-key from CA SDM that we obtained in
    Step 6
    , followed by literal string
    :{{hmac}}
  10. Ensure that the
    GET
    section contains
    /caisd-rest/cnt
    as the resource, because that is what is encrypted in the pre-request script.
  11. Add the
    X-Obj-Attrs
    header key with values:
    userid,last_name
    (basically we are trying to get the userid, last_name field values from the resource: /caisd-rest/cnt ). Your code should look like the following:
    GET /caisd-rest/cnt HTTP/1.1
    Host: SDMHostName.ca.com:58553
    Authorization: SDM 1842290659:jkd32qsCPwaBcWH0NX93V8zu6sI%3D
    Content-Type: application/xml
    X-Obj-Attrs: userid, last_name
    Cache-Control: no-cache
  12.  Save and send.
  13. The following response is received:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <collection_cnt COUNT="25" START="1" TOTAL_COUNT="36">
    <link href="http://localhost:8050/caisd-rest/cnt?start=26&amp;size=25" rel="next"/>
    <link href="http://localhost:8050/caisd-rest/cnt?start=1&amp;size=36" rel="all"/>
    ..
    ..
     
    ..
    <cnt id="U'793ED69B4E87A545BD8E911834D829FC'" REL_ATTR="U'793ED69B4E87A545BD8E911834D829FC'" COMMON_NAME="System_AHD_generated">
    <link href="http://localhost:8050/caisd-rest/cnt/U'793ED69B4E87A545BD8E911834D829FC'" rel="self"/>
    <last_name>System_AHD_generated</last_name>
    <userid>ahd</userid>
    </cnt>
    <cnt id="U'7A0E651346BF0E4491EBD37D13962417'" REL_ATTR="U'7A0E651346BF0E4491EBD37D13962417'" COMMON_NAME="System_Argis_User">
    <link href="http://localhost:8050/caisd-rest/cnt/U'7A0E651346BF0E4491EBD37D13962417'" rel="self"/>
    <last_name>System_Argis_User</last_name>
    <userid>System_Argis_User</userid>
     
    </cnt>
    ..
    ..
     
     
    </collection_cnt>