Oracle Cloud

Thinfinity® Cloud Manager connects to Oracle Cloud Infrastructure (OCI) using either API Key-based authentication (the default, using a PEM private key and a set of OCI identifiers) or Instance Principal authentication, which allows a Compute instance to authenticate without static credentials. This article documents the Cloud Manager credential form for OCI, the minimum IAM permissions, and common configuration errors.

Info

All API calls from Cloud Manager originate from the Thinfinity® Workspace server. Ensure outbound HTTPS (port 443) is open from that host to the OCI API endpoint for your region (e.g., iaas.us-ashburn-1.oraclecloud.com). See Prerequisites for the full network requirements.

Prerequisites

Before adding OCI credentials in Cloud Manager, the following must be in place on the OCI side:

An active OCI account and access to the OCI Console with permissions to create users, API keys, and manage IAM policies.
The target Compute instances reside in an OCI region reachable from the Thinfinity Workspace server.
For API Key authentication:
- A dedicated IAM user for Cloud Manager, with an uploaded API Signing Key. The private key (.pem file) is downloaded only once at creation — store it securely.
- The Tenancy OCID, User OCID, the API key fingerprint, and the target region identifier.
For Instance Principal authentication:
- The Thinfinity Workspace server is an OCI Compute instance.
- That instance belongs to a Dynamic Group.
- An IAM policy grants the Dynamic Group the required Compute permissions.
The IAM user (or Dynamic Group) must be granted the IAM permissions listed in Minimum IAM Permissions below.

For how to create users, generate API signing keys, set up Dynamic Groups, and write IAM policies, refer to the OCI Identity documentation.

Minimum IAM Permissions

The IAM user or Dynamic Group must be granted permissions equivalent to the following policy verbs.

Policy Verb	Required For
`read instance-images`	All operations
`use virtual-network-family`	All operations
`use instances`	Managed VMs — start, stop, connect to existing instances
`manage instances`	VDI/DaaS Models — start, stop, terminate, and launch new instances

Info

The manage instances verb covers start, stop, terminate, and launch. If Cloud Manager will only manage existing VMs (Managed VMs), use instances plus read instance-images and use virtual-network-family is sufficient. Scope policies to a specific compartment rather than the full tenancy where possible.

Authentication Methods

Method	When to Use
API Key	Works from any server, including on-premises or non-OCI-hosted Workspace servers. Requires an OCI user, a PEM key pair, and an uploaded public key.
Instance Principal	Keyless. Recommended when the Thinfinity Workspace server runs as an OCI Compute instance. No static credentials required.

Option A — API Key Authentication

Add the Credentials in Cloud Manager

In Cloud Manager, go to Credentials and click + New.
Select Oracle Cloud as the provider.
Ensure Use Instance Principal is set to false.
Fill in the fields below and click Save.

For the full Add / Edit / Delete procedure, see Managing Credentials.

Credential Fields

Field	Description
Use Instance Principal	Set to false to use API Key authentication.
Tenancy ID	The OCID of the OCI tenancy. Format: `ocid1.tenancy.oc1..aaaa...`.
User ID	The OCID of the Cloud Manager IAM user. Format: `ocid1.user.oc1..aaaa...`.
Private Key (.PEM file)	Upload the private key file generated when the API key was created in OCI. Cloud Manager uses this to sign all API requests.
Fingerprint	The MD5 fingerprint of the API Signing Key uploaded to the OCI user profile. Format: `xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx`.
Region	Dropdown of OCI regions. Select the region where your target Compute instances reside (e.g., `us-ashburn-1`, `eu-frankfurt-1`).

Option B — Instance Principal Authentication

Use this method when the Thinfinity Workspace server runs as an OCI Compute instance. Cloud Manager authenticates using the instance’s identity — no static keys required.

Add the Credentials in Cloud Manager

In Cloud Manager, go to Credentials and click + New.
Select Oracle Cloud as the provider.
Set Use Instance Principal to true. The API Key fields (Tenancy ID, User ID, Private Key, Fingerprint) are hidden — they are not needed when authenticating as the host instance.
Fill in the fields below and click Save.

For the full Add / Edit / Delete procedure, see Managing Credentials.

Credential Fields

Field	Description
Use Instance Principal	Set to true to use Instance Principal authentication.
Region	Dropdown of OCI regions. Select the region where your target Compute instances reside (e.g., `us-ashburn-1`, `eu-frankfurt-1`).

Verification

After saving, Cloud Manager validates the credentials by listing Compute instances in the selected region and tenancy. If validation succeeds, the credential status shows as Ok. If it fails, review the error and refer to Common Errors below.

Common Errors

Error	Likely Cause	Resolution
`401 - NotAuthenticated`	The private key does not match the public key uploaded to OCI, or the fingerprint is incorrect.	Verify the fingerprint in the OCI user’s API Keys view. Re-upload the key pair if needed.
`404 - NotAuthorizedOrNotFound`	The Tenancy ID or User ID OCID is incorrect, or the user lacks IAM permissions.	Verify the OCIDs and check the IAM policy against the Minimum IAM Permissions table.
`InvalidParameter: region`	The selected region is invalid or not subscribed to in the tenancy.	Verify region availability in the OCI Console.
Instance Principal failure	The Workspace instance is not in the Dynamic Group, or the policy is missing.	Verify Dynamic Group membership and the associated IAM policy.
Connection timeout	The Workspace server cannot reach the OCI API endpoint for the selected region.	Check firewall and proxy settings. See Prerequisites.

Security Recommendations

Use Instance Principal when the Thinfinity Workspace server runs on OCI — it eliminates the risk of static key exposure entirely.
Scope IAM policies to a compartment, not the full tenancy, when all Cloud Manager resources reside in a single compartment.
Rotate API keys periodically. OCI allows up to three API keys per user, enabling zero-downtime rotation.
Enable OCI Audit service to monitor all API calls made by the Cloud Manager user or Dynamic Group.

See Also