Cloud Integrations

Shared Rules

Use these rules for every provider:

  • connect integrations at the project level

  • keep storage and deployment auth aligned with the same customer-owned target

  • prefer workload identity, OIDC, or service-account impersonation over long-lived keys wherever the provider supports it

  • treat identity verification and bucket or container configuration as separate steps

  • expect IAM and RBAC changes to take a few minutes to propagate before retrying verification

  • use the provider-specific bucket check and bucket config endpoints after identity verification succeeds

Recommended operator order:

  1. connect the cloud identity

  2. verify the cloud identity

  3. verify the bucket or container exists and is accessible

  4. save the bucket or container config

  5. upload artifacts and start deployments

Azure

The recommended Azure path is Workload Identity Federation plus the DCF Azure bootstrap template. Legacy client-secret auth still exists in the backend for backward compatibility, but customer-facing onboarding should use the WIF flow.

What Customers Need Before They Start

Before opening the Azure flow, the customer should have:

  • the Azure tenant ID

  • the subscription ID

  • the target resource group name

  • permission to deploy resources and assign RBAC within that resource group

  • an Azure region with enough App Service Plan quota if they will use the DCF resource bootstrap flow

Azure Identity Setup Flow

Current onboarding is a two-step process:

  1. Call POST /api/v1/projects/{projectId}/integrations/azure/wif/register. DCF stores a pending onboarding row, generates a dcfCorrelationId, and returns an Azure Portal deployment link.

  2. Open the returned portalUrl in Azure Portal and complete the template deployment.

  3. Return to DCF and call POST /api/v1/projects/{projectId}/integrations/azure/wif/verify.

The Azure bootstrap template creates or applies:

  • a resource-group tag containing dcfCorrelationId

  • a user-assigned managed identity

  • a federated identity credential that trusts the DCF GKE OIDC issuer and service-account subject

  • a Contributor role assignment scoped to the selected resource group

During verification, DCF checks:

  • the resource group exists in the specified subscription

  • the dcfCorrelationId tag matches the current onboarding session

  • the managed identity can be resolved in Microsoft Graph

Azure Resource And Storage Prerequisites

Identity verification alone is not enough for a working deployment.

For Azure-hosted deployments, the target resource group must eventually contain:

  • an Azure Container Registry

  • an App Service Plan

  • an App Service

DCF can help with that through:

  • POST /api/v1/projects/{projectId}/integrations/azure/resources/template

  • GET /api/v1/projects/{projectId}/integrations/azure/resources/verify

For artifact handling, the customer also needs:

  • a storage account in the connected resource group

  • a Blob container for function artifacts

Use these endpoints after Azure identity setup:

  • POST /api/v1/projects/{projectId}/integrations/azure/bucket/check

  • GET /api/v1/projects/{projectId}/integrations/azure/bucket/config

  • POST /api/v1/projects/{projectId}/integrations/azure/bucket/config

Azure Permissions To Grant

The current Azure code path separates management-plane and data-plane access.

Grant these permissions:

  • Contributor on the target resource group so DCF can verify the resource group, inspect storage accounts, and work with deployment resources

  • Storage Blob Data Contributor on the target storage account or container so DCF can upload, read, and delete function artifacts

For container existence checks, Storage Blob Data Reader may be enough to confirm access, but uploads require Storage Blob Data Contributor.

Common Azure Failure Modes

These are the most common customer-side setup issues:

  • Contributor role assignment missing …​ or not yet propagated Wait a few minutes after RBAC changes, then retry verification.

  • Resource group "<name>" not found …​ The onboarding values do not point at the correct subscription or resource group, or the template deployment did not finish.

  • Correlation ID mismatch The customer verified against the wrong resource group or a resource group created by a different DCF onboarding session.

  • Azure container exists but blob access is denied The connected identity can see the resource group but does not have the Blob data-plane role needed for storage access.

AWS

AWS support uses IAM OIDC and sts:AssumeRoleWithWebIdentity. DCF assumes a customer IAM role with a short-lived web identity token, then uses those temporary credentials for S3 artifact handling and CodeBuild deployment orchestration.

DCF must not request or store static AWS access keys for the current AWS flow.

What Customers Need Before They Start

Before enabling AWS, the customer should have:

  • an AWS account where they can create IAM resources

  • the target AWS region

  • the S3 bucket name for artifacts

  • permission to create an IAM OIDC provider and IAM role

  • permission to create or select a CodeBuild project

  • permission to grant the DCF assumed role S3 and CodeBuild access

  • permission to grant the CodeBuild service role the Lambda permissions needed by the DCF-supplied buildspec

AWS OIDC Setup Flow

The current OIDC flow is:

  1. Fetch the generated setup script from GET /api/v1/projects/{projectId}/integrations/aws/oidc/setup-commands

  2. Run the returned AWS CLI commands locally in an AWS CLI session

  3. Paste the resulting role ARN and region into DCF

  4. Verify through POST /api/v1/projects/{projectId}/integrations/aws/oidc/verify

  5. Validate and save the artifact bucket, CodeBuild project, ECR repository URI, and Lambda execution role ARN through POST /api/v1/projects/{projectId}/integrations/aws/bucket/save

DCF generates commands for these steps:

  • confirm the customer’s current AWS identity

  • create an IAM OIDC provider pointing at the DCF runtime issuer

  • create a trust policy that exactly matches the DCF runtime token claims

  • create the IAM role DCF will assume

  • create or attach the runtime policy for S3 artifacts and CodeBuild start/read

  • confirm the customer-owned ECR repository and Lambda execution role used by CodeBuild

The generated trust policy expects:

  • the exact issuer host used by the DCF runtime token

  • the exact sub claim from the runtime token

  • aud = sts.amazonaws.com

During verification, DCF reads its mounted token and calls sts:AssumeRoleWithWebIdentity. If that succeeds, the integration stores the role ARN, region, issuer, subject, and verification timestamp.

AWS Responsibility Split

DCF owns:

  • the API and frontend onboarding flow

  • the projected Kubernetes token path used for AWS web identity

  • the OIDC verification call to AWS STS

  • S3 bucket validation using OIDC temporary credentials

  • artifact upload/read/delete using OIDC temporary credentials

  • deployment runner environment injection for AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, and AWS_REGION

The customer owns:

  • the IAM OIDC provider in their AWS account

  • the IAM role trust policy and permissions policy

  • the S3 artifact bucket

  • the ECR repository for Lambda container images

  • the CodeBuild project

  • the CodeBuild service role and Lambda execution role

DCF supplies the standard CodeBuild buildspec that turns S3_BUCKET, S3_KEY=builds/app.zip, FUNCTION_NAME, and AWS_REGION into a Lambda deployment. Customer-specific buildspec changes should be reviewed as enterprise exceptions instead of becoming the default path.

AWS Storage And Deployment Prerequisites

After role verification, the customer still needs a working artifact bucket and CodeBuild project.

Current expectations:

  • the S3 bucket already exists

  • the bucket is reachable in the configured region

  • the DCF assumed role can list the bucket location and read/write/delete artifact objects

  • the CodeBuild project exists in the configured region

  • the DCF assumed role can call codebuild:StartBuild and codebuild:BatchGetBuilds on that project

  • the CodeBuild service role can read s3://<bucket>/builds/app.zip and create or update the target Lambda resources

  • the CodeBuild project accepts DCF’s standard buildspec override and defines the required project environment variables

Use these endpoints to validate and save the artifact bucket, CodeBuild project, ECR repository URI, and Lambda execution role ARN:

  • POST /api/v1/projects/{projectId}/integrations/aws/bucket/validate

  • POST /api/v1/projects/{projectId}/integrations/aws/bucket/save

  • GET /api/v1/projects/{projectId}/integrations/aws/bucket/config

AWS Permissions To Grant

For the DCF assumed role:

  • s3:GetBucketLocation

  • s3:ListBucket

  • s3:GetObject

  • s3:PutObject

  • s3:DeleteObject

  • codebuild:StartBuild

  • codebuild:BatchGetBuilds

  • lambda:GetFunction

  • lambda:GetFunctionUrlConfig

  • lambda:DeleteFunctionUrlConfig, lambda:RemovePermission, and lambda:DeleteFunction when DCF undeploy should remove Lambda resources

For the CodeBuild service role:

  • read access to the staged S3 artifact object

  • ECR image push permissions on the target repository

  • CloudWatch Logs permissions for build logs

  • the Lambda and IAM permissions required by the DCF-supplied buildspec, including lambda:CreateFunction, lambda:UpdateFunctionCode, lambda:UpdateFunctionConfiguration, lambda:GetFunction, lambda:GetFunctionConfiguration, lambda:GetFunctionUrlConfig, lambda:CreateFunctionUrlConfig, lambda:AddPermission, and lambda:TagResource

  • permission to create or update the Lambda Function URL and public function URL permissions when the deployment exposes HTTP access

See AWS Customer OIDC Setup for the full customer walkthrough and full policy example.

Common AWS Failure Modes

The most common AWS setup issues are:

  • Invalid OIDC token The IAM trust policy does not exactly match the runtime token claims. The issuer, subject, and audience checks are case-sensitive.

  • Access denied assuming role The trust policy or attached permissions do not allow the requested role assumption.

  • Bucket exists but access is denied The DCF assumed role can reach the bucket endpoint but does not have enough bucket permissions.

  • CodeBuild project missing The bucket was saved without a valid CodeBuild project, or the project is in a different region.

  • ECR_REPOSITORY_URI is required The saved AWS integration is missing the ECR repository URI needed for Lambda container image publishing.

  • LAMBDA_EXECUTION_ROLE_ARN is required The saved AWS integration is missing the Lambda execution role ARN needed by the CodeBuild deployment.

  • CodeBuild starts but Lambda is not updated The DCF role can start the build, but the CodeBuild service role or buildspec does not have the Lambda deployment permissions needed inside the customer account.

GCP

GCP support in DCF uses Workload Identity Federation (WIF) with a customer-owned service account. DCF never owns your project — it only impersonates a service account that you explicitly grant permissions to.

Core Model (Important)

  • DCF authenticates via Workload Identity Federation

  • DCF impersonates a customer-owned service account

  • That service account performs builds and deployments

  • Customer retains full control over IAM and runtime access

What Customers Need Before They Start

Before connecting GCP, the customer should have:

  • the target GCP project ID

  • a dedicated Google service account for DCF to impersonate

  • the workload identity host project number

  • the workload identity pool ID

  • the workload identity provider ID

  • a GCS bucket for function artifacts

  • an Artifact Registry Docker repository in the selected deployment region

  • a customer-owned workload identity provider already configured to trust the DCF runtime identity

  • permission to manage IAM on the target service account, storage bucket, Artifact Registry repository, and selected runtime target

For Cloud Run deployments, enable these APIs in the customer project:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  sts.googleapis.com \
  --project="$PROJECT_ID"

Step 1: Create Service Account

Create a dedicated service account:

dcf-deployer@<project-id>.iam.gserviceaccount.com

Step 2: Configure Workload Identity Federation

Bind DCF to impersonate the service account:

gcloud iam service-accounts add-iam-policy-binding \
  dcf-deployer@<project-id>.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/subject/<SUBJECT>"

Typical roles depend on the customer deployment model. For the standard Cloud Run path, start with the narrowest set that supports the chosen access model:

  • roles/storage.objectAdmin on the artifact bucket, or a custom role that can write, read, and delete the staged function artifacts DCF owns

  • roles/cloudbuild.builds.editor on the project so DCF can start container builds

  • roles/artifactregistry.writer on the target repository for the account that pushes the image

  • roles/run.developer on the target Cloud Run service or project so DCF can create and update revisions

  • roles/iam.serviceAccountUser on the Cloud Run runtime service account if the deploy flow attaches a user-managed service identity

Public Cloud Run services need one more policy decision. If DCF is expected to make the service public through --allow-unauthenticated, the impersonated customer service account also needs permission to set the Cloud Run service IAM policy, such as a narrowly scoped custom role that includes run.services.setIamPolicy or a broader operator-approved role. Security-first customers can instead keep DCF on the private path and manage the public roles/run.invoker binding themselves.

GKE targets are advanced and customer-operated. In that model, the customer must provide the cluster access and Kubernetes RBAC needed for the specific namespace, deployment, and container update.

For GKE, common examples include:

  • roles/cloudbuild.builds.editor

  • Artifact Registry writer/reader roles for the build and pull identities

  • the customer-selected GKE or Kubernetes permissions required by the cluster policy

  • roles/viewer → view logs in UI (Cloud Build / Run)

IMPORTANT: Do NOT use roles/run.admin by default.

Step 7: Connect + Verify in DCF

APIs:

  • POST /integrations/gcp/wif/register

  • POST /integrations/gcp/wif/verify

Then configure bucket + runtime:

  • POST /integrations/gcp/bucket/config

{
  "gcpProjectId": "customer-app-prod",
  "serviceAccountEmail": "dcf-deployer@customer-app-prod.iam.gserviceaccount.com",
  "workloadIdentityProjectNumber": "123456789012",
  "workloadIdentityPool": "dcf-pool",
  "workloadIdentityProvider": "dcf-provider"
}

Important details:

  • gcpProjectId is the customer project where DCF deploys and validates resources

  • workloadIdentityProjectNumber is the numeric host project for the workload identity pool and provider

  • the backend normalizes the STS audience internally

  • the public API does not accept workloadIdentityAudience

GCP Verification And Bucket Flow

The current operator flow is:

  1. Save the GCP WIF contract with the connect endpoint.

  2. Apply the IAM binding command returned by DCF so the federated workload identity principal can impersonate the customer-owned service account.

  3. Optional operator debug: call the diagnostics endpoint to inspect each auth hop without exposing raw tokens.

  4. Call the verify endpoint.

  5. Validate the target GCS bucket and save it with the GCP deployment fields through the bucket config endpoint.

The GCP bucket config request requires the customer-selected GCS bucket, deployment region, existing Artifact Registry Docker repository name, and runtime target:

{
  "bucketName": "dcf-gcs-bucket",
  "region": "us-central1",
  "artifactRepository": "customer-dcf-repo",
  "runtimeTarget": "cloud_run",
  "serviceName": "dartcloudfunctions-test"
}

IMPORTANT:

For the advanced GKE target, use runtimeTarget=gke and include the Kubernetes namespace in the config. Deployment requests still need the workload-specific deploymentName and containerName.

During verification, DCF exchanges its mounted runtime token against GCP STS, then calls IAMCredentials directly to generate a short-lived access token for the customer-owned service account.

Deployment Target (Frontend)

Frontend must send:

{
  "target": {
    "runtimeTarget": "cloud_run",
    "region": "us-central1",
    "artifactRepository": "dcf-repo",
    "namespace": "default",
    "deploymentName": "dcf-<functionId>",
    "containerName": "dcf-gcs-bucket"
  }
}

IMPORTANT:

  • runtimeTarget must come from config API

  • DO NOT hardcode

  • deploymentName must be stable

Deployment Behavior

DCF deployment flow:

  1. Cloud Build builds Docker image

  2. Image pushed to Artifact Registry

  3. Deployed to runtime (Cloud Run or GKE)

Public vs Private Access

Access is controlled from UI:

  • public → --allow-unauthenticated

  • private → --no-allow-unauthenticated

Cloud Run:

  • enforced automatically

GKE:

  • NOT enforced by DCF

  • customer controls ingress/auth

Common Failure Modes

  • GCP_RUNTIME_TARGET_REQUIRED → missing runtimeTarget in request

  • WORKLOAD_IDENTITY_BINDING_MISSING → missing roles/iam.workloadIdentityUser

  • permission denied → missing IAM roles

  • repository not found → Artifact Registry not created

  • build succeeds but deploy fails → missing run.developer

  • 403 Forbidden on endpoint → deployed as private

Security Model

  • no service account keys

  • all auth via WIF

  • short-lived credentials only

  • customer controls access boundary

Final Flow

  1. Create service account

  2. Configure WIF

  3. Grant impersonation

  4. Assign roles

  5. Create bucket + repo

  6. Connect + verify

  7. Save config (region + repo + runtimeTarget)

  8. Deploy

Result:

  • image built via Cloud Build

  • stored in Artifact Registry

  • deployed to Cloud Run / GKE

  • endpoint returned