Skip to main content
Connecting a cloud provider gives the CauseFlow orchestrator agent access to your infrastructure — EC2 instances, ECS services, Lambda functions, CloudWatch logs, and more — without exposing credentials. CauseFlow uses each cloud provider’s native cross-account delegation mechanism so your keys never leave your environment.

​
How it works

CauseFlow assumes a read-only role in your cloud account at investigation time. For AWS this is STS AssumeRole, for Azure it is a Service Principal with a Reader role assignment, and for GCP it is a Service Account with Viewer permissions. CauseFlow never stores long-lived credentials — it requests temporary session credentials for each investigation and discards them when the investigation completes.

​
Required information

ProviderWhat you provide
AWSIAM Role ARN, external ID (generated by CauseFlow)
AzureTenant ID, Client ID, Client Secret
GCPService Account key (JSON) or Workload Identity configuration

​
AWS

​
How AWS access works

CauseFlow uses AWS STS AssumeRole with an external ID to access your AWS account. You create an IAM role in your account, attach a trust policy that permits CauseFlow’s AWS account to assume it, and provide the role ARN in the dashboard. CauseFlow passes the external ID on every AssumeRole call — without it, the call is rejected. The external ID is a unique token generated per CauseFlow tenant. It prevents the confused deputy problem: even if someone else knows your role ARN, they cannot assume it without your tenant’s external ID.

​
Required permissions

Attach the following permissions to the IAM role. All permissions are read-only. 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CauseFlowReadOnly",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:DescribeAlarms",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:GetLogEvents",
        "logs:FilterLogEvents",
        "ec2:DescribeInstances",
        "ec2:DescribeSecurityGroups",
        "ecs:DescribeClusters",
        "ecs:DescribeServices",
        "ecs:DescribeTasks",
        "ecs:ListTasks",
        "lambda:ListFunctions",
        "lambda:GetFunction",
        "iam:GetRole",
        "iam:ListRolePolicies",
        "iam:GetRolePolicy",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

​
Trust policy

Attach this trust policy to the IAM role. Replace <your-causeflow-external-id> with the external ID shown in Dashboard > Integrations > AWS. 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::409171461008:role/CauseFlowIntegrationRole"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your-causeflow-external-id>"
        }
      }
    }
  ]
}
CauseFlow AWS account ID: 409171461008. Confirm the exact principal ARN in Dashboard > Integrations > AWS once you begin the connection flow. Do not share the external ID — it is a secret that proves the connection originated from your CauseFlow tenant.

​
Steps to configure in CauseFlow

1

Open AWS integration

Go to Dashboard > Integrations > Cloud > AWS and click Connect.
2

Copy your external ID

CauseFlow generates a unique external ID for your tenant. Copy it — you will need it in the trust policy.
3

Create the IAM role

In your AWS account, create a new IAM role with the permission policy and trust policy shown above. Use any name you like (for example, CauseFlowRole).
4

Copy the role ARN

After creating the role, copy its ARN. The format is arn:aws:iam::<your-aws-account-id>:role/<role-name>.
5

Enter the role ARN in CauseFlow

Back in CauseFlow, paste the role ARN and click Verify connection. CauseFlow calls sts:GetCallerIdentity to confirm access.

​
What this enables

  • CloudWatch alarm ingestion via SNS webhook (see Monitoring for setup)
  • Log retrieval from CloudWatch Logs during investigation
  • EC2 and ECS instance state inspection
  • Lambda function configuration review

​
Azure

​
How Azure access works

CauseFlow uses a Service Principal with a Reader role assignment scoped to your subscription or resource group. You register an app in Azure Entra ID, create a client secret, and grant the principal Reader access. CauseFlow authenticates as the service principal to read resource metadata during investigations.

​
Required permissions

  • Role: Reader (built-in) scoped to your subscription or target resource group
  • API permissions: None required (Reader is sufficient for resource inspection)

​
Steps to obtain credentials

1

Register an application

In the Azure Portal, go to Microsoft Entra ID > App registrations > New registration. Give it a name (for example, CauseFlow) and click Register.
2

Create a client secret

Under Certificates & secrets, click New client secret. Set an expiry, click Add, and copy the secret value immediately — it is only shown once.
3

Note the IDs

From the app overview page, copy the Application (client) ID and the Directory (tenant) ID.
4

Assign the Reader role

Go to your Subscription > Access control (IAM) > Add role assignment. Select the Reader role, then assign it to the app you just registered.

​
Steps to configure in CauseFlow

1

Open Azure integration

Go to Dashboard > Integrations > Cloud > Azure and click Connect.
2

Enter credentials

Provide your Tenant ID, Client ID, and Client Secret.
3

Verify the connection

Click Verify connection. CauseFlow confirms read access to your subscription and shows a green status indicator.

​
What this enables

  • Azure resource inspection (VMs, AKS nodes, Azure Functions, App Services)
  • Azure Monitor metrics and log retrieval during investigation

​
GCP

​
How GCP access works

CauseFlow authenticates using a GCP Service Account. You create a service account, grant it Viewer permissions on your project, and download a JSON key file (or configure Workload Identity for keyless authentication). CauseFlow uses the service account to read resource metadata and logs during investigations.

​
Required permissions

  • IAM roles: roles/viewer on the target project (or a custom role with equivalent read-only permissions)
  • Optional: roles/logging.viewer if you want CauseFlow to read Cloud Logging entries

​
Steps to obtain credentials

1

Create a service account

In the Google Cloud Console, go to IAM & Admin > Service Accounts > Create Service Account. Give it a name (for example, causeflow-integration) and click Create.
2

Grant Viewer role

On the next screen, grant the Viewer role to the service account. Click Done.
3

Create a key

From the service account list, click your new service account, go to the Keys tab, and click Add Key > Create new key. Choose JSON and click Create. A JSON key file is downloaded automatically.

​
Steps to configure in CauseFlow

1

Open GCP integration

Go to Dashboard > Integrations > Cloud > GCP and click Connect.
2

Upload the service account key

Upload the JSON key file you downloaded. CauseFlow stores it in its encrypted credential vault.
3

Verify the connection

Click Verify connection. CauseFlow confirms access and shows a green status indicator.

​
What this enables

  • GCP resource inspection (Compute Engine instances, GKE nodes, Cloud Run services)
  • Cloud Logging retrieval during investigation

​
Troubleshooting

AWS: AccessDenied on AssumeRole Confirm that:
  • The external ID in the trust policy exactly matches the one shown in CauseFlow
  • The principal ARN in the trust policy matches what CauseFlow showed you during setup
  • The role has no permission boundary blocking AssumeRole
AWS: AccessDenied on CloudWatch / Logs Confirm the permission policy attached to the role includes the CloudWatch and Logs actions listed above. Azure: AuthorizationFailed Confirm the Reader role assignment is scoped to the subscription or resource group containing the resources you want CauseFlow to inspect. Also confirm the client secret has not expired. GCP: PERMISSION_DENIED Confirm the service account has the Viewer role on the correct project. If using a custom role, ensure it includes resourcemanager.projects.get.

Monitoring integrations

Set up CloudWatch alarm forwarding via SNS webhook.

Security overview

Learn how CauseFlow stores and protects your cloud credentials.

Databases

Connect databases for deeper root-cause analysis.

API reference

Manage cloud integrations programmatically.