X

Best Practices from Oracle Development's A‑Team

Invoking OCI REST APIs using POSTMAN

Oracle Cloud Infrastructure (OCI) is Oracle's next generation IaaS platform that enables building and running a wide range of applications and services in a highly available, hosted environment. OCI offers high-performance compute, storage, overlay virtual network, database, load balancing and numerous other capabilities.

One of the best features of OCI is that it uniformly presents all of its capabilities through the OCI UI Console, SDK, CLI and REST API.

In this blog we will explore how to invoke OCI REST APIs, and examine OCI's REST authentication scheme in detail. I will also provide a sample POSTMAN Collection and Environment script that automates most of the messy details and allows us to seamlessly call OCI APIs. 

If the reader is interested in invoking OCI REST API through cURL, please see my colleague Michael Shanley's blog here

 

Basics

In order to use any of the SDK, CLI or REST API, OCI has a few pre-requisites:

  1. Only an IAM User can can invoke the API. So make sure the users are created.

  2. Generate an RSA key pair and its fingerprint, as mentioned here .

  3. Make note of your OCI tenancy's OCID and the specific user's ( created in #1 above) OCID, as described here .

  4. Upload the generated RSA public key from the key pair , as described here .

  5. Generate the required header and authentication bits and invoke the API.

The steps 1-4 above are relatively straightforward.

Step 5 is already done for you if using the SDK or CLI, but the authentication pieces need to be constructed manually if invoking REST APIs manually, and that is what this blog post is mainly about.

In the sections below we will first understand the authentication scheme for invoking the OCI REST APIs, and then we will explore how we use POSTMAN to invoke the API.

 

OCI API Authentication Scheme

PS: Clients invoking OCI CLI or REST APIs cannot have its clock skewed more than 5 minutes from OCI, otherwise a 401 unauthorized error will be thrown.

PPS: OCI REST APIs require SSL TLS1.2 protocol.

OCI uses the IETF-draft-cavage-http-signatures-08 specification as its authentication scheme, which guarantees that the client is authenticated and the message integrity is preserved (HTTPS or SSL establishes confidentiality).

Understanding the above authentication scheme is a little challenging, below is a summary of the core requirements: 

  1. Generate Current Date

  2. Generate API_Key as “tenancyOCID/UserOCID/APIKeyFingerprint”

  3. Generate Signing String

    1. If POST/PUT , generate SHA256, base64 encoded hash of the body and include as part of signing string .

  4. Generate RSA Digital Signature of the SHA256 hash of the Signing String generated above.

  5. Set the formatted Authorization header that includes API Key, Digital Signature(from above step) and other parameters.

  6. Invoke the API with ‘Authorization’, ‘Date’, ‘Content-Type’, and ‘x-content-sha256’ hash of the body(3.a) as Header parameters.

 

Using POSTMAN to invoke OCI APIs

Postman is a GUI-based REST API invocation tool that is very popular among developers. However, even though Postman provides a lot of features, using the authentication scheme above for OCI REST APIs can be challenging.

Thankfully Postman allows automating such custom requirements using Sandboxes, Collections, and Environments.

Hence, I provide some scripts and steps below that can be used to allow invoking OCI REST APIs through Postman . Please follow the steps in the order described.

  1. Download the Postman Collections and Environment from github

  2. Import the environment into Postman using the 'Import' button at the top, and activate it by selecting it from the top right drop-down as shown below

  3. Open and Edit the newly imported environment, and set the variables tenancyId, authUserId, keyFingerprint and private Key. These are same as what we collected in the Basics section above.Also, make sure to set both Initial Value and Current Value of the variables. 

  4. Now import the two collections into Postman. 

  5. From the OCI_REST_INITIALIZATION collection, invoke the Initializer GET for 'jsrsasign-all-min.js' , which imports and initializes a required library jsrsasign for encryption and digital signatures. This is a one-time setup task. 

That's it. Now you can use the other oci_rest_collection to invoke any OCI REST APIs. The collection provides a sample GET and POST request, which can be extrapolated to invoke any OCI REST API. 

Just make sure that the OCI REST calls are executed as part of the OCI_REST_COLLECTION, as that collection contains the necessary javascript code to generate OCI's authentication header

Join the discussion

Comments ( 7 )
  • Abhijit Tuesday, June 4, 2019
    Thanks Ashish. This blogs is helpful and worked fine for me. One point worth mentioning is that the pre-request script will work only in the Postman Windows app. I first tried it in the Chrome Add-on app which didn't work. Anyways, Chrome app is deprecated recently.
  • Ashish Singh Wednesday, June 5, 2019
    Thanks for the feedback Abhijeet.
    I did not test the app using Chrome add-on, and you are right, the global variables may not be set correctly on the add-on postman.

    But as you say this is not an issue anymore as the add-on postman app is now deprecated.
  • VINAY AGARWAL Monday, July 15, 2019
    While i tried this i get the following error in postman app. Any suggestion?

    There was an error in evaluating the Pre-request Script: ReferenceError: KJUR is not defined
  • Eugene Monday, August 5, 2019
    Thanks very very much for the nice info
  • Rajat Gupta Wednesday, August 7, 2019
    Hi Ashish- Thank you for this post. Very nicely done!

    Request: It seems that the headers don't get pre-populated for new requests using the OCI environment. Can you please see if there's a way to achieve that? Thanks again!
  • Ashish Singh Wednesday, August 7, 2019
    Great feedback Rajat.
    I've made changes to the repository to make sure headers are not required to be manually populated anymore.
  • vinay Wednesday, October 30, 2019
    Hi, I was able to do till step-5 and I could see that the jsrsasign is set, but when invoking the OCI rest apis, i'm getting the error "There was an error in evaluating the Pre-request Script: undefined: undefined". Also, how can we specify the pass phrase for the private key?
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content