When you start working with a new software development kit (SDK), you might find yourself spending extra time performing initial authentication and the authorization setup steps to provision an API key and get it working with its corresponding cloud service. By design, this process is in keeping with security as a core design principle. However, to overcome some of the manual effort involved, we created a feature that lets you quickly download your API key. This feature saves you the time and hassle of numerous mouse clicks and keyboard commands when going between a web browser and your local system.
Before you get your API key, though, you need to take several actions in the Oracle Cloud Console for proper security and permissions. We made this blog post to help guide you through our documented setup tasks in the Console, so you can start working with the Oracle Cloud SDKs more quickly and use principles consistent with developing your app as part of your organization. To ensure that you’re ready before you start using the Oracle Cloud Infrastructure (OCI) SDKs, I'll walk you through the pinpoint spots in our documentation, screens in the Oracle Cloud Console, and commands to test with. It only takes a few minutes!
If you don’t already have an Oracle Cloud account, sign up for a free account. Are you new to the Oracle Cloud SDKs? If so, see the reference documentation and try them out in Cloud Shell, a Linux environment in Oracle Cloud with a browser-based console that comes with our SDKs preinstalled. My previous blog post walks you through using our SDKs immediately on the command line with Cloud Shell. You can also check out our SDK quick starts.
Now that you have an Oracle Cloud account, we have some prep work for it. Given our focus on security at Oracle, we need to create the proper permissions and policy that apply to our API key, which the SDK uses for communication with Oracle Cloud.
First, let’s create a compartment in your cloud tenancy, which we can work with as a sandbox. As you work with Oracle Cloud resources, you can use this compartment as a testing ground for utilizing the SDK to manage your infrastructure needs, such as virtual machines (VMs), Kubernetes clusters, and storage objects. We follow the naming conventions in the Adding Users section of our cloud documentation. In the menu in your Console, navigate to Identity, Compartments, then create a compartment.
Now, make a new group by selecting the main Console menu, then going to Identity and Groups. Click the Create Group button, fill in the following details, and click the Create button.
Let’s now make a policy for this group. We create a policy that allows users and their API keys in the group to act within our sandbox compartment. On the Identity screen, select Policies and then Create Policy. Use the following information to build a new policy. I chose the Customize (Advanced) option in the Policy Builder to include the following completed policy statement: “Allow group SandboxGroup to manage all-resources in compartment Sandbox". This will allow your API Key to take administrative actions in your Sandbox environment.
The next step is to create a user, then provision and download the API key. By creating a user account different from your own account, you can identify, track, and troubleshoot its SDK and API usage of your cloud account more easily than if you provision an API key for your own user account.
In your main Cloud Console menu, navigate to Identity, Users, then click the Create User button. Under Select User Type, change to IAM User, enter a name and description, and click Create.
After creating the user, you immediately see the user details, where you can Add User to Group under the Groups section at the bottom of the page. Select the sandbox group that you created previously, then click Add. If you navigate away, you can always come back to take this action by clicking Groups under the Resources section in the bottom-left of the page.
Next, we create an API key and generate a configuration file. In the bottom-left, under Resources, select API Keys, and click Add Public Key. On the next screen, select Generate API key Pair, then Download Private Key.
After you’ve downloaded the private key, place it in a location that’s both accessible by your local system and properly secured according to your organization’s guidelines. The app you’re developing with the SDK uses this private key to access Oracle Cloud.
Now click Add and you will be able to view your Configuration File.
Copy the text under Configuration File Preview and keep it handy.
At this point, you’re ready to use your API key and config file to start using the API. However, to ensure that your setup is correct, I walk you through using the Oracle Cloud command-line interface (CLI) to confirm that everything is working properly.
You can easily install the CLI using only a few commands, depending on your type of operating system. Typically, we run the oci setup config command to create a configuration with a corresponding file titled config (no file extension) in a new directory. Since we already have all the tenancy info we need from the previous step, we can skip this task and instead create a folder and file ourselves, depending on the type of operating system we have. If you’re running Windows, place the text into the following file and folder location: /Users/<YourName>/.oci/config.
If you’re running Mac OS X or Linux, place the file into a new folder in your home directory: ~/.oci/config. The only part you need to edit in this file is the line beginning with key_file, where you replace the template text with your private key’s location from the previous step. Your completed config file looks something like the following block:
[DEFAULT] user=ocid1.user.oc1..aaaaaaaa24bt4dgkuapa3odaegdrgx72ebmqhkhjya3mo1s5zuqg1kb23ozb fingerprint=10:f4:a4:bc:12:74:2b:16:ae:2f:0d:8f:34:6a:bb:3e key_file=/home/user-name/.keys/oci_api_key_test-dev-jan-2021.pem tenancy=ocid1.tenancy.oc1..aaaaaaaacjjo4moagtocccba2mbgmcp4g2d46v2lvbewa3wga2qxosqc1fgf region=us-phoenix-1
Now, let’s use a basic CLI command as a test. On your command line, type ‘oci iam compartment list.’ If you see a response in JSON format, your API key is valid.
Success! Your local system is now securely communicating with your Oracle Cloud tenancy, and you’re ready to set up your SDK language of choice.
If you’re curious about what else you can do with the CLI, check out some basic examples and our CLI command reference documentation. For more details, see the Setup and Prerequisites documentation. Now you’re ready to move to installing and configuring the SDK!
Not finding the SDK you need? Instead, try using the Oracle Cloud APIs to tackle your specific workflow.
We hope that this post saves you time in preparing your account and local system to work with Oracle Cloud with an API key. Send us your thoughts in the comments. Happy hacking!