techlist.io
KREN
cloudflare

Unlocking the Cloudflare app ecosystem with OAuth for all (opens in new tab)

cloudflare-workersoauthwranglerdatabase-migrationscloudflare-queuesblue-green-deploymenthydra

Cloudflare opened self-managed OAuth to all customers so developers can build SaaS integrations, internal platforms, CI/CD workflows, and agentic tools without relying on difficult-to-manage API tokens. The expansion required improvements to permissions, consent, revocation, and phishing protections, as well as a major upgrade to the Hydra-based OAuth engine. Cloudflare used staged migrations, custom database changes, token-handling safeguards, and queued revocations to minimize disruption and preserve users’ security controls.

Why Cloudflare Expanded OAuth Access

  • Previously, third-party OAuth integrations were limited to manually approved partners.
  • Other developers had to use API tokens, which are less convenient and poorly suited to delegated access.
  • Self-managed OAuth lets customers:
    • Request narrowly scoped permissions.
    • Give users clearer consent controls.
    • Revoke application access from the dashboard.
    • Build integrations and agentic tools using standard OAuth flows.
  • Cloudflare improved consent screens to identify the requesting application and its permissions, while making application ownership more visible to reduce phishing risks.

Planning the Hydra Upgrade

  • Cloudflare used Hydra, an open-source OAuth engine, but its older deployment could not support the platform’s growing scale and new use cases.
  • The upgrade was split into two stages:
    • First, move to the latest 1.X release.
    • Then, perform the larger 2.X migration.
  • The 1.X database migrations created operational risks:
    • Standard index creation could take exclusive locks on critical tables.
    • Schema changes added columns and moved data between tables.
    • Hydra’s SDK used SELECT *, creating deserialization problems after schema changes.
  • Cloudflare rewrote migrations to use CREATE INDEX CONCURRENTLY and built a custom Hydra version that selected explicit columns.

Designing a Blue-Green Migration

  • An in-place 2.X upgrade was rejected because of the volume of schema changes.
  • A blue-green deployment was chosen, but the migration would take several hours.
  • Disabling writes would prevent new authorizations and revocations, leaving users unable to manage application access during the upgrade.
  • Instead, Cloudflare kept writes enabled while reducing the amount of data that could be lost during the cutover:
    • Token expiry times were temporarily extended to multiple hours, reducing refresh-token writes.
    • Revocation events were written to Cloudflare Queues.
    • After switching to the green database, queued revocations could be replayed.
  • Preserving revocations was essential to prevent applications that users had disabled from regaining access.

Lessons from the 1.X Upgrade

  • The custom migrations completed faster than expected without user impact.
  • A hard cutover was necessary because the old Hydra version could not read tokens created by the new version.
  • The new version introduced stricter refresh-token invalidation:
    • Reusing a refresh token invalidated the entire access and refresh-token chain.
    • This caused problems for high-volume clients such as Wrangler and MCP clients.
  • Cloudflare added refresh-token coalescing in the Worker routing layer:
    • Briefly caching requests allowed retries to be served without triggering invalidation.
  • Hydra 2.X provides a configurable refresh-token grace period, offering a more direct solution for safe retries.

Executing the 2.X Upgrade

  • Cloudflare prepared a blue-green migration to avoid several hours of customer-facing downtime.
  • The strategy depended on reducing token writes, recording all revocations externally, switching databases, and replaying queued events afterward.
  • The provided article ends while beginning the detailed discussion of the 2.X execution.

Cloudflare’s approach demonstrates that opening a security-sensitive platform to broad OAuth usage requires more than exposing an authorization endpoint. Safe adoption depends on explicit permissions, transparent consent, reliable revocation, backward-compatible token behavior, and migration plans that protect users even during infrastructure cutovers.