Connect AWS

00How access works

AWS Data Exports writes a FOCUS 1.2 file set to an S3 bucket in your account every day. FinOpsAI's ingestion identity — a Google Cloud service account — presents a Google-signed token to AWS STS and assumes an IAM role in your account (AssumeRoleWithWebIdentity). The role's trust policy accepts only that one identity, and its permission policy allows only reading the export bucket plus five read-only commitment-inventory calls. You can revoke everything by deleting the role.

01Before you start

• You need IAM permissions for Billing and Cost Management → Data Exports (e.g. bcm-data-exports:*, cur:*), S3 bucket creation, and IAM role creation in the management account.
• Decide on a bucket name. Bucket names are global — something like acme-focus-billing-export.
• Activate cost-allocation tags before the first export (Step 3). Tag activation is not retroactive: months exported before activation stay blank for those tags.
• Have the FinOpsAI workspace owner ready with three values: payer account ID, bucket name, prefix. The role is created from a template the wizard generates, so its ARN is never typed.

02Steps

1. S3 → Create bucket Region Asia Pacific (Mumbai) ap-south-1. Name e.g. acme-focus-billing-export. Keep Block all public access on. Default encryption (SSE-S3) is fine. Create.
2. Billing and Cost Management → Data Exports → Create Export type Standard data export. Name focus. Data table FOCUS 1.2 with AWS columns. Compression/format Parquet. File versioning Overwrite existing data export file. Under Data export storage settings choose the bucket from Step 1 and S3 path prefix focus. Create.

   The console offers to apply the bucket policy that lets the export service (bcm-data-exports.amazonaws.com and billingreports.amazonaws.com) write to the bucket — accept it. Without that policy the export is created but never delivers. The first file set arrives within 24 hours and is refreshed up to three times a day thereafter; earlier months are not back-filled.

3. Billing and Cost Management → Cost allocation tags Under User-defined cost allocation tags select every tag key you want to report on (owner, environment, cost-centre…) and click Activate. Activation can take up to 24 hours to appear in exports.
4. FinOpsAI → Connections → Add a cloud → Amazon Web Services → steps 1–2 Step 1 lists who is needed. Step 2: enter the 12-digit payer account ID (Account menu → Account), the bucket name and the prefix focus. The wizard derives the role ARN from the account ID and the default role name FinOpsAIReader.
5. Step 3 "Give us read access" → Download the CloudFormation template The template is generated for your workspace: it creates the role FinOpsAIReader with a trust policy pinned to your workspace identity and a read-only policy limited to your bucket (plus the optional commitments describe/get calls). Click the CloudFormation link → Create stack → Upload a template file → the file you downloaded → Next → stack name finopsai-reader → Next → tick I acknowledge that AWS CloudFormation might create IAM resources with custom names → Submit. About a minute. The wizard watches and turns green when the role can be assumed.

   Prefer to create the role by hand? The same step shows the trust policy and the permission policy to paste (IAM → Roles → Create role → Custom trust policy); the values are identical to what the template creates.

6. Step 4 "Test and connect" → Run the test → Connect FinOpsAI assumes the role, lists the bucket under the prefix and reads the latest FOCUS manifest, reporting one clear diagnosis if anything is off (see below). No export delivered yet is acceptable for a new export — Connect still works and the first sync runs when the file lands.

03What the template creates — trust policy and permission policy

For review by your security team. The CloudFormation template from Step 5 creates exactly these two documents; if you create the role by hand, paste them from the wizard, which fills in your workspace identity.

Trust policy

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "accounts.google.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "accounts.google.com:sub": "<your workspace identity's unique ID — shown in the wizard>",
        "accounts.google.com:aud": "<the same value>"
      }
    }
  }]
}

Both conditions pin the same value — the numeric unique ID of your workspace's FinOpsAI service account. No other Google identity, and no other FinOpsAI workspace, can assume the role.

Permission policy — YOUR-BUCKET-NAME is your bucket from Step 1

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "FinOpsAIReadFocusExport",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"],
      "Resource": [
        "arn:aws:s3:::YOUR-BUCKET-NAME",
        "arn:aws:s3:::YOUR-BUCKET-NAME/*"
      ]
    },
    {
      "Sid": "FinOpsAICommitmentInventoryReadOnly",
      "Effect": "Allow",
      "Action": [
        "savingsplans:DescribeSavingsPlans",
        "ec2:DescribeReservedInstances",
        "ce:GetSavingsPlansUtilization",
        "ce:GetSavingsPlansUtilizationDetails",
        "ce:GetReservationUtilization"
      ],
      "Resource": "*"
    }
  ]
}

The second statement is optional. It lets FinOpsAI list your Savings Plans and Reserved Instances and read their utilisation for the Commitments view; these are account-wide describe/get calls that do not support resource-level ARNs, hence "Resource": "*". Omit it and billing analysis still works — the Commitments inventory shows "access not granted".

04Values to enter in FinOpsAI

05What FinOpsAI verifies, and what a failure means

06After connecting

• FinOpsAI ingests the export on its refresh cycle, loading rows into its own analytics store in asia-south1; the connection detail page shows the last loaded period and flags an export that has stopped (no new file for 48 hours).
• Member accounts of your organisation appear automatically; the connection card shows how many linked accounts have billing rows.
• Savings Plans and Reserved Instances appear in Commitments once the optional inventory statement is in place; utilisation follows FOCUS used ÷ (used + unused) per instrument.
• Reports draw on the trailing 30 days, so the first complete Savings Audit is meaningful about a month after the export starts.

07Revoking access

Delete the finopsai-reader CloudFormation stack, or the FinOpsAIReader role if you created it by hand. Access stops at the next token exchange — within the hour. The export and bucket are yours; disable the export in Data Exports if you no longer need it. Use Disconnect in FinOpsAI to remove the ingested rows and the connection record from FinOpsAI's side.

08Troubleshooting

We already have a legacy Cost and Usage Report (CUR 2.0) — can FinOpsAI use it?

FinOpsAI reads the FOCUS 1.2 table only. Create a FOCUS export alongside your existing CUR; both can deliver to the same bucket under different prefixes.

Our security policy forbids "Resource": "*"

Omit the second statement. Everything derived from billing works; only the live Savings Plan / RI inventory is unavailable.

Can the role be created in a member account?

The role must be in the account that owns the export bucket — normally the management account, because only it can create the export. If the bucket lives in a member account (cross-account delivery), create the role there and enter that account's role ARN; the payer account ID stays the management account's.

The export shows "Healthy" in AWS but FinOpsAI still says "no export delivered yet"

Check the S3 path: Data Exports writes to <prefix>/<export-name>/…. The prefix you enter in FinOpsAI is the S3 path prefix, not the export name.

Who to contact

finops@samsofttechnologies.com — include the check that failed and its detail text.