The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 358 lines 14.6 KB
Raw
1 ---
2 title: Custom OAuth and OIDC
3 description: Add Keycloak OIDC sign-in to an Alchemy Worker with D1, one small step at a time.
4 ---
5
6 Start in an existing Alchemy project with [Bun](https://bun.sh) and a [configured Cloudflare profile](/cloudflare/setup). This standalone walkthrough uses Keycloak and Better Auth 1.7.5's `genericOAuth`; all application files are introduced below.
7
8 ## Add the auth dependencies
9
10 ```sh
11 bun add @alchemy.run/better-auth better-auth@1.7.5 kysely
12 ```
13
14 Use an `@alchemy.run/better-auth` release matching your installed Alchemy release. Keep your existing `alchemy` and `effect` dependencies.
15
16 ## Create the Auth service
17
18 Create `src/auth.ts`:
19
20 ```typescript
21 import { BetterAuth } from "@alchemy.run/better-auth";
22 import * as Config from "effect/Config";
23 import * as Context from "effect/Context";
24 import * as Effect from "effect/Effect";
25 import * as Layer from "effect/Layer";
26 import * as Option from "effect/Option";
27
28 const makeAuth = Effect.gen(function* () {
29 const baseURL = yield* Config.String("AUTH_BASE_URL").pipe(Config.option);
30 return yield* BetterAuth({
31 basePath: "/api/auth",
32 baseURL: Option.getOrUndefined(baseURL),
33 account: { accountLinking: { disableImplicitLinking: true } },
34 });
35 });
36
37 export class Auth extends Context.Service<
38 Auth,
39 Effect.Success<typeof makeAuth>
40 >()("app/Auth") {
41 static readonly layer = Layer.effect(Auth, makeAuth);
42 }
43 ```
44
45 The service keeps its options directly inside `BetterAuth` and reads Config during construction. Leaving `AUTH_BASE_URL` unset lets Better Auth use the incoming request's origin.
46
47 ## Start with OIDC disabled
48
49 Apply this addition to `src/auth.ts`:
50
51 ```diff lang="typescript"
52 const makeAuth = Effect.gen(function* () {
53 const baseURL = yield* Config.String("AUTH_BASE_URL").pipe(Config.option);
54 + const enabled = yield* Config.Boolean("OIDC_ENABLED").pipe(
55 + Config.withDefault(false),
56 + );
57 return yield* BetterAuth({
58 ```
59
60 OIDC stays disabled until you know the local URL and register its callback. The next addition reads credentials and installs the plugin only when this switch is enabled.
61
62 ## Register the OIDC provider
63
64 Apply both hunks to `src/auth.ts`, adding the imports and the inline plugin configuration:
65
66 ```diff lang="typescript"
67 import * as Option from "effect/Option";
68 +import * as Redacted from "effect/Redacted";
69 +import { genericOAuth } from "better-auth/plugins/generic-oauth";
70 @@
71 baseURL: Option.getOrUndefined(baseURL),
72 + plugins: enabled ? [genericOAuth({
73 + config: [{
74 + providerId: "company",
75 + clientId: yield* Config.String("OIDC_CLIENT_ID"),
76 + clientSecret: Redacted.value(yield* Config.Redacted("OIDC_CLIENT_SECRET")),
77 + discoveryUrl: yield* Config.String("OIDC_DISCOVERY_URL"),
78 + scopes: ["openid", "profile", "email"],
79 + pkce: true,
80 + authentication: "basic",
81 + requireIdTokenVerification: true,
82 + requireEmailVerification: true,
83 + disableProviderLogout: true,
84 + }],
85 + })] : [],
86 account: { accountLinking: { disableImplicitLinking: true } },
87 ```
88
89 In 1.7.5, `genericOAuth` registers a social provider named `company`, using `signIn.social` and `/api/auth/callback/company`, not the older `signIn.oauth2` flow. HTTP Basic client authentication matches Keycloak's client-secret token exchange, while required ID-token verification fails closed when discovery lacks usable verification metadata.
90
91 ## Keep application logout local
92
93 `disableProviderLogout: true` makes sign-out end the application session without terminating a shared Keycloak SSO session. Keep it unless you deliberately configure provider-wide logout and its registered return URLs.
94
95 ## Declare the database
96
97 Create `src/database.ts`:
98
99 ```typescript
100 import * as Cloudflare from "@alchemy.run/cloudflare";
101
102 export const AuthDb = Cloudflare.D1.Database("AuthDb");
103 ```
104
105 This declares the D1 database that will store users, accounts, and sessions. The same resource uses local D1 during `alchemy dev` and Cloudflare D1 when deployed.
106
107 ## Give Auth its database layer
108
109 Create `src/auth-layer.ts`:
110
111 ```typescript
112 import { CloudflareD1 } from "@alchemy.run/better-auth/CloudflareD1";
113 import * as Layer from "effect/Layer";
114 import { Auth } from "./auth.ts";
115 import { AuthDb } from "./database.ts";
116
117 export const AuthLive = Auth.layer.pipe(
118 Layer.provide(CloudflareD1(AuthDb)),
119 );
120 ```
121
122 `CloudflareD1` supplies the database binding and automatic supported schema migrations. Alchemy also provisions the stable signing secret automatically; do not invent a manual secret for this example.
123
124 ## Host Auth in a Worker
125
126 Create `src/worker.ts`:
127
128 ```typescript
129 import * as Cloudflare from "@alchemy.run/cloudflare";
130 import * as Effect from "effect/Effect";
131 import { Auth } from "./auth.ts";
132 import { AuthLive } from "./auth-layer.ts";
133
134 export default class AuthWorker extends Cloudflare.Worker<AuthWorker>()(
135 "AuthWorker",
136 {
137 main: import.meta.url,
138 compatibility: { flags: ["nodejs_compat"] },
139 assets: { directory: "./public", runWorkerFirst: ["/api/*"] },
140 },
141 Effect.gen(function* () {
142 const auth = yield* Auth;
143 return { fetch: auth.fetch };
144 }).pipe(Effect.provide(AuthLive)),
145 ) {}
146 ```
147
148 The Worker forwards API requests to Better Auth, including its session and callback endpoints. Static assets serve the browser page outside `/api/*`.
149
150 ## Define the stack
151
152 Use this as `alchemy.run.ts` for the walkthrough:
153
154 ```typescript
155 import * as Alchemy from "alchemy";
156 import * as Cloudflare from "@alchemy.run/cloudflare";
157 import * as Effect from "effect/Effect";
158 import AuthWorker from "./src/worker.ts";
159
160 export default Alchemy.Stack(
161 "CompanyAuth",
162 { providers: Cloudflare.providers(), state: Alchemy.localState() },
163 Effect.gen(function* () {
164 const worker = yield* AuthWorker;
165 return { url: worker.url };
166 }),
167 );
168 ```
169
170 The output exposes the Worker's actual URL. Preserve the local state directory so subsequent runs retain resource identities and the signing secret.
171
172 ## Add the browser page
173
174 Create `public/index.html`:
175
176 ```html
177 <!doctype html>
178 <html lang="en">
179 <head>
180 <meta charset="utf-8">
181 <meta name="viewport" content="width=device-width, initial-scale=1">
182 <title>Company sign-in</title>
183 </head>
184 <body>
185 <h1>Company sign-in</h1>
186 <button id="sign-in" type="button">Sign in with company</button>
187 <button id="read-session" type="button">Read session</button>
188 <button id="sign-out" type="button">Sign out</button>
189 <p id="status" role="status"></p>
190 <script type="module" src="/client.js"></script>
191 </body>
192 </html>
193 ```
194
195 The page provides three controls and a text-only status area. The browser bundle will be written to `public/client.js`.
196
197 ## Create the browser client
198
199 Create `src/client.ts`:
200
201 ```typescript
202 import { createAuthClient } from "better-auth/client";
203
204 const authClient = createAuthClient();
205 const status = document.getElementById("status")!;
206
207 async function run(action: () => Promise<string>) {
208 try {
209 status.textContent = await action();
210 } catch {
211 status.textContent = "Could not reach the server. Try again.";
212 }
213 }
214 ```
215
216 The client uses the page's origin and the default `/api/auth` path; no `genericOAuthClient` plugin is needed in 1.7.5. It imports no server Auth module or credentials.
217
218 ## Start company sign-in
219
220 Append to `src/client.ts`:
221
222 ```typescript
223 document.getElementById("sign-in")!.onclick = () => void run(async () => {
224 const { data, error } = await authClient.signIn.social({
225 provider: "company",
226 callbackURL: "/",
227 disableRedirect: true,
228 });
229 if (error) return "Could not start company sign-in. Check the configuration.";
230 if (!data?.url) return "No authorization URL was returned.";
231 window.location.assign(data.url);
232 return "Redirecting to company sign-in…";
233 });
234 ```
235
236 The provider ID matches the server's `company` registration. Better Auth returns the authorization URL and sends successful callbacks back to `/`.
237
238 ## Read the current session
239
240 Append to `src/client.ts`:
241
242 ```typescript
243 async function readSession(): Promise<string> {
244 const { data, error } = await authClient.getSession();
245 if (error) return "Could not check your session. Try again.";
246 return data ? `Signed in as ${data.user.name}.` : "Not signed in.";
247 }
248
249 document.getElementById("read-session")!.onclick = () => void run(readSession);
250 void run(readSession);
251 ```
252
253 The page checks the session on load, including after the OAuth callback. The button repeats that lookup without confusing a failed request with an anonymous session.
254
255 ## Sign out
256
257 Append to `src/client.ts`:
258
259 ```typescript
260 document.getElementById("sign-out")!.onclick = () => void run(async () => {
261 const { error } = await authClient.signOut();
262 return error ? "Could not sign out. Try again." : "Signed out.";
263 });
264 ```
265
266 This ends the application session. Because provider logout is disabled, a subsequent sign-in may reuse the user's existing Keycloak SSO session.
267
268 ## Bundle the browser client
269
270 ```sh
271 bun build ./src/client.ts --target browser --outdir ./public
272 ```
273
274 The final client is the initial `src/client.ts` block followed by the three append blocks, in order. The final `src/auth.ts` is its initial module with both labeled diffs applied; every other module above is complete as shown.
275
276 ## Discover the local origin
277
278 ```sh
279 bunx alchemy dev --stage company-guide
280 ```
281
282 Run without provider credentials or `OIDC_ENABLED=true` for this first start; Alchemy allocates a port and prints the actual origin. Keep OIDC disabled until the registration below is ready, and rebuild the browser bundle whenever you edit `src/client.ts`.
283
284 ## Create the Keycloak client
285
286 In Keycloak, select your application realm rather than the administration realm, open **Clients → Create client**, choose **OpenID Connect**, and set a client ID such as `alchemy-auth`. Enable **Client authentication** and **Standard flow**, leaving implicit flow and direct access grants disabled.
287
288 ## Register the callback
289
290 ```text
291 /api/auth/callback/company
292 ```
293
294 In **Login settings**, set the home URL to the printed origin and add that origin plus this path to **Valid redirect URIs**, without wildcards. Save the client and copy its secret from **Credentials** for the server-side token exchange.
295
296 ## Configure identity claims
297
298 Require S256 PKCE in the client's advanced settings where available, and ensure the `profile` and `email` scopes supply `sub`, `name`, `email`, and `email_verified`. Configure real realm email delivery and verification, and use verified realm users rather than marking arbitrary addresses verified.
299
300 Keycloak's [server administration guide](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients) covers client configuration. Its [OIDC guide](https://www.keycloak.org/securing-apps/oidc-layers) describes discovery endpoints.
301
302 ## Supply server credentials
303
304 Create `.env.local.example`, then copy it to a gitignored `.env.local` and replace the placeholder values:
305
306 ```dotenv
307 OIDC_ENABLED=true
308 OIDC_CLIENT_ID=alchemy-auth
309 OIDC_CLIENT_SECRET=replace-with-your-client-secret
310 OIDC_DISCOVERY_URL=https://identity.example.com/realms/my-app/.well-known/openid-configuration
311 # Leave AUTH_BASE_URL unset for local request-origin discovery.
312 ```
313
314 Discovery must be reachable from the Worker and publish the expected issuer, authorization/token endpoints, signing algorithms, and `jwks_uri`; use the application realm's real URL. These server-side Config values must stay out of `VITE_*`, browser bundles, source control, and logs.
315
316 ## Enable OIDC locally
317
318 ```sh
319 bunx alchemy dev --stage company-guide --env-file .env.local
320 ```
321
322 Stop the first dev process before running this command, and update Keycloak's callback if the newly printed origin changes. Open that origin, select **Sign in with company**, then use **Read session** and **Sign out** to exercise the roundtrip.
323
324 ## Set the production origin
325
326 Create `.env.production.example` as a template for your private production configuration:
327
328 ```dotenv
329 AUTH_BASE_URL=https://auth.example.com
330 OIDC_ENABLED=true
331 OIDC_CLIENT_ID=replace-with-production-client-id
332 OIDC_CLIENT_SECRET=replace-with-production-client-secret
333 OIDC_DISCOVERY_URL=https://identity.example.com/realms/production/.well-known/openid-configuration
334 ```
335
336 Replace the example origin with the actual HTTPS Worker origin, without a trailing slash or `/api/auth`; `baseURL` does not attach a domain to the Worker. Use separate production clients or realms, register that origin plus `/api/auth/callback/company`, and supply these values through your deployment's server configuration.
337
338 ## Preserve provider identity
339
340 `company` determines both the callback path and stored provider identity: do not rename it or point it at an unrelated issuer once accounts exist. Discovery-based OIDC uses the provider profile's `sub` as the account subject, not a mutable email address, and this configuration requires verified ID tokens with nonce binding enabled.
341
342 Keep implicit linking disabled, verified-email checks, and the same-email restriction if you later add account linking. Follow Better Auth's [account-linking guidance](https://www.better-auth.com/docs/concepts/users-accounts#account-linking) rather than adding `company` to `trustedProviders` or merging rows to bypass ownership checks.
343
344 ## Adapt another provider
345
346 Edit the inline `genericOAuth` configuration in `src/auth.ts`, preserving any other plugins when integrating into a larger application. For plain OAuth, use reviewed `authorizationUrl`, `tokenUrl`, and `userInfoUrl` settings instead of OIDC discovery, and verify the vendor's token authentication, PKCE, identity, and email-trust requirements.
347
348 Plain OAuth defaults to the raw profile's immutable `id`; nonstandard fields require an `accountSubject` resolver and possibly `getUserInfo` or `mapProfileToUser`. Consult the upstream [Generic OAuth documentation](https://www.better-auth.com/docs/plugins/generic-oauth) rather than merely removing ID-token verification from this OIDC example.
349
350 ## Diagnose callback failures
351
352 Better Auth displays callback failures on its built-in `/api/auth/error` page; no custom application error query is needed. Keep ID-token verification, nonce binding, state, origin, and CSRF checks enabled.
353
354 For an unknown provider, check discovery reachability and issuer/JWKS metadata; for callback mismatches, compare the exact `/api/auth/callback/company` registration. For token-exchange failures, compare the secret and authentication method, then start a fresh sign-in instead of replaying codes or logging tokens and full callback URLs.
355
356 ## Resolve email-verification failures
357
358 `requireEmailVerification` checks local user verification and can leave a created or linked account without a session. For `email_not_verified`, review both issuer and local verification state: an existing unverified local user needs a real [email-verification flow](https://www.better-auth.com/docs/concepts/email), not a database edit to mark the user verified.