A New Login Flow for Wrangler

The Workers Developer Productivity team has been focused on improving the developer experience of wrangler, the command line interface for Cloudflare Workers. The current authorization method relies on users manually generating API tokens from the dashboard and pasting them into the CLI—a process that works but adds friction. The OAuth 2.0 login protocol has now been integrated to streamline this and introduce token management options.

The protocol involves several key participants. The resource owner is the user who can grant access to a protected resource. The resource server hosts the protected resource; here, it is the Cloudflare API. The client is the application making requests on behalf of the resource owner, which in this case is Wrangler. The authorization server issues access tokens after authenticating the user, managed by the OAuth 2.0 service provider.

Bringing OAuth 2.0 to Wrangler

How Authorization Works

Wrangler implements the Authorization Code Flow with PKCE (Proof Key for Code Exchange) challenges. When a user invokes wrangler login, they first authenticate on the Cloudflare dashboard. After logging in, they see an authorization page to grant or deny Wrangler permission. Upon approval, Wrangler receives an authorization grant, exchanges it for an access token and a refresh token, and stores them on disk. The access token is used for authenticated API requests; as it is short-lived, refresh tokens are employed to obtain new access tokens as they expire.

Successful interaction from User to Wrangler and OAuth service provider using the wrangler login command.

This flow also enables granular scopes. Users can specify which scopes they require, a step up from the all-or-nothing nature of API tokens. A user can request only account and user read permissions with a command like the following:

wrangler login --scopes account:read user:read

To view all scopes, use wrangler login --scopes-list. Revoking access is equally direct—the standard wrangler logout command invalidates the refresh token at the authorization server, which in turn invalidates the associated access token.

Security Measures

A focus on security was central to this integration. Several mechanisms protect against common OAuth vulnerabilities:

  • CSRF state parameter: During the initial request, Wrangler generates a unique random value used to verify that the response comes from the legitimate OAuth service provider.
  • PKCE code_challenge: When exchanging the authorization grant for an access token, Wrangler includes a code_challenge. The authorization server verifies this value, ensuring the request originates from the genuine application and mitigating stolen authorization grant attacks.
  • Short-lived access tokens: If an access token is intercepted, its limited lifespan reduces exposure. The response options are to wait for expiration, exchange the refresh token to obtain a new access token (invalidating the old one), or revoke both tokens entirely.

Availability Options

OAuth 2.0 support in Wrangler arrives in version 1.19.3. Those who prefer the earlier method are unaffected; the wrangler config command remains available for using API tokens and global API keys.