Enabling Any Federated User to Invoke the Oracle Cloud Infrastructure SDK and CLI

At Oracle, we’ve been focused on improving our identity federation support for enterprises that integrates seamlessly with Oracle Cloud Infrastructure. We want you to be able to use your existing identity provider (IdP) to access the Oracle Cloud Infrastructure Console, SDK, and CLI.

In the past few months, we’ve delivered SDK and CLI access to users federated through Oracle Identity Cloud Service (IDCS) and Okta.

Today, I’m excited to introduce the token-based CLI and SDK, which allows any federated user to invoke the CLI and SDK. This feature uses a CLI command that allows you to log in by using a web browser for CLI and SDK sessions.

When to Use the Token-Based CLI Versus API Signing Keys

Oracle Cloud Infrastructure already supports API signing keys, which allow a local user to access the SDK and CLI. So when would you use the token-based CLI versus API signing keys? This section provides some use cases.

Flexibility to Support Any Identity Provider

Currently, API signing keys are supported only by Okta and SCIM. Therefore, if you use any other IdP, you can use the token-based CLI to enable CLI and SDK access to Oracle Cloud Infrastructure.

User Interactive SDK and CLI Sessions

After API signing keys are set up, they can support user interactive sessions. However, token-based CLI access is ideal for sessions in which user interaction is required because, by default, it uses a web browser to authenticate each user.    

For example, say that you need to tag a few databases and you want to do it interactively. If you use the token-based CLI, you can enter your username and password in the web-based login page and then use the CLI to perform the tagging tasks. The session lasts one hour, but you can refresh it without using the web browser for up to 24 hours. The exact length of time depends on your IdP.

What About Headless Computers?

You might have administrative computers from which you want to run Oracle’s CLI but that don’t have web browsers installed. You can still use the token-based CLI with those computers. You first create an authenticated session on a computer with a web browser, and then using the token-based CLI, you export this session and then import it on the headless computer.

Users who are logged in to the headless computer can still refresh the token session without having a web browser by using the oci session refresh command. This can usually be done for up to 24 hours, but again, the exact duration depends on your IdP.

Automated Jobs That Don't Require User Interaction

API signing keys are ideal for automated jobs, for example, jobs that run at 3 a.m. and don't require user interaction. A token-based CLI is not well suited for automated jobs because there is no recommended way to authenticate the session without user interaction.

Key Management Considerations

API signing keys must be distributed, rotated, and managed. The API signing key is a public/private key pair, and you need that private key on any machine that runs the CLI or SDK. This might be a concern because you now have to manage private keys.

If you want a solution that requires simpler administration, consider the token-based CLI. It uses ephemeral keys that last only a short time. You don’t need to worry about distribution and key rotation, which might be significantly easier to administer for your organization.

The following chart summarizes the preceding use cases:

Using the Token-Based CLI and SDK

The token-based CLI and SDK allows any federated user to invoke the Oracle Cloud Infrastructure CLI and SDK. To use this feature, run the oci session authenticate command from the CLI. This command brings up a web browser, which you can use to authenticate the session. When the session is authenticated, you can then run CLI and SDK commands.

SDK Support

To generate an authenticated session that the SDK can use, use oci session authenticate and then, from that command window, call your SDK script. You need to also change how your SDK script uses the signer. For information, see the documentation.

PowerShell Tip

Here’s a tip that will save you typing in PowerShell, and I’m sure there’s an equivalent in UNIX and MacOS. If you get tired of appending the profile and auth parameters to your CLI calls, you can write a one-line function in PowerShell that do the appending for you. The only prerequisite is that you use the same profile name every time that you authenticate.

Write a PowerShell function and save it to your PowerShell profile:

function toci {oci @args --profile TokenDemo --auth session_token}

This function writes an alias called toci that always appends --profile TokenDemo and --auth session_token. So instead of typing this:

oci <oci_command>  --profile TokenDemo --auth session_token

You just type this:

toci <oci_command>

To make this work, you need to specify the profile name you used in the function—in my case, TokenDemo—as your profile every time you call oci session authenticate.

Thanks for reading, and stay tuned for more authentication features coming soon.