In this blog post, we will explore the OCI Signature authentication to call an Oracle Cloud Infrastructure REST API. For this purpose, we will be using a simple GET API called ListInstances which returns a list of compute instances in a particular compartment.
Visual Builder (19.4.3 onwards) supports signing requests via Oracle Cloud Infrastructure API Signature version 1 authentication method ( More details can be found here) .
For this we require two parts:
Login to the OCI console for your tenancy. You can login with a user who is in a group that has been granted relevant privileges to list instances via IAM Policies (See the literature for more information about OCI users, groups and IAM policies). In this example, I am logging as a user who is in the OCI Administrators group which has access to manage all resources.
For this, we will note the Tenancy and the User OCIDs from the user's profile
Next we create a public and private API key pair. We will create a private key locally (i.e. on our computer) by using openssl utility (note: you need openssl with version 1.0.1 or higher )
openssl genrsa -out oci-fn-vb-privkeyenc.pem -aes128 2048
Enter/Re-enter a passphrase when prompted to encrypt the private key and note the passphrase for future use
This file oci-fn-vb-privkeyenc.pem is your encrypted private key. Now we will generate the corresponding public key for uploading to OCI
openssl rsa -pubout -in oci-fn-vb-privkeyenc.pem -out oci-fn-vb-pubkey.pem
Enter the correct passphrase when prompted.
Upload the public key to the OCI Console by navigating to User Settings -> API Key -> Add Public Key. Choose the file oci-fn-vb-pubkey.pem .
This should get uploaded and also generate a fingerprint for this particular key as shown below. Keep a note of the fingerprint.
Construct the key ID by using the following syntax
key ID = [TENANCY OCID]/[USER OCID]/[KEY FINGERPRINT]
As an example
We have the first part i.e. the key ID.
If you open the oci-fn-vb-privkeyenc.pem file, you will see the following lines in your file.
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: AES-128-CBC,E76204F69772B5958468790EEE41C8D5 dmQhVR08dVjd91ldj2q+2ASMd3tSLG0rfYl27hUSsjujK+FEJ7+4Jj+ozgif2LKf GF1EYyLO45FLW4r0lnH6pMrlMuLp5Dr1OWXEMVSRR6swaQG1dFPDZ9kVzDQkF4aQ 6bVeMpbW2jEsi6+V/0oQtLg7UdzrHnsKxRuo6326OKafzw5ICyCNL57w8yMwtl5i fo4vBCYktcf2Gyv/S154YSRXNAaIXt+P3pbkxJmpU73kZF4Q2KBxazEmi2FJM4F0 KU+5OkStQQ91/z0eUvv0c6L5cKMx1jDBUfyoGdqnQ4zlfVYWzouS2KEjUOCqeICp iGwcw57vOh+aHYqxnwTJRm3rMV7/nbjfIuJee5TCdD6Q5bazXxyLdeq3ER8wv1Q9 ............... -----END RSA PRIVATE KEY-----
This indicates this is an RSA encrypted key. We need to convert this into a PEM unencrypted key to be uploaded to VB
openssl pkcs8 -topk8 -in oci-fn-vb-privkeyenc.pem -out oci-fn-vb-privkey.pem -nocrypt
Now we will use the key ID and the oci-fn-vb-privkey.pem in the Service Connection
Another thing we need to list instances is the CompartmentId, which is the OCID of the compartment for which we need to fetch the compute instances. Navigate to Identity -> Compartments. Find out the compartment you are interested in and note down its OCID. We will be fetching the instances belonging to a compartment called oci-test which is nested within the root compartment
Login to Visual Builder. Create a Visual Application OCIServiceTest. In this, navigate to Service Connections and proceed to create a new Service Connection. Choose the Define by Endpoint category when prompted to select Source
In the Service Connection Wizard, choose as below :
Method : GET URL : https://[OCI Regional host]/[version]/instances (e.g. https://iaas.ap-mumbai-1.oraclecloud.com/20160918/instances) Action Hint : Get Many
In the next screen, the service name/id has been automatically populated. Change this to be a meaningful value. In my example the service is called ociListInstances1
Navigate to the Server tab. This holds all the configuration needed to connect to this endpoint.
Choose Authentication to be Oracle Cloud Infrastructure API Signature 1.0. This uses API Signature algorithm mentioned here
The Connection Type field, which is used to control the use of a Proxy or Direct call, is immaterial here. No matter what connection type you choose, the OCI Signature algorithm is such that it needs a server side proxy to be computed, and hence all requests to this Service Connection would go via Proxy.
Click on the pencil icon next to the API Key. There would be a place holder to put in the API Key (the Key ID) as well as the Private Key. Use the entire part of the Private Key including the BEGIN PRIVATE KEY till END PRIVATE KEY. Save the credentials
Since compartmentId is one of the mandatory parameters of ListInstances, we add it in Request -> Parameters tab in the section Dynamic Query parameters.
Next, test the endpoint connectivity by navigating to the Test Tab. Give the OCID of the compartment in the compartmentId URL parameter, and click Send
You should get a 200 OK response with a list of instances available in the compartment.
Finally, click on the create button to create the Service Connection.
That completes the setup of service connection from VB to an OCI REST API. You can now leverage this via a VB webapp or a mobile app.