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:
- In the terminal, run the following command:
oci session authenticate
- Select a region.
- In the browser, enter your user credentials.
- 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:
-
API key based authentication (oci setup config)
-
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
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.
oci session authenticate --no-browser --public-key-file-path <path-to-public-key> --profile <profile_name> --auth security_token
--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
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 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
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>
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:
- In the CLI, run the following command:
oci session authenticate
- Enter the user credentials you wish to use on the target computer.
- 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.
This method only works for the OCI SDKs for Go and Python. The following example is for the Oracle Cloud Infrastructure SDK for Python:
- 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()
- Read the private key specified by the
.config
file.private_key = oci.signer.load_private_key_from_file(config['key_file'])
- 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)
- Make the identity
request.
result = client.list_region_subscriptions(config['tenancy'])