github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-23 23:52:05 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[GH-ISSUE #7453] oauth-provider: well-known endpoints should be mountable at origin root for spec compliance #10815

New Issue
Closed
opened 2026-04-13 07:10:23 -05:00 by GiteaMirror · 6 comments
GiteaMirror commented 2026-04-13 07:10:23 -05:00
Owner
Copy Link

Originally created by @gustavovalverde on GitHub (Jan 18, 2026).
Original GitHub issue: https://github.com/better-auth/better-auth/issues/7453

The oauth-provider plugin mounts /.well-known/oauth-authorization-server and /.well-known/openid-configuration endpoints under the base path (e.g., /api/auth/.well-known/openid-configuration).

Per RFC 8414 Section 3 and OpenID Connect Discovery 1.0 Section 4, these endpoints must be located at the origin root when the issuer has no path component:

"Authorization servers supporting metadata MUST make a JSON document containing metadata [...] available at a path formed by inserting a well-known URI string into the authorization server's issuer identifier between the host component and the path component, if any."
— RFC 8414 Section 3

"OpenID Providers supporting Discovery MUST make a JSON document available at the path formed by concatenating the string /.well-known/openid-configuration to the Issuer."
— OpenID Connect Discovery 1.0 Section 4

The current implementation uses SERVER_ONLY metadata and prints warnings asking developers to set up reverse-proxy rules manually.

Describe the solution you'd like

Add a publicEndpoints plugin feature that mounts endpoints at the origin root instead of under the base path.

This would require:

  1. Add publicEndpoints field to the plugin type definition
  2. Add a publicRouter that mounts at "/" instead of the base path
  3. Migrate well-known endpoints from endpoints to publicEndpoints
// Current (mounted at /api/auth/.well-known/...)
endpoints: {
  getOpenIdConfig: createAuthEndpoint("/.well-known/openid-configuration", ...)
}

// Proposed (mounted at /.well-known/...)
publicEndpoints: {
  getOpenIdConfig: createAuthEndpoint("/.well-known/openid-configuration", ...)
}

Describe alternatives you've considered

  1. Keep current approach - Developers manually configure nginx/proxy rules. Works but adds setup friction.

  2. Configuration option - Add an option like mountWellKnownAtRoot: true (default false) to opt-in. Safest but requires explicit configuration.

Additional context

Affected endpoints:

  • /.well-known/oauth-authorization-server (RFC 8414)
  • /.well-known/openid-configuration (OpenID Connect Discovery)
  • /.well-known/oauth-protected-resource (in mcp.ts)

References:

Originally created by @gustavovalverde on GitHub (Jan 18, 2026). Original GitHub issue: https://github.com/better-auth/better-auth/issues/7453 The `oauth-provider` plugin mounts `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration` endpoints under the base path (e.g., `/api/auth/.well-known/openid-configuration`). Per RFC 8414 Section 3 and OpenID Connect Discovery 1.0 Section 4, these endpoints must be located at the origin root when the issuer has no path component: > "Authorization servers supporting metadata MUST make a JSON document containing metadata [...] available at a path formed by inserting a well-known URI string into the authorization server's issuer identifier between the host component and the path component, if any." > — [RFC 8414 Section 3](https://datatracker.ietf.org/doc/html/rfc8414#section-3) > "OpenID Providers supporting Discovery MUST make a JSON document available at the path formed by concatenating the string `/.well-known/openid-configuration` to the Issuer." > — [OpenID Connect Discovery 1.0 Section 4](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) The current implementation uses `SERVER_ONLY` metadata and prints warnings asking developers to set up reverse-proxy rules manually. ## Describe the solution you'd like Add a `publicEndpoints` plugin feature that mounts endpoints at the origin root instead of under the base path. This would require: 1. Add `publicEndpoints` field to the plugin type definition 2. Add a `publicRouter` that mounts at `"/"` instead of the base path 3. Migrate well-known endpoints from `endpoints` to `publicEndpoints` ```typescript // Current (mounted at /api/auth/.well-known/...) endpoints: { getOpenIdConfig: createAuthEndpoint("/.well-known/openid-configuration", ...) } // Proposed (mounted at /.well-known/...) publicEndpoints: { getOpenIdConfig: createAuthEndpoint("/.well-known/openid-configuration", ...) } ``` ## Describe alternatives you've considered 1. **Keep current approach** - Developers manually configure nginx/proxy rules. Works but adds setup friction. 2. **Configuration option** - Add an option like `mountWellKnownAtRoot: true` (default false) to opt-in. Safest but requires explicit configuration. ## Additional context Affected endpoints: - `/.well-known/oauth-authorization-server` (RFC 8414) - `/.well-known/openid-configuration` (OpenID Connect Discovery) - `/.well-known/oauth-protected-resource` (in mcp.ts) References: - [RFC 8414 - OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) - [RFC 5785 - Defining Well-Known URIs](https://datatracker.ietf.org/doc/html/rfc5785)
GiteaMirror added the locked label 2026-04-13 07:10:23 -05:00
GiteaMirror commented 2026-04-13 07:10:28 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Jan 18, 2026):

It sounds like you're raising an important issue regarding the OAuth provider and well-known endpoints compliance with specifications. Currently, the oauth-provider plugin mounts endpoints such as /.well-known/oauth-authorization-server and /.well-known/openid-configuration under a base path instead of the origin root. As per RFC 8414 and OpenID Connect Discovery specifications, these must be located at the root when the issuer lacks a path component.

Your proposed solution to add a publicEndpoints field to mount these endpoints correctly is well-aligned with compliance needs. It’s a viable approach and addresses the friction in setup caused by requiring developers to configure manual reverse-proxy rules.

Next steps could include discussing this feature request with the team and gathering more feedback from the community on potential implications of this change or exploring how multiple configuration options might impact existing implementations.

In the meantime, would you like assistance with specific implementation details or perhaps exploring alternatives to your current setup?

If you need more help, tag @better-auth-agent in a comment so I can respond.

Diagram • Discord • GitHub

Diagram Join Star

<!-- gh-comment-id:3765140725 --> @better-auth-agent[bot] commented on GitHub (Jan 18, 2026): It sounds like you're raising an important issue regarding the OAuth provider and well-known endpoints compliance with specifications. Currently, the `oauth-provider` plugin mounts endpoints such as `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration` under a base path instead of the origin root. As per RFC 8414 and OpenID Connect Discovery specifications, these must be located at the root when the issuer lacks a path component. Your proposed solution to add a `publicEndpoints` field to mount these endpoints correctly is well-aligned with compliance needs. It’s a viable approach and addresses the friction in setup caused by requiring developers to configure manual reverse-proxy rules. Next steps could include discussing this feature request with the team and gathering more feedback from the community on potential implications of this change or exploring how multiple configuration options might impact existing implementations. In the meantime, would you like assistance with specific implementation details or perhaps exploring alternatives to your current setup? _If you need more help, tag @better-auth-agent in a comment so I can respond._ <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) • [Discord](https://discord.gg/better-auth) • [GitHub](https://github.com/better-auth/better-auth) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/better-auth_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/better-auth) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/better-auth/better-auth)
GiteaMirror commented 2026-04-13 07:10:28 -05:00
Author
Owner
Copy Link

@Bekacru commented on GitHub (Jan 19, 2026):

I think the best approach is to call auth.api under the root path. Mounting Better Auth at the root creates a lot of confusion, and since most users use Better Auth alongside an existing app, it’s likely to cause conflicts.

<!-- gh-comment-id:3769994616 --> @Bekacru commented on GitHub (Jan 19, 2026): I think the best approach is to call auth.api under the root path. Mounting Better Auth at the root creates a lot of confusion, and since most users use Better Auth alongside an existing app, it’s likely to cause conflicts.
GiteaMirror commented 2026-04-13 07:10:28 -05:00
Author
Owner
Copy Link

@himself65 commented on GitHub (Jan 20, 2026):

See our demo https://github.com/better-auth/better-auth/tree/canary/demo/nextjs/app/.well-known

Due to our design issue. We don't want to mount endpoints on the root level. So you should do that manually.

<!-- gh-comment-id:3771148277 --> @himself65 commented on GitHub (Jan 20, 2026): See our demo https://github.com/better-auth/better-auth/tree/canary/demo/nextjs/app/.well-known Due to our design issue. We don't want to mount endpoints on the root level. So you should do that manually.
GiteaMirror commented 2026-04-13 07:10:29 -05:00
Author
Owner
Copy Link

@gustavovalverde commented on GitHub (Jan 21, 2026):

Mounting Better Auth at the root creates a lot of confusion

@Bekacru @himself65 What I'm proposing is not to mount Better Auth at root. Only /.well-known/* paths would be intercepted (per RFC 5785), and this would work transparently; without additional configurations. Consider this is just an option for plugins.

I'll open a PR so you can better visualize what I'm proposing (I already have this working without issues on my side, and not breaking changes were added to better auth).

<!-- gh-comment-id:3777638976 --> @gustavovalverde commented on GitHub (Jan 21, 2026): > Mounting Better Auth at the root creates a lot of confusion @Bekacru @himself65 What I'm proposing is not to mount Better Auth at root. Only `/.well-known/*` paths would be intercepted (per RFC 5785), and this would work transparently; without additional configurations. Consider this is just an option for plugins. I'll open a PR so you can better visualize what I'm proposing (I already have this working without issues on my side, and not breaking changes were added to better auth).
GiteaMirror commented 2026-04-13 07:10:29 -05:00
Author
Owner
Copy Link

@gustavovalverde commented on GitHub (Jan 21, 2026):

Due to our design issue. We don't want to mount endpoints on the root level. So you should do that manually.

One side effect (and a great benefit) of this approach from #7524 is that users are not required to mount a reverse proxy just for the sake of having a spec compliant plugin for OIDC.

<!-- gh-comment-id:3777924210 --> @gustavovalverde commented on GitHub (Jan 21, 2026): > Due to our design issue. We don't want to mount endpoints on the root level. So you should do that manually. One side effect (and a great benefit) of this approach from #7524 is that users are not required to mount a reverse proxy just for the sake of having a spec compliant plugin for OIDC.
GiteaMirror commented 2026-04-13 07:10:30 -05:00
Author
Owner
Copy Link

@gustavovalverde commented on GitHub (Feb 16, 2026):

Just re-pinging here as a follow-up @himself65 @Bekacru

If needed, I can demo this or even hop on a call or open a discussion in Discord to better explain this. This has 0 impact in the existing better-auth behavior, and allows to create compliant plugins (which I have a few waiting for this)

<!-- gh-comment-id:3908139732 --> @gustavovalverde commented on GitHub (Feb 16, 2026): Just re-pinging here as a follow-up @himself65 @Bekacru If needed, I can demo this or even hop on a call or open a discussion in Discord to better explain this. This has 0 impact in the existing better-auth behavior, and allows to create compliant plugins (which I have a few waiting for this)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label locked
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#10815
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?