Oracle Cloud Infrastructure Documentation
Try Free Tier

Token-based Authentication for the CLI

Token-based authentication for the CLI allows you to create a temporary session token which can be used to authenticate a CLI command request. You can generate this token with or without using a web browser.

Requirements

The requirements are the same as those listed for the CLI in Requirements.

Creating a CLI Session with a Browser

To use token-based authentication for the CLI on a computer with a web browser:

  1. In the terminal, run the following command: 
    oci session authenticate
  2. Select a region.
  3. In the browser, enter your user credentials.
  4. After successful authentication, close the browser and follow interactive prompt on the terminal. A configuration file will be created.

Creating a CLI Session without a Browser

To generate a user token without a browser, you must first authenticate with one of the following methods:

  1. API key based authentication (oci setup config)

  2. Session token based authentication (oci session authenticate)

API key-based authentication

To use token-based authentication for the CLI without a web browser, run the following command:

oci session authenticate --no-browser

This command creates a public/private key pair and updates the private key file location in .config file.

Session token-based authentication

If you are using a session token:
oci session authenticate --no-browser --auth security_token

Optional arguments

For both the API key-based and session token-based authentication, you can provide a path to a public key as an argument. This provides a session token which can be signed by corresponding private key while using the generated token.

In the CLI, run the following command:
oci session authenticate --no-browser --public-key-file-path <path-to-public-key> --profile <profile_name> --auth security_token
You can control the time for which the token persists. The minimum time for which token persists is 5 minutes and the maximum time for token persistence is 60 minutes (the default value). To setup a custom session expiration for the token, use the parameter --session-expiration-in-minutes. For example:
oci session authenticate --no-browser --session-expiration-in-minutes <token-persistence-time-in-minutes> --profile <profile_name> --auth security_token
Note

If you require multiple user tokens, run the no-browser token based authentication again with oci session authenticate --no-browser.

Validating a Token

To verify that a token is valid, run the following command:

oci session validate --config-file <path_to_config_file> --profile <profile_name> --auth security_token
You should receive a message showing the expiration date for the session. If you receive an error, check your profile settings.
Note

You must use the --auth security_token or set the OCI_CLI_AUTH environment variable to security_token to authenticate CLI commands using the session token.

Refreshing a Token

The default token expiration time is set to 1 hour, and can be refreshed within the validity period up to 24 hours.
Note

For sessions authenticated using oci session authenticate --no-browser, the maximum value is 60 minutes.

To refresh the token, run the following command:

oci session refresh --profile <profile_name>
Note

You must use the --auth security_token or set the OCI_CLI_AUTH environment variable to security_token to authenticate CLI commands using the session token.

Copying a CLI Session Token to Another Machine

To use token-based authentication for the CLI on a computer without a web browser, you must export a session from a web-enabled computer, then import it to the computer without a web browser.

Exporting from Source Computer

On the source computer with the browser:

  1. In the CLI, run the following command: 
    oci session authenticate
  2. Enter the user credentials you wish to use on the target computer.
  3. To export a zip file, run the following command: 
    oci session export --profile <profile_name> --output-file <output_filename>

To verify the export, see Validating a Token.

Importing to Target Computer

On the target computer without the browser, run the following command in the CLI,:

oci session import --session-archive <path_to_exported_zip>

You can test the import by running the following:

oci iam region list --config-file <path_to_config_file> --profile <profile_name> --auth security_token

It should return a list of regions. Successful execution of this command verifies that the token authentication is working as expected.

Running Scripts on a Computer without a Browser

After importing the authentication to the target computer, you can run the CLI and SDKs by using the following settings.

For CLI

To run scripts on the CLI, append the following suffix:

--config-file <path_to_config_file> --profile <profile_name> --auth security_token

For SDKs

To run SDKs on the target computer, you must read in the token file, then use it to initialize the SecurityTokenSigner.

After creating a token file as shown in Creating a CLI Session with a Browser, use the following process.

Note

This method only works for the OCI SDKs for Go and Python. The following example is for the Oracle Cloud Infrastructure SDK for Python:
  1. Read the token file from the security_token_file parameter of the .config file. 
    config = oci.config.from_file(profile_name='TokenDemo')
token_file = config['security_token_file']
token = None
with open(token_file, 'r') as f:
     token = f.read()
  2. Read the private key specified by the .config file.
    private_key = oci.signer.load_private_key_from_file(config['key_file'])
  3. Create the initial SDK client which targets the user-specified region.
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key) 
client = oci.identity.IdentityClient({'region': region}, signer=signer)
  4. Make the identity request.
    result = client.list_region_subscriptions(config['tenancy'])

Was this article helpful?