TheKoguryo's Tech Blog

14.3.4 Postman - Calling OCI REST API

Postman, the most used professional REST client tool, is more convenient to use through a GUI. Since OCI Request Signature is not yet natively supported, I would like to explain how to call OCI REST API using Postman’s pre-script.

To make a call through OCI Request Signature, Postman must use pre-script. Like Insomina, it does not provide plug-in functionality. Pre-script can be set in units of REST request, and can also be set in units of folders and collections.

If pre-script is set in a folder, pre-script is executed first before all REST requests under the folder. For ease of administration, we will use the pre-scripts in the folder.

Step 0. Download Postman

Download the app from the official site.

• https://www.postman.com/downloads/

Step 1. Load RSA library to be used in pre-script

※ Loading external RSA JavaScript library The Cryto library included by default in pre-script does not support RSA encryption used by OCI Request Signature. So, add an external encryption library by bypassing it in the following way.

1. Make a GET request

   • Target URL: http://kjur.github.io/jsrsasign/jsrsasign-latest-all-min.js

2. Copy the following to the Test tab

   pm.globals.set("jsrsasign-js", responseBody);
   

3. Execute the request

4. Execution result

   When executed as below, the encryption module is saved in the Postman global variable (jsrsasign-js).

   

Step 2. pre-script setting

1. Create a folder to contain the REST requests.

2. Right-click on the folder name and click Edit

   
   

3. Select the Pre-request Scripts tab in the folder settings.

   
   

4. Copy and paste the following JavaScript.

   var navigator = {}; //fake a navigator object for the lib
   var window = {}; //fake a window object for the lib
   eval(pm.globals.get("jsrsasign-js")); //import javascript jsrsasign
   
   const isOracleCloud = pm.environment.get("isOracleCloud");
   
   if (isOracleCloud != "true")
     return;
   
   const tenancyId = pm.environment.get('tenancyId');
   const authUserId = pm.environment.get('authUserId');
   const keyFingerprint = pm.environment.get('keyFingerprint');
   
   var privateKey = pm.environment.get("privateKey");
   
   var signAlgorithm = "RSA-SHA256";
   var sigVersion = "1";
   var now = new Date().toUTCString();
   var host = getHost(request.url.trim());
   var target = getTarget(request.url.trim());
   var method = request.method;
   var keyId = tenancyId + "/" + authUserId + "/" + keyFingerprint;
   
   var headers = "(request-target) date host";
   var request_target="(request-target): " + method.toLowerCase() + " "  + target;
   var date_header = "date: " + now;
   var host_header = "host: " + host;
   
   var signing_string = request_target + "\n" + date_header + "\n" + host_header;
   
   var methodsThatRequireExtraHeaders = ["POST", "PUT"];
   
   if(methodsThatRequireExtraHeaders.indexOf(method.toUpperCase()) !== -1) {
     var body = request.data;
     console.log(body);
   
     var signatureSign = CryptoJS.SHA256(body);
     var content_sha256 = signatureSign.toString(CryptoJS.enc.Base64);
   
     var content_type = "application/json";
     var content_length = body.length;
   
     headers = headers + " x-content-sha256 content-type content-length";
     var content_sha256_header = "x-content-sha256: " + content_sha256;
     var content_type_header = "content-type: " + content_type;
     var content_length_header = "content-length: " + content_length;
   
     signing_string = signing_string + "\n" + content_sha256_header + "\n" + content_type_header + "\n" + content_length_header;
   
     pm.environment.set("x-content-sha256_header", content_sha256);
   
   }
   
   // RSA signature generation
   var signatureSign = new KJUR.crypto.Signature({"alg": "SHA256withRSA"});
   signatureSign.init(privateKey);
   signatureSign.updateString(signing_string);
   var signedSignatureHex = signatureSign.sign();
   
   var signedSignature = hexToBase64(signedSignatureHex);
   
   const authorization = `Signature version="${sigVersion}", keyId="${keyId}", algorithm="${signAlgorithm.toLowerCase()}", headers="${headers}", signature="${signedSignature}"`;
   
   pm.environment.set("date_header", now);
   pm.environment.set("Authorization_header", authorization);
   
   function getHost(url) {
     // https://identity.us-ashburn-1.oraclecloud.com/20160918/users/
     var n1 = url.indexOf("//");
     var n2 = url.indexOf("/", n1 + 2);
   
     var start = n1 + 2;
     var length = n2 - start;
   
     var host = url.substr(start, length);
   
     return host;
   }
   
   function getTarget(url) {
     // https://identity.us-ashburn-1.oraclecloud.com/20160918/users/
   
     url = url.replace(new RegExp('^https?://[^/]+/'),'/'); // strip hostname
   
     return url;
   }
   
   function hexToBase64(hexstring) {
       return btoa(hexstring.match(/\w{2}/g).map(function(a) {
           return String.fromCharCode(parseInt(a, 16));
       }).join(""));
   }
   

Step 3. Setting environment variables

1. Required environment variables
   • isOracleCloud: Set to “true”, the set plugin is applied globally, and the detailed script works only when true.
   • tenancyId: tenancy OCID
   • authUserId: User OCID
   • keyFingerprint: Fingerprint of API Key
   • privateKey: Copy and paste the text of the private key that matches the public key registered with the API key.
     

Step 4. Run User Query REST API

1. Make a REST request under the folder you created earlier.

2. Select the environment variable set in the upper right corner.

3. Add date and Authorization to Header of REST request as shown in the figure.

   • date : {{date_header}}
   • Authorization : {{Authorization_header}}
   • Actual values ​​of date and Authorization are set at the time of execution while pre-script is executed.
   • Except for POST and PUT, set only the above two HTTP operations.

4. Execution result

Step 5. Run REST API - CreateUser

1. Make a REST request under the folder you created earlier.

2. Select the environment variable set in the upper right corner.

3. Add date and Authorization to Header of REST request as shown in the figure.

   • date : {{date_header}}
   • Authorization : {{Authorization_header}}
   • Content-Type : application/json
   • x-content-sha256 : {{x-content-sha256_header}}
   • Except for Content-Type, the three actual values ​​are set at the time of execution as the pre-script is executed.
   • For POST and PUT, set the above four. This is because there is a request message, so the request message is also added to the signature.

4. Execution result

5. When requesting with POST or PUT, copy and write the above REST request.

References

Refer to the following link for the use of external RSA JavaScript library in Postman’s pre-script.

• https://github.com/postmanlabs/postman-app-support/issues/1607#issuecomment-401611119