Advanced

Custom Configuration

Advanced customization of Nuxt Umbu module options

Learn how to customize Nuxt Umbu configuration for specific requirements, including custom endpoints, multiple strategies, and advanced provider settings.

Overview

Nuxt Umbu provides extensive configuration options through the auth key in your nuxt.config.ts. This allows you to tailor the authentication system to your specific needs.

Module Configuration Structure

The main configuration object varies based on your provider:

Sanctum Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  auth: {
    provider: 'sanctum',
    csrf: '/sanctum/csrf-cookie',
    cookie: {
      prefix: 'auth.',
      options: {
        httpOnly: false,
        secure: false,
        sameSite: 'Lax',
        priority: 'high'
      }
    },
    strategies: {
      default: {
        endpoints: {
          login: { url: '/login', method: 'post' },
          user: { url: '/api/user', method: 'get', property: 'data' },
          logout: { url: '/logout', method: 'post' }
        },
        redirect: {
          login: '/login',
          logout: '/',
          home: '/dashboard'
        }
      }
    }
  }
})

Passport Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  auth: {
    provider: 'passport',
    cookie: {
      prefix: 'auth.',
      options: {
        httpOnly: false,
        secure: false,
        sameSite: 'Lax',
        priority: 'high'
      }
    },
    strategies: {
      password: {
        endpoints: {
          login: {
            url: '/oauth/token',
            method: 'post',
            alias: 'token'
          },
          user: {
            url: '/api/user',
            method: 'get',
            property: 'data'
          },
          refresh: {
            url: '/oauth/token',
            method: 'post',
            alias: 'refresh-token'
          },
          logout: { alias: 'logout' }
        },
        redirect: {
          login: '/login',
          logout: '/',
          home: '/dashboard'
        }
      }
    }
  },
  runtimeConfig: {
    secret: {
      password: {
        client_id: process.env.NUXT_AUTH_PASSWORD_CLIENT_ID,
        client_secret: process.env.NUXT_AUTH_PASSWORD_CLIENT_SECRET,
        grant_type: 'password'
      }
    }
  }
})

Multiple Strategies

You can configure multiple authentication strategies for different use cases:

strategies: {
  password: {
    endpoints: {
      login: { url: '/oauth/token', method: 'post' },
      user: { url: '/api/user', method: 'get' }
    },
    redirect: {
      login: '/login',
      logout: '/',
      home: '/dashboard'
    }
  },
  social: {
    endpoints: {
      login: { url: '/oauth/social', method: 'post' },
      user: { url: '/api/social/user', method: 'get' }
    },
    redirect: {
      login: '/auth/social',
      logout: '/',
      home: '/dashboard'
    }
  }
}

Using Different Strategies

// Login with password strategy
await $auth.loginWith('password', { 
  username: 'user@example.com', 
  password: 'secret' 
})

// Login with social strategy
await $auth.loginWith('social', { 
  provider: 'google',
  token: 'oauth_token' 
})

Custom Endpoints

Endpoint Aliases

For Passport provider, you can use aliases to create cleaner API routes:

endpoints: {
  login: {
    url: '/oauth/token',
    method: 'post',
    alias: 'token'  // Creates /api/token route
  },
  refresh: {
    url: '/oauth/token',
    method: 'post',
    alias: 'refresh-token'  // Creates /api/refresh-token route
  }
}

Custom User Property

Specify where user data is located in the response:

endpoints: {
  user: {
    url: '/api/user',
    method: 'get',
    property: 'data.user'  // Nested property path
  }
}

Two-Factor Authentication Endpoint

Configure 2FA endpoint for enhanced security:

endpoints: {
  twoFactor: {
    url: '/api/2fa/verify',
    method: 'post',
    property: 'access_token',
    expires: 'expires_in',
    headerName: 'X-2FA-Token'
  }
}

Redirect Configuration

Customize redirect behavior for authentication events:

redirect: {
  login: '/login',           // Where to redirect when not authenticated
  logout: '/',               // Where to redirect after logout
  home: '/dashboard',        // Where to redirect after successful login
  twoFactor: '/2fa',         // Where to redirect for 2FA
  callback: '/auth/callback' // OAuth callback URL
}

CSRF Configuration

Sanctum CSRF

auth: {
  provider: 'sanctum',
  csrf: '/sanctum/csrf-cookie'  // CSRF cookie endpoint
}

Passport CSRF (Optional)

auth: {
  provider: 'passport',
  csrf: '/api/csrf-token'  // Optional CSRF endpoint
}

Environment-Specific Configuration

Use environment variables for different configurations:

// nuxt.config.ts
export default defineNuxtConfig({
  auth: {
    provider: process.env.AUTH_PROVIDER || 'sanctum',
    cookie: {
      prefix: process.env.NODE_ENV === 'production' ? '__Secure-' : 'auth.',
      options: {
        secure: process.env.NODE_ENV === 'production',
        httpOnly: process.env.NODE_ENV === 'production',
        sameSite: process.env.NODE_ENV === 'production' ? 'Strict' : 'Lax'
      }
    }
  }
})

Validation

The module validates your configuration automatically:

Passport Secret Validation

For Passport provider, the module validates that:

runtimeConfig.secret exists and is properly structured
Each secret has client_id, client_secret, and grant_type
Each secret in runtimeConfig.secret has a corresponding strategy

Strategy Validation

The module ensures:

All strategies have required endpoints
Endpoints have valid url and method properties
Redirect options are properly configured

Common Patterns

API-First Configuration

strategies: {
  api: {
    endpoints: {
      login: { url: '/api/v1/auth/login', method: 'post' },
      user: { url: '/api/v1/user', method: 'get' },
      logout: { url: '/api/v1/auth/logout', method: 'post' }
    },
    redirect: {
      login: '/auth/login',
      logout: '/',
      home: '/app'
    }
  }
}

Multi-Tenant Configuration

strategies: {
  tenant1: {
    endpoints: {
      login: { url: '/tenant1/auth/login', method: 'post' },
      user: { url: '/tenant1/user', method: 'get' }
    },
    redirect: { login: '/tenant1/login', logout: '/', home: '/tenant1' }
  },
  tenant2: {
    endpoints: {
      login: { url: '/tenant2/auth/login', method: 'post' },
      user: { url: '/tenant2/user', method: 'get' }
    },
    redirect: { login: '/tenant2/login', logout: '/', home: '/tenant2' }
  }
}

Troubleshooting

Configuration Not Applied

Ensure configuration is in nuxt.config.ts under the auth key
Restart the Nuxt dev server after configuration changes
Check for typos in configuration keys

Strategy Not Found

Verify strategy name matches between strategies and loginWith() calls
Check that runtimeConfig.secret has corresponding entries for Passport

Redirects Not Working

Ensure redirect URLs are valid paths in your application
Check that middleware is properly configured on protected routes

Best Practices

Use environment variables for sensitive configuration
Keep development and production configurations separate
Use meaningful strategy names for clarity
Document custom endpoint configurations
Test redirects in different authentication scenarios
Validate configuration changes in development before production

Advanced

Advanced configuration and customization options for Nuxt Umbu

Cookie Configuration

Advanced cookie settings and security configuration