Important
Action required
-
If you use
requireMcpAuthwithout anissueroption and verify tokens against keys fetched from a URL (jwksUrlor the JWT plugin'sjwks.remoteUrl), make sure tokens carry the discovery issuer, or passissuerexplicitly. (#12714) -
If you verify OAuth provider tokens outside Better Auth against a pinned
jwt.issueror base URL, switch to the discoveryissuer, and accept both values until JWT access tokens issued before the upgrade expire. (#12714) -
If you throw from
customTokenResponseFieldsor anextensions[].claims.idTokencontributor to refuse tokens, move that check tobeforeTokenIssuance. (#12663) -
If you use CIBA, run
npx auth@latest migrate, ornpx auth@latest generateand apply the schema with your ORM, before you upgrade to add the newapprovedViaConsentcolumn on thecibaRequestmodel. (#12801) -
If you have OAuth resources with an empty stored
allowedScopesthat relied on denying every scope, setdisabled: trueon each (or give it real scopes) before the first 1.8 process starts, and remove any configallowedScopes: [], which now fails at startup. (#12743) -
If you use CIBA with
approvalPage, record each decision withauth.api.completeCibaRequest, and if your code extendsCibaOptionswithinterface, use an intersection type instead. If yoursendNotificationusesurlas a string, check it forundefined. (#12712) -
If you use CIBA, run
npx auth@latest migratewith the built-in Kysely adapter, or runnpx auth@latest generateand apply the schema with your ORM, to add theactorcolumn tocibaRequestbefore you upgrade. (#12712) -
feat(ciba)!: require client authentication; 401 for invalid_client (#12712)
CIBA deployments can now read a pending request on their own approval page with the new server-only
auth.api.getCibaRequest({ body: { requestId, userId } }). It returns what to show the user (client, scopes, resources, binding message, ACR values, authorization details, actor, and expiry), ornullwhencompleteCibaRequestwould refuse the request as unknown, such as a decided or expired request or one for another user, and when the client no longer exists.sendNotificationnow also receives the requestedresources. -
If your client handles
/oauth2/bc-authorizeerrors, expect status 401 withinvalid_clientinstead of 400, including when the request has noclient_id. (#12712) -
If you set
allowPublicClients, remove it and register those clients with a secret or withprivate_key_jwt. (#12712) -
If you use the OAuth provider, run
npx auth@latest migrate, or generate and apply the schema, to add theaccessTokenFormatcolumn tooauthResourcebefore deploying, or every request will fail the schema check. (#12656) -
If a relying party sits on an internal network and its public-looking name resolves to a private address, list its exact origin in
trustedOriginsto keep delivering logout tokens to it. (#12697) -
If you use CIBA ping mode with a client whose notification endpoint resolves to a private or internal address, list that endpoint's origin in
trustedOriginsat initialization to keep receiving pings. (#12690) -
If you use a custom
jwt.signin the JWT plugin, make it apply itsheaderargument, which carriestyp: at+jwt, or the provider will reject its access tokens. (#12667) -
If a client reads
nameorpicturefrom UserInfo and expects an empty string, handle the missing key, or return the claim fromcustomUserInfoClaims. (#12803) -
feat(mcp)!: pass requireMcpAuth handlers the sub the token carries (#12672)
requireMcpAuthpasses the handler thesubthe access token carries, as in 1.7, instead of the internal user ID that 1.8.0-beta.10 passed. For a client withsubject_type: "pairwise", an opaque token'ssubis now its pairwise subject, as at/oauth2/introspect, and a JWT'ssubis the pairwise subject when the provider setsaccessTokenSubject: "pairwise". Other tokens keep the user ID.Breaking for 1.8.0-beta.10 users: beta.10 passed the user ID even for pairwise tokens. An MCP handler that looks users up by
subfor pairwise clients must now map the pairwise subject itself, or keep those clients onsubject_type: "public". -
If your clients rotate
private_key_jwtkeys, keep thejwks_urireachable, publish the new key and wait 5 minutes before signing with it. (#12700) -
If you want a user's OAuth tokens to stay valid across a password reset, set
revokeGrantsOnPasswordReset: false. (#12738) -
If you rely on
getOAuthConsentorgetOAuthConsentsreturning only the last approval, or on the consent page appearing again for previously approved access, update that code; consents now accumulate everything the user approved and did not take back. (#12798)
better-auth
Features
- Added
tokenEndpoint,userInfoEndpoint, andjwksEndpointoverrides to social providers so you can point them at a local OAuth emulator or sandbox (#12746) - Added
prepareDeviceCodeRedemptionso custom device code issuers can run a final check before the code is spent (#12663) - Added an
onPasswordResetplugin hook that runs after a password reset, including for users with no live session (#12738)
For detailed changes, see CHANGELOG
@better-auth/oauth-provider
❗ Breaking Changes
- Changed the OAuth consent page to add each approval to the user's stored consent instead of replacing it (#12798)
- Changed the OAuth provider to refetch a client's
jwks_urifor an unknown key at most once every 60 seconds (#12700) - Changed UserInfo to omit the
nameandpictureclaims when the user's name or image is an empty string (#12803) - Changed the OAuth provider to accept JWT access tokens only when their header has
typ: at+jwt(#12667) - Fixed back-channel logout to skip delivery to a
backchannel_logout_uriwhose host resolves to a non-public address (#12697) - Changed OAuth resource
allowedScopesto a single storable contract, where an empty stored list now allows every requested scope instead of denying all (#12743) - Fixed OAuth provider tokens to carry the same
issas the discoveryissuer, so clients and the end-session endpoint accept them (#12714)
Features
- Added
serverContexttoprovider.issueAuthorizationCode()so plugin endpoints can store values with a code and read them back when it is redeemed (#12676) - Added a
beforeTokenIssuanceoption that lets you refuse token issuance for any grant before any token is stored (#12663) - Changed
customTokenResponseFieldsandextensions[].claims.idTokencontributors to run after the DPoP check andbeforeTokenIssuance(#12663) - Added a
beforeAuthorizationoption to run a policy on each authorization request, such as requiring a new sign-in or refusing the request (#12657) - Added an
amroption toprovider.issueAuthorizationCode()so plugin endpoints can report the authentication methods they verified (#12654) - Added
provider.validateAuthorizationRequest()so plugin endpoints can reject an invalid OAuth authorization request before the user signs in (#12654) - Added support for a function-valued
accessTokenExpiresInto set access token lifetime per user grant, capped by the newaccessTokenMaxExpiresIn(#12740) - Added an
idToken: falseoption toissueTokensso extension grants can skip the ID token while keeping theopenidscope (#12665) - Added
tokenResponseFieldsso OAuth provider extensions can add their own fields to the token response (#12664) - Added
grantIdto claim callbacks andcustomTokenResponseFieldsso apps can tell separate authorizations apart across refreshes (#12662) - Changed refresh token replay to revoke only the affected grant instead of every refresh token the client holds for the user (#12754)
- Added an
onTokenRevokedoption that reports revoked grants and access tokens so you can notify resource servers or keep an audit log (#12678) - Improved
provider.issueAuthorizationCode()to reuse same-requestauthenticateClient()andverifyDpopProof()results instead of rejecting them as replayed (#12759) - Added revocation of a user's OAuth access and refresh tokens, including
offline_accessgrants, on password reset whenemailAndPassword.revokeSessionsOnPasswordResetis enabled (#12738) - Added a per-resource
accessTokenFormat: "opaque"option so protected resources can receive opaque access tokens instead of JWTs (#12656) - Changed OAuth authorization requests without
scopeto use the intersection of the client's registered scopes andclientRegistrationDefaultScopes(#12742)
Bug Fixes
- Fixed revoked sessions being able to approve or deny interaction requests, such as CIBA requests or OAuth device codes, while
session.cookieCachestill served them (#12690) - Fixed device codes to be rejected with
invalid_grantwhen the user's stored consent was deleted or narrowed after approval (#12790) - Fixed authorization codes to be rejected with
invalid_grantwhen the user's stored consent was deleted or narrowed after the code was issued (#12737) - Fixed the OAuth provider token endpoint to exchange authorization codes that carry no scopes instead of rejecting them with
invalid_scope(#12741) - Fixed concurrent matching refresh requests to get the same rotated response instead of
invalid_grantwhenrefreshTokenReuseIntervalis set (#12739) - Fixed deleting an OAuth consent to also revoke the access and refresh tokens issued under it (#12736)
For detailed changes, see CHANGELOG
@better-auth/ciba
❗ Breaking Changes
- Added a CIBA
approvalPageoption so requests are approved only on your own page or app, and/oauth2/authorizeno longer approves them (#12712) - Added CIBA delegated access tokens that name the user as
suband an actor as theactclaim, using the newresolveActoroption (#12712) - feat(ciba)!: require client authentication; 401 for invalid_client (#12712)
- Changed CIBA
/oauth2/bc-authorizeto answerinvalid_clientwith status 401 and aWWW-Authenticatechallenge instead of 400 (#12712) - Removed the CIBA
allowPublicClientsoption, so clients usingtoken_endpoint_auth_method: "none"are now always rejected withinvalid_client(#12712)
Bug Fixes
- Fixed CIBA requests approved from a link so they can no longer be redeemed after the user deletes or narrows the stored consent (#12801)
- Fixed CIBA ping mode to re-check the notification endpoint's host and skip the ping when it resolves to a non-public address (#12690)
- Fixed CIBA ping notifications so providers running on Cloudflare Workers can deliver them to clients (#12690)
For detailed changes, see CHANGELOG
@better-auth/mcp
❗ Breaking Changes
- feat(mcp)!: pass requireMcpAuth handlers the sub the token carries (#12672)
- Changed
requireMcpAuthto expect the OAuth provider's discovery issuer by default, which follows a customjwt.issuer(#12714)
For detailed changes, see CHANGELOG
@better-auth/cimd
Features
- Added
createCimdMetadataResolverso runtimes that build the auth instance per request can share one CIMD metadata cache, fetch limits, and in-flight fetches (#12745)
Bug Fixes
- Fixed CIMD so a flood of refused
client_idURLs no longer exhausts the metadata fetch budget and makes allowed clients fail withtemporarily_unavailable(#12744)
For detailed changes, see CHANGELOG
@better-auth/core
Features
- Added
tokenEndpoint,userInfoEndpoint, andjwksEndpointoverrides to social providers so you can point them at a local OAuth emulator or sandbox (#12746) - Added an
onPasswordResetplugin hook that runs after a password reset, including for users with no live session (#12738)
For detailed changes, see CHANGELOG
Contributors
Thanks to everyone who contributed to this release:
@alfaroukhesham, @cursoragent, @Garv978, @GautamBytes, @ghazy2001, @grant0417, @gustavovalverde, @kaiizer777, @Lakshya0604, @PrabalParihar, @risi-au, @vjymisal0, @waleed-mirza
Full changelog: v1.8.0-beta.10...v1.8.0-beta.11