Connect Oracle Cloud (OCI)

Connecting an OCI tenancy lets Retrievy's CSPM scanner audit your Oracle Cloud Infrastructure. OCI uses API signature authentication, which is more steps than the OAuth flows on Azure or M365, but it's the most-supported model on OCI and works with every region and tenancy type.

OCI does not support a Quick Connect path today. Manual credential entry is the only supported flow.

caution

Live API validation for OCI is a roadmap item. Today Retrievy validates the credential shape when you save (every required field present and properly formatted) but does not call OCI's API at save time. The connection is exercised for real on the first scan. If your credentials are wrong, the scan reports the auth failure within minutes of the first run.

Before you start

You need:

• An OCI tenancy where you can create users, groups, policies, and API signing keys.
• A Retrievy workspace with CSPM enabled (every plan).
• The manage-cloud-accounts permission in Retrievy.
• One free data-source slot on your plan.
• A way to generate an RSA key pair (the openssl CLI works fine, or any tool that produces a 2048-bit RSA key in PEM format).

How OCI authentication works

OCI doesn't use bearer tokens or shared secrets. Every API call is signed with a private key whose corresponding public key is registered against a user in your OCI tenancy. Retrievy stores the private key, signs requests, and OCI validates the signature against the public key you uploaded.

The five fields you'll need to give Retrievy:

Field	Where to get it	Format
Tenancy OCID	Tenancy overview page in OCI console.	ocid1.tenancy.oc1..aaaa...
User OCID	The user you create for Retrievy in step 2.	ocid1.user.oc1..aaaa...
Fingerprint	Generated when you upload the public key in step 3.	aa:bb:cc:dd:... (hex with colons)
Region	Your tenancy's home region or the region you want scanned first.	us-ashburn-1, eu-frankfurt-1, etc.
Private Key	The PEM file from the key pair you generate in step 3.	Begins with -----BEGIN RSA PRIVATE KEY-----

Step 1. Create a group and policy

Best practice on OCI is to grant permissions to groups, not individual users.

In the OCI console:

1. Open Identity & Security → Groups → Create Group.

2. Name: retrievy-readers. Description: Read-only group for Retrievy CSPM scans. Click Create.

3. Open Identity & Security → Policies → Create Policy.

4. Name: retrievy-read-only. Description: same as above. Pick the root compartment as the scope so the policy applies to the entire tenancy.

5. Switch to Show manual editor and paste:

   Allow group retrievy-readers to read all-resources in tenancy
   Allow group retrievy-readers to read audit-events in tenancy

6. Click Create.

That policy gives the group read-only access to every resource and to the audit log, with no write permissions anywhere.

Step 2. Create the user

1. Open Identity & Security → Users → Create User.
2. Type: IAM User.
3. Name: retrievy-cspm-reader. Description: same.
4. Leave email blank or use a shared mailbox. Click Create.
5. On the new user's detail page, scroll to Groups → Add user to group → pick retrievy-readers. Click Add.
6. Copy the OCID from the user's detail page. You'll paste it into Retrievy in step 4.

Step 3. Generate an API signing key

On any machine with openssl:

# Create a private key (keep this file secret)
openssl genrsa -out retrievy-oci-private.pem 2048

# Derive the public key from the private key
openssl rsa -in retrievy-oci-private.pem -pubout -out retrievy-oci-public.pem

# Compute the fingerprint
openssl rsa -in retrievy-oci-private.pem -pubout -outform DER \
  | openssl md5 -c

The MD5 command prints the fingerprint in OCI's expected format (aa:bb:cc:dd:...). Copy it.

In the OCI console:

1. Open the user you created in step 2.
2. Scroll to Resources → API Keys in the left sidebar.
3. Click Add API Key.
4. Pick Paste a Public Key, then paste the entire contents of retrievy-oci-public.pem (including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines). Click Add.
5. OCI displays the fingerprint alongside the key. Confirm it matches the one your openssl md5 command produced.

You now have everything you need: User OCID, fingerprint, and the private-key PEM file.

caution

The private key file is a long-lived credential with read access to your entire tenancy. Treat it like a password. Delete the file from your local machine once you've pasted it into Retrievy. Rotate it by generating a new key pair and replacing it on the user's API Keys list every 12 months.

Step 4. Add the tenancy in Retrievy

In Retrievy:

1. Open Settings → Cloud Integrations → Add Cloud Account.
2. On the IDENTIFY TARGET step, pick Oracle Cloud (OCI) from the provider tiles. Click Next.
3. The INGEST CREDENTIALS step shows the five fields. Fill them in:

Field	What to paste
Tenancy OCID	From the OCI console tenancy overview.
User OCID	From the user detail page (step 2).
Fingerprint	From the API Keys list (step 3).
Region	The region identifier, for example us-ashburn-1.
Private Key	The full contents of retrievy-oci-private.pem, including the BEGIN and END lines.

4. Click Next. Retrievy validates the shape of each field (OCID prefixes, fingerprint format, PEM structure) and saves the account.

5. On the final step, click Finish. The first scan queues automatically.

Step 5. Watch the first scan

The account appears in Settings → Cloud Integrations with a Scanning... state. The first scan exercises the credentials against the OCI API; if anything is wrong (typo in OCID, wrong region, mismatched key), the scan reports the failure within a few minutes.

When the scan succeeds, findings start landing in the Command Center and Hardening Kanban.

What Retrievy scans

The OCI CSPM module covers the standard service-by-service audit set: IAM (users, groups, policies, federation), Object Storage (bucket visibility, encryption, versioning, lifecycle), Compute (security lists, network security groups, instance hardening), Networking (VCN, gateways, route tables), Block Volume and Boot Volume encryption, Vault (key rotation, secret access), Audit (log retention, compartment coverage), and more.

Findings carry CIS Oracle Cloud Infrastructure Foundations Benchmark mappings.

Multi-region tenancies

The Region field on the wizard is the primary region Retrievy scans against. OCI's API surface is region-scoped, so a credential signed against us-ashburn-1 won't query eu-frankfurt-1 resources unless you tell it to.

To scan multiple regions in one tenancy, add the tenancy multiple times in the wizard, once per region, using the same user OCID and key but a different region value. Each region counts as one data-source slot.

A roadmap improvement will let one OCI account cover every region the user has access to with a single slot. Until then, the per-region pattern is the supported approach.

Rotating credentials and revoking access

To rotate the private key:

1. Generate a new key pair (step 3) with a different filename.
2. In the OCI console, add the new public key to the user's API Keys list. OCI allows up to 3 active API keys per user, so you can run both old and new concurrently during the cutover.
3. In Retrievy, Update credentials on the account → paste the new private key and the new fingerprint. Save.
4. Confirm a fresh scan works. Remove the old API key from OCI.

To revoke:

1. In Retrievy, Deactivate the account or remove it entirely.
2. In OCI, either delete the user (cleanest) or remove the user from the retrievy-readers group (preserves the user record).

Troubleshooting

Symptom: First scan fails with NotAuthenticated. → Fix: Mismatch between the private key Retrievy holds and the public key registered against the user. Re-check the Fingerprint field; it must exactly match the one OCI shows in the user's API Keys list. Re-paste the private key making sure no characters were truncated (the BEGIN and END lines must be present).

Symptom: Scan fails with NotAuthorizedOrNotFound. → Fix: The user isn't in a group with the right policy. Open Identity & Security → Users → retrievy-cspm-reader → Groups and confirm retrievy-readers is listed. Open the retrievy-read-only policy and confirm both read all-resources and read audit-events statements are present.

Symptom: Scan succeeds but only Compartment-root resources appear. → Fix: Your policy is scoped to a sub-compartment instead of the tenancy root. Edit the policy and change the scope to the root compartment (Identity & Security → Policies → retrievy-read-only → Edit).

Symptom: Scan completes but Object Storage findings are missing. → Fix: Object Storage uses a separate objectstorage-namespaces permission. Add a policy statement: Allow group retrievy-readers to inspect objectstorage-namespaces in tenancy.

Symptom: I want to limit Retrievy to one compartment, not the entire tenancy. → Fix: Scope the policy at the compartment level instead of the tenancy. Replace in tenancy with in compartment <compartment-name> in both policy statements.

Symptom: Wizard saves with no error but the account never appears in the list. → Fix: Reload the page. The cloud-accounts list updates live; if your network blocks WebSocket connections the list won't refresh until you reload.

Related

• How the Retrievy Index is calculated
• Command Center
• Plan feature matrix
• OCI API signing key documentation