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: [email protected]
• Builder: -
• User Config: typescript, modules, auth, devtools, future, compatibilityDate, ssr, nitro, hub, css, runtimeConfig
• Runtime Modules: @nuxthub/[email protected], @nuxt/[email protected], @pinia/[email protected], @nuxt/[email protected], @nuxt/[email protected], @vueuse/[email protected], @sidebase/[email protected]
• 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.

[pkawiak]

I had the same issue when using the baseURL in config... I dug a bit deeper and found out that there's this resolveApiBaseUrl utility function which is taking the envBaseUrl directly from originEnvKey here basically ignoring the baseURL... So what I did is I set the AUTH_ORIGIN env variable to a full URL, like https://stellar-xxx.netlify.app/api/auth and that fixed this particular issue. Seems like a hack though as full URL is definitely not origin...

[etienne-bondot]

I experience the same issue. You can see all test I made in https://github.com/sidebase/nuxt-auth/issues/906#issuecomment-3117779370.

[phoenix-ru]

@pkawiak You are 100% right that originEnvKey is misleading, I want to rename this variable to be baseUrlEnvKey to be in line with what it actually does. However we are 1.0 already, so this change will have to wait till 2.0.

For now the intended way is described here: https://auth.sidebase.io/guide/advanced/url-resolutions