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.
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.
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
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:
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
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:
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.