# Understanding the Auto-Provisioning Policy for Gatekeepers in Cloudflare OS

> Learn about the Cloudflare OS auto-provisioning policy for Gatekeepers. Discover how vendors enable automatic account creation without OAuth when ambient mode is configured.

- Repository: [Cloudflare/cloudflare-os](https://github.com/cloudflare/cloudflare-os)
- Tags: deep-dive
- Published: 2026-09-05

---

**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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-shared/src/gatekeeper.ts) (lines 79-86), this property remains optional:

```typescript
// 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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/provisioning-policy.ts)) performs a strict logical conjunction:

```typescript
// 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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/user.ts) (lines 1198-1206) demonstrates this flow:

```typescript
// 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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/admin-config.ts), the configuration structure accepts ambient mode overrides per Gatekeeper:

```typescript
// 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:

```typescript
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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/provisioning-policy.ts), interface definitions in [`packages/workshop-shared/src/gatekeeper.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-shared/src/gatekeeper.ts), and account resolution in [`packages/workshop-backend/src/user.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/user.ts).