> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudgeni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Cloud Accounts

> Choose the cloud connection method that matches the current UI and the least privilege model the product actually uses.

# Connect Cloud Accounts

Cloud integrations are organization-scoped. They provide the live infrastructure context used by:

* Cloud compliance scans
* Cloud monitor findings
* Cloud resource inventory and import
* Agent sessions that need cloud-side context

Go to `Settings` -> `Integrations` -> `Cloud` to start.

## Current Provider Paths

| Provider | Current product path                         | Notes                                                       |
| -------- | -------------------------------------------- | ----------------------------------------------------------- |
| AWS      | Manual credentials in the UI                 | Best if you create a dedicated read-only IAM user           |
| Azure    | Quick Connect                                | Manual credential setup is deprecated after October 1, 2025 |
| GCP      | Keyless impersonation or service account key | Keyless impersonation is the preferred path                 |
| OCI      | Manual credentials in the UI                 | Uses tenancy, user, fingerprint, and private key            |

## Principle: Read First, Write Never

For onboarding and scanning, Cloudgeni is designed around read access to your cloud estate. The
product reads live state, runs scans, and uses that context to open repository changes later. It is
not supposed to apply infrastructure changes directly in your cloud account.

## AWS

The current UI exposes the manual credential path.

Use a dedicated IAM user with read-only access:

```bash theme={null}
aws iam create-user --user-name cloudgeni-readonly

aws iam attach-user-policy \
  --user-name cloudgeni-readonly \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

aws iam create-access-key --user-name cloudgeni-readonly
```

Take the `AccessKeyId` and `SecretAccessKey` into the AWS integration form.

## Azure

As of March 11, 2026, the supported path is **Quick Connect**.

The codebase still contains a manual credential screen, but that path is explicitly marked
deprecated after **October 1, 2025** and should not be your default recommendation.

Quick Connect creates a subscription-scoped service principal with read-only roles for resource
inventory, security posture, Log Analytics access, Terraform state discovery, and Azure Cost
Management summaries. The Cost & Billing views need **Cost Management Reader**; plain `Reader`
access can discover resources while still returning no actual billing rows.

If you need to understand the manual privilege shape, it is a subscription-scoped service principal
with this role set:

```bash theme={null}
export SCOPE="/subscriptions/$AZURE_SUBSCRIPTION_ID"

SP_JSON=$(az ad sp create-for-rbac \
  --name cloudgeni-reader \
  --role Reader \
  --scopes "$SCOPE" \
  --output json)

# Requires jq (https://jqlang.org/download/) in addition to az CLI.
APP_ID=$(echo "$SP_JSON" | jq -r .appId)
CLIENT_SECRET=$(echo "$SP_JSON" | jq -r .password)
TENANT_ID=$(echo "$SP_JSON" | jq -r .tenant)

SP_OBJECT_ID=$(az ad sp show --id "$APP_ID" --query id --output tsv)

for ROLE in \
  "Cost Management Reader" \
  "Security Reader" \
  "Log Analytics Reader" \
  "Storage Account Key Operator Service Role"
do
  az role assignment create \
    --assignee-object-id "$SP_OBJECT_ID" \
    --assignee-principal-type ServicePrincipal \
    --role "$ROLE" \
    --scope "$SCOPE"
done
```

Capture the full `create-for-rbac` output before extracting fields: the client secret (`password`)
is returned exactly once and cannot be retrieved later. The manual credential form needs `APP_ID`
(client ID), `CLIENT_SECRET`, and `TENANT_ID`. Passing `--assignee-object-id` with
`--assignee-principal-type ServicePrincipal` avoids the "principal not found" failures that can
occur when a role assignment races Entra ID replication right after the principal is created.

Use Quick Connect in the product unless you are validating a legacy fallback.

## GCP

The current app supports two modes:

* Keyless impersonation
* Service account key upload

Keyless impersonation is the better default because Cloudgeni requests short-lived tokens on demand
instead of storing a reusable key.

The exact setup flow in the app uses this platform service account:

`cloudgeni-platform-sa@cloudgeni-production.iam.gserviceaccount.com`

Minimal impersonation example:

```bash theme={null}
export PROJECT_ID="your-project-id"
export CLOUDGENI_SA="cloudgeni-access@$PROJECT_ID.iam.gserviceaccount.com"

gcloud iam service-accounts create cloudgeni-access \
  --display-name="CloudGeni Access" \
  --project=$PROJECT_ID

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CLOUDGENI_SA" \
  --role="roles/viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$CLOUDGENI_SA" \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud iam service-accounts add-iam-policy-binding $CLOUDGENI_SA \
  --member="serviceAccount:cloudgeni-platform-sa@cloudgeni-production.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project=$PROJECT_ID
```

## OCI

OCI currently uses the manual setup path in the UI.

You need a dedicated user, an API key pair, and a policy that grants read access to the tenancy or
compartment you want Cloudgeni to inspect.

```bash theme={null}
# Example policy statements to place in an OCI policy
Allow group CloudGeniReaders to inspect compartments in tenancy
Allow group CloudGeniReaders to read all-resources in tenancy
```

Use a dedicated user in that group, upload the public API key in OCI, and then enter the user OCID,
tenancy OCID, fingerprint, and private key in the Cloudgeni form.

## After The Account Is Connected

The next useful actions are:

* Run [Cloud Compliance](/features/cloud-compliance) for framework-based posture scans
* Review [Cloud Monitors](/features/cloud-monitors) for native provider findings
* Open [Cloud Resource Import](/features/cloud-resource-import) if you want to recover IaC from live resources

## What To Check If Setup Fails

* Integration is present but not useful: verify the account really has enough read scope for the resources you expect
* No findings or inventory appear: run a sync or scan from the integration page after the connection becomes active
* Agent work lacks cloud context: make sure you selected the cloud account when launching the session, not just connected it earlier