Add authentication section to Agents docs#28654
Conversation
github-actions
Bot
added
product:agents
github-actions
Bot
assigned
elithrar,
irvinebroque,
rita3ko,
thomasgauvin,
threepointone and
whoiskatrin
deathbyknowledge
changed the title
deathbyknowledge
requested review from
elithrar,
irvinebroque,
rita3ko,
thomasgauvin,
threepointone and
whoiskatrin
as code owners
| - You need session management, password hashing, and JWT issuance in one package. | ||
| - You are building a product where users create accounts and interact with personalized Agent instances. | ||
|
|
||
| You can view the full example code on [GitHub](https://github.com/cloudflare/agents/tree/main/examples/auth-agent). |
There was a problem hiding this comment.
Sunil ended up rewriting the example. Either we change the docs to follow the example or just don't mention the example
There was a problem hiding this comment.
Good catch — confirmed the auth-agent example was rewritten in cloudflare/agents#948 and now ships as a lightweight JWT demo (no Better Auth). Addressed in the replacement PR #30053 by removing the two links to the example from better-auth.mdx. Also fixed the auth-agent description in index.mdx (it incorrectly said "Complete working example with Better Auth"), and added a cross-link from token-and-middleware.mdx since the rewritten example actually demonstrates that page's JWT + onBeforeConnect / onBeforeRequest pattern.
|
|
||
| :::note[Lazy initialization] | ||
|
|
||
| The `getAuth()` function uses a lazy singleton pattern because `betterAuth()` accesses environment bindings (like `env.AUTH_DB`) that are only available inside a request context on Workers, not at module scope. |
There was a problem hiding this comment.
I don't believe this is fully true. We can use
import { env } from "cloudflare:workers"
There are other reasons for using s lazy singleton pattern though. I think it's best explained in the changes in this commit
There was a problem hiding this comment.
You're right — import { env } from "cloudflare:workers" does give module-scope access to bindings, so the original note was inaccurate. Rewrote it in the replacement PR #30053 using the reasoning from the commit you linked: the real reason for the lazy singleton is that betterAuth()'s internal init() does async I/O (telemetry filesystem detection via dynamic import("fs/promises")) that only resolves inside a request context — calling betterAuth() at module scope causes auth.handler() to hang indefinitely. Also updated the inline code comment above the snippet to match.
|
Hey there, we've marked this pull request as stale because there's no recent activity on it. This label is helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant). |
Adds a dedicated Authentication section with focused pages for each approach: - Overview (authentication/index.mdx) with decision table and best practices. - Token and middleware auth (authentication/token-and-middleware.mdx) covering static token validation, JWT verification, passing tokens from clients, per-instance authorization, and Hono middleware. - Workers OAuth Provider (authentication/oauth-provider.mdx) covering OAuth 2.1 authorization server setup, third-party IdP integration (GitHub example), and token scoping and revocation. - Full-stack auth with Better Auth (authentication/better-auth.mdx) with a full tutorial for user management, D1 setup, JWT issuance, and client integration. This replaces the stale PR #28654. Incorporates review feedback: - Removed links to the cloudflare/agents auth-agent example from better-auth.mdx; the example was rewritten as a lightweight JWT demo and no longer demonstrates Better Auth. - Corrected the 'Lazy initialization' note in better-auth.mdx. Environment bindings are available at module scope via 'import { env } from "cloudflare:workers"'. The real reason for the lazy singleton is that betterAuth()'s init() does async I/O (telemetry filesystem detection via dynamic import("fs/promises")) that only resolves inside a request context. - Added a 'Complete example' link to token-and-middleware.mdx pointing at the auth-agent example, since that page describes the JWT pattern the example now demonstrates. - Updated the auth-agent description in index.mdx to reflect that it demonstrates JWT auth, not Better Auth.
|
Closed in favor of #30053 so @Muhammad-Bin-Ali could incorporate outstanding comments. |
9 participants
Summary
Adds a new Authentication section to the Agents documentation, replacing the single-page auth guide with a dedicated section containing focused pages for each approach:
authentication/index.mdx) — Decision table for choosing an auth approach, core principle (authenticate before the Agent), and best practices.authentication/token-and-middleware.mdx) — Static token validation, JWT verification, passing tokens from clients, per-instance authorization, and custom routing with Hono middleware.authentication/oauth-provider.mdx) — OAuth 2.1 authorization server setup, third-party IdP integration (GitHub example), token scoping and revocation.authentication/better-auth.mdx) — Complete tutorial for user management with sign-up/sign-in, D1 database setup, JWT issuance, and client integration.Screenshots (optional)
Documentation checklist