Understanding the Auto-Provisioning Policy for Gatekeepers in Cloudflare OS

Cloudflare OS auto-provisions Gatekeeper accounts only when a vendor declares autoProvisionsAccount: true and the administrator configures the ambient mode as enabled or optional, eliminating the need for OAuth flows.

Cloudflare OS manages third-party service integrations through modular components called Gatekeepers, each requiring explicit provisioning policies to control account lifecycle management. The auto-provisioning policy for Gatekeepers determines whether the Workshop kernel automatically creates connected accounts without user intervention or manual OAuth authorization. This analysis examines the exact implementation logic defined in the cloudflare/cloudflare-os repository.

Declaring Auto-Provisioning Capabilities in VendorDescription

A Gatekeeper must explicitly signal its support for automatic account creation by setting autoProvisionsAccount: true within its VendorDescription interface. This boolean flag indicates that the Gatekeeper implementation can programmatically generate accounts without requiring users to complete a browser-based OAuth handshake.

According to the interface definition in packages/workshop-shared/src/gatekeeper.ts (lines 79-86), this property remains optional:

// packages/workshop-shared/src/gatekeeper.ts
interface VendorDescription {
  id: string;
  name: string;
  // ...
  autoProvisionsAccount?: boolean;
}

When this flag is absent, undefined, or explicitly false, the system treats the Gatekeeper as requiring manual provisioning. Administrators must then enable the integration through the Connectors UI, and users must authenticate via standard OAuth redirects before the platform creates any account associations.

The Two-Step Auto-Provisioning Policy

The decision logic resides in packages/workshop-backend/src/provisioning-policy.ts and follows a mandatory two-step validation process. The kernel evaluates both administrative configuration and vendor capabilities before creating accounts automatically.

Step 1 – Ambient Mode Configuration

The first check examines the ambient mode assigned to each Gatekeeper in the AdminConfig. The system defines three distinct modes, with DEFAULT_AMBIENT_GATEKEEPER_MODE = "optional" serving as the fallback value (lines 17-23 in provisioning-policy.ts):

• optional – Permits auto-provisioning when users first interact with the Gatekeeper, but does not force it (default behavior)
• enabled – Forces automatic account creation for all users immediately
• disabled – Blocks all auto-provisioning attempts regardless of vendor capabilities

Administrators modify these settings through the configuration interface defined in packages/workshop-backend/src/admin-config.ts (lines 44-48), which stores the mode per vendor ID.

Step 2 – The Provisioning Validation Function

The second step invokes shouldAutoProvisionAccount(config, vendorId), a predicate function that returns true only when both conditions satisfy:

1. The AdminConfig sets the Gatekeeper's ambient mode to enabled or optional
2. The Gatekeeper's VendorDescription.autoProvisionsAccount property equals true

The implementation (lines 32-34 in provisioning-policy.ts) performs a strict logical conjunction:

// packages/workshop-backend/src/provisioning-policy.ts
export function shouldAutoProvisionAccount(
  config: AdminConfig, 
  vendorId: string
): boolean {
  const mode = getAmbientMode(config, vendorId);
  const vendor = getVendorDescription(vendorId);
  
  return (mode === "enabled" || mode === "optional") && 
         vendor.autoProvisionsAccount === true;
}

If either condition fails—whether through disabled ambient mode or missing vendor declaration—the function returns false, and the system falls back to manual OAuth flows.

Account Creation Implementation

When the policy check succeeds, the platform bypasses OAuth entirely. The Gatekeeper's createAccount() method generates a new account instance identified solely by a system-generated accountId, with no linkage to external user identities. The platform persists these accounts as standard Durable Objects.

The resolution path in packages/workshop-backend/src/user.ts (lines 1198-1206) demonstrates this flow:

// packages/workshop-backend/src/user.ts
async function resolveGatekeeperAccount(
  vendor: GatekeeperVendor, 
  env: Cloudflare.Env
) {
  // Prior validation confirms autoProvisionsAccount is true
  if (shouldAutoProvisionAccount(config, vendor.id)) {
    const account = await vendor.createAccount();
    // account.id contains the generated accountId
    await storeAccountReference(account.id, env);
    return account;
  }
  
  // Fallback to OAuth initiation...
}

Unlike OAuth-provisioned accounts that map to external provider identities, auto-provisioned accounts exist as isolated Durable Objects managed entirely within the Cloudflare OS infrastructure.

Configuring the Policy via Admin API

The AdminConfig interface provides the administrative control surface for the auto-provisioning policy. Defined in packages/workshop-backend/src/admin-config.ts, the configuration structure accepts ambient mode overrides per Gatekeeper:

// packages/workshop-backend/src/admin-config.ts
export interface AdminConfig {
  gatekeepers: Record<string, {
    ambientMode: "optional" | "enabled" | "disabled";
    // Additional configuration...
  }>;
}

Administrators query the current policy status programmatically using the shared validation logic:

import { shouldAutoProvisionAccount } from "packages/workshop-backend/src/provisioning-policy";
import { AdminConfig } from "packages/workshop-shared/src/api";

function checkProvisioningStatus(
  config: AdminConfig, 
  vendorId: string
): boolean {
  return shouldAutoProvisionAccount(config, vendorId);
}

Setting ambientMode to "enabled" immediately triggers account creation for all existing users upon their next interaction, while "disabled" prevents any automatic provisioning even for compliant Gatekeepers.

Summary

• Vendor Declaration Required: Gatekeepers must explicitly set autoProvisionsAccount: true in their VendorDescription interface to participate in auto-provisioning.
• Dual-Condition Validation: The shouldAutoProvisionAccount function requires both administrative approval (via ambient mode) and vendor capability declaration to return true.
• Default Conservative Posture: The system defaults to optional mode, preventing forced provisioning while allowing user-initiated automation.
• OAuth Elimination: Successful policy validation invokes createAccount() directly, creating Durable Objects with generated accountId values rather than mapping external identities.
• Primary Implementation Files: Policy logic lives in packages/workshop-backend/src/provisioning-policy.ts, interface definitions in packages/workshop-shared/src/gatekeeper.ts, and account resolution in packages/workshop-backend/src/user.ts.

Frequently Asked Questions

What prevents auto-provisioning if a Gatekeeper declares autoProvisionsAccount: true?

The ambientMode setting in AdminConfig acts as the administrative override. If an administrator sets the mode to "disabled", the shouldAutoProvisionAccount function returns false regardless of the vendor's declared capabilities. Additionally, if the vendor interface omits autoProvisionsAccount or sets it to false, the policy check fails immediately.

How does auto-provisioning differ from standard OAuth account creation?

Standard OAuth flows require users to authenticate with third-party providers, creating accounts mapped to external identities. Auto-provisioned accounts bypass this by calling createAccount() directly on the Gatekeeper, generating isolated Durable Objects identified only by system-generated accountId values. These accounts contain no external identity linkage and exist solely within the Cloudflare OS infrastructure.

Where is the default ambient mode constant defined?

The default value "optional" is defined as DEFAULT_AMBIENT_GATEKEEPER_MODE in packages/workshop-backend/src/provisioning-policy.ts at line 17. This constant ensures that new Gatekeepers do not force automatic account creation until administrators explicitly change the setting to "enabled".

Can auto-provisioning be enabled for only specific users?

No. The auto-provisioning policy applies uniformly per Gatekeeper based on the AdminConfig settings. The ambientMode operates at the vendor level, affecting all users equally. To achieve user-specific provisioning, administrators must implement custom logic outside the standard shouldAutoProvisionAccount check, potentially within the account resolution layer in packages/workshop-backend/src/user.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}