Oracle Cloud Infrastructure Documentation

Token-based Authentication for the CLI

Token-based authentication for the CLI allows customers to authenticate their session interactively, then use the CLI for a single session without an API signing key. This enables customers using an identity provider that is not SCIM-supported to use a federated user account with the CLI and SDKs.

Requirements

The requirements are the same as those listed for the CLI in Requirements, except that instead of a SSH keypair, you need a web browser for the authentication process.

Starting a Token-based CLI Session

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

  1. In the CLI, run the following command. This will launch a web browser.
    oci session authenticate
  2. In the browser, enter your user credentials. This authentication information is saved to the .config file.

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.

Refreshing a Token

The default token TTL is set to 1 hour before it expires and can be refreshed within the validity period up to 24 hours.

To refresh the token, run the following command:

oci session refresh --profile <profile_name>

Starting a Token-based CLI Session without a Browser

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 Starting a Token-based CLI Session, use the following process.

Note

These code samples demonstrate how to accomplish this using the Python SDK. For other SDKs, follow the same process, but adjust the syntax accordingly.

  1. Read the token file from the security_token_file parameter of the .config file.
  2. 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()
  3. Read the private key specified by the .config file.
  4. private_key = oci.signer.load_private_key_from_file(config['key_file'])
  5. Create the initial SDK client which targets the user-specified region.
  6. signer = oci.auth.signers.SecurityTokenSigner(token, private_key) 
    client = oci.identity.IdentityClient({'region': region}, signer=signer)
  7. Make the identity request.
  8. result = client.list_region_subscriptions(config['tenancy'])