Documentation: Contradictory requirements for `baseURL` configuration causing OAuth authentication failures

[andrey-kokoev]

Environment

---

• Operating System: Windows_NT
• Node Version: v20.13.1
• Nuxt Version: 3.17.3
• CLI Version: 3.25.1
• Nitro Version: 2.11.11
• Package Manager: pnpm@10.11.0
• Builder: -
• User Config: typescript, modules, auth, devtools, future, compatibilityDate, ssr, nitro, hub, css, runtimeConfig
• Runtime Modules: @nuxthub/core@0.8.27, @nuxt/eslint@1.3.1, @pinia/nuxt@0.11.0, @nuxt/ui@3.1.1, @nuxt/icon@1.12.0, @vueuse/nuxt@13.1.0, @sidebase/nuxt-auth@0.10.1
• Build Modules: -

---

Reproduction

1. Create a new Nuxt 3 project with @sidebase/nuxt-auth v0.10.1
2. Configure Azure AD authentication provider with all required credentials
3. Set up authentication using the path-only approach: baseURL: '/api/auth'
4. Attempt to authenticate with Azure AD

Result: Client-side authentication requests go to /providers instead of /api/auth/providers, causing authentication failures.

Describe the bug

Issue Description

The documentation contains contradictory instructions regarding how baseURL should be configured, specifically whether it should contain the full URL (protocol + domain + path) or just the path portion. This inconsistency directly leads to authentication failures with OAuth providers.

Investigation Steps Taken

1. I've searched through open issues and discussions related to baseURL configuration and authentication failures
2. I've reviewed the documentation thoroughly and found direct contradictions
3. I've tested both configuration approaches in a minimal project setup

Minimal Reproduction

1. Create a new Nuxt 3 project with @sidebase/nuxt-auth v0.10.1
2. Configure Azure AD authentication provider with all required credentials
3. Set up authentication using the path-only approach: baseURL: '/api/auth'
4. Attempt to authenticate with Azure AD

Result: Client-side authentication requests go to /providers instead of /api/auth/providers, causing authentication failures.

Evidence of Contradictory Documentation

1. In configuration.md:

   baseURL: The full URL at which the app will run combined with the path to authentication.

2. In url-resolutions.md:

   export default defineNuxtConfig({
     auth: {
       baseURL: 'https://example.com/api/auth',
       // ...

3. In multiple GitHub issues and deployment guides, only the path portion is used:

   auth: {
     baseURL: '/api/auth'
   }

Root Cause Analysis

The inconsistency appears to be between server-side and client-side URL resolution. While the server correctly processes the configuration, the client-side components are not properly inheriting the base URL prefix, causing requests to incorrect endpoints.

This is particularly problematic with OAuth providers where precise URL construction is essential for the authentication flow to succeed.

Proposed Solution

Documentation must be updated to:

1. Clearly specify the correct format for baseURL in both client and server contexts
2. Include version-specific guidance if the requirement has changed between versions
3. Remove contradictory examples or explicitly label them as version-specific

[phoenix-ru]

I couldn't reproduce the issue you outlined. When using the default baseURL: '/api/auth' with Azure AD, I get correct redirects

[w20k]

I'm currently experiencing the same issue and am still investigating the root cause. I'll update once I've identified what's causing the problem or found a solution.