In June, we launched the Oracle Cloud Infrastructure (OCI) SDK for TypeScript & JavaScript to enable you to work with all of your favorite cloud APIs directly from your TS & JS projects without having to resort to using REST APIs with a complex signing process. There are certainly times when it is preferable to manually sign your requests. For example, maybe you need to make a single call and you want to keep the codebase light you might want to avoid including the entire SDK dependency and sign the request manually (I've blogged about this before). However, there are also times when you need the full power of the SDK included in your projects. In those cases, you can now use both resource and instance principal authentication providers with the TS/JS SDK.

What is Instance Principal Authentication?

I've talked about instance principal auth many times here on this blog, but if you're new here (where have you been?!) I'll quickly go over it again as a refresher. There are many different ways to authenticate when using the OCI SDKs - for example, you can use your credentials directly in an authentication provider (SimpleAuthenticationDetailsProvider) or you can use a config file located on disk somewhere (ConfigFileAuthenticationDetailsProvider). Both of these solutions require you to provide the SDK with your credentials (either in the form of variables/strings or stored as text on the disk). This is usually not a problem when developing your application because you typically (hopefully) already have a config file on your local disk to work with the OCI CLI. If you were to use one of these auth methods when you deploy your application to a VM in the Oracle Cloud, you now have to manage these sensitive values somehow. This becomes another potential security vulnerability in your infrastructure if it is not properly managed. But, if you think about it, when you are deploying to a VM in the Oracle Cloud, shouldn't that VM know (or have access to) all of the necessary information about your tenancy that it needs to sign and authenticate your SDK calls? Well, it takes a small bit of configuration to enable it, but that's essentially what instance principal authentication is. The instance itself, when configured properly, uses a certificate that is frequently refreshed to sign the SDK requests so you do not have to worry about providing the credentials.

What is Resource Principal Authentication?

Resource principal auth, in theory, is very similar to instance principal auth but used for resources that are not instances such as serverless functions. The implementation is slightly different, but the goal is the same - to sign SDK requests from a function deployed to the Oracle Cloud in a way that does not require developer provided credentials. I'm sure you're anxious to read the docs about this, so here is the link to read more about resource principal auth. 

Working With Resource Principals

Let's look at an example of using resource principal authentication to utilize the Object Storage API to retrieve the tenancies namespace. The first step is to create our serverless application:

Next, create a function using Node:

Now switch to the newly created function directory and run npm install:

Oh, we'll also need the oci-sdk, so install that too:

Now we can start creating our function. As I covered above, normally we would have to rely on something like a ConfigFileAuthenticationDetailsProvider by using code similar to the snippet below:

This would require us to include our OCI config file in the Docker image, which means we'd have to include a manual Dockerfile in our function. And already we're getting complicated! Let's keep it simple.

That's much better! No config file dependency, no plain text credentials, no manual Dockerfile. The entire function illustrates just how easy it is to use resource principal auth with the TS/JS SDK:

Deploy the function:

And invoke it:

Which properly returns the namespace:

{"namespace":"toddrsharp"}

Working With Instance Principals

Let's take this very basic demo and use instance principal authentication instead. You can certainly turn up a VM to try this out, but I think it would be much easier to run it directly in Cloud Shell since it has Node and NPM installed already and we don't have to make any other changes to try it out. Open Cloud Shell, create a directory, switch to it, run npm init and then install the oci-sdk:

Now open up a file called index.js in your preferred text editor and enter the following:

This code is very similar to the serverless example above, but note the use of InstancePrincipalsAuthenticationDetailsProviderBuilder instead of ResourcePrincipalAuthenticationDetailsProvider. Save it, and run it to see the expected output:

Summary

In this post, we looked in depth at instance and resource principals. We learned why they exist and demonstrated a simple use case of each authentication type. If you have any questions, leave a comment below or, as always, connect on Twitter @recursivecodes.

Photo by chris panas on Unsplash