Authorization (RBAC)

This module includes a simple yet powerful Role-Based Access Control (RBAC) system to control access to your application's pages and API routes.

🚨 Critical: Permissions Required

By default, NO users (including admins) can access any protected routes until you configure permissions. If you're experiencing redirect loops or users being sent back to login after authentication, this is likely the cause.

Quick fix for admin access:

// nuxt.config.ts
nuxtUsers: {
  auth: {
    permissions: {
      admin: ['*'] // Gives admin access to everything
    }
  }
}

Overview

The authorization system follows a whitelist approach - by default, no routes are accessible unless explicitly configured. This ensures security by default, but requires explicit permission configuration for any protected access.

How Authorization Works

The authorization logic follows these rules in order:

1. Whitelist Paths: These paths are defined in your nuxt.config.ts (nuxtUsers.auth.whitelist) and are always accessible to any user, authenticated or not. They do not require any specific permissions.
2. Protected Paths: Any path that is not in the whitelist requires authentication. Additionally, you can protect routes based on user roles using the permissions configuration.

This means that routes like /login or /register (if whitelisted) are accessible to everyone, bypassing the permission system entirely.

Role-Based Access Control

You can restrict access to certain routes based on the user's role. The user's role is stored in the role column of the users table.

Configuration

You can define permissions in your nuxt.config.ts file under the nuxtUsers.auth.permissions option. The permissions object maps roles to an array of allowed rules.

A rule can be a simple string for a path (which allows all methods) or an object to specify allowed HTTP methods for a path.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-users'],
  nuxtUsers: {
    // ... other options
    auth: {
      whitelist: ['/register', '/public'],
      permissions: {
        admin: ['*'], // Admin can access everything
        user: ['/profile', '/settings', '/api/nuxt-users/me'],
        manager: [
          // Manager can only GET and PATCH users, but not DELETE them
          { path: '/api/nuxt-users/*', methods: ['GET', 'PATCH'] },
          '/manager-dashboard' // They can access their dashboard normally
        ]
      }
    }
  }
})

Permission Patterns

The system supports various patterns for flexible route protection:

Method-Based Permissions (Recommended)

For fine-grained control over API endpoints, use the object format. This is the most secure way to grant permissions.

permissions: {
  manager: [
    { path: '/api/users/*', methods: ['GET', 'PATCH'] },
    { path: '/api/posts', methods: ['POST'] }
  ],
  viewer: [
    { path: '/api/posts/*', methods: ['GET'] }
  ]
}

NOTE

Requests using safe, non-modifying methods like OPTIONS and HEAD are always allowed and bypass permission checks.

Exact Paths

permissions: {
      user: ['/profile', '/settings']
}

Wildcard Patterns

permissions: {
  admin: ['*'],                    // Access to everything
  moderator: ['/admin/*'],         // Access to all admin sub-routes
  editor: ['/content/*', '/api/content/*']  // Access to content routes
}

Complex Wildcards

permissions: {
  api_user: ['/api/*/profile'],    // Example pattern
  manager: ['/admin/*/users/*']    // Access to user management under admin
}

Configuration Examples

Basic Setup

nuxtUsers: {
  auth: {
    whitelist: ['/register', '/about'],
    permissions: {
      admin: ['*'],
      user: ['/profile', '/dashboard'],
      guest: [] // No permissions - can only access whitelisted routes
    }
  }
}

E-commerce Application

nuxtUsers: {
  auth: {
    whitelist: ['/register', '/products', '/categories'],
    permissions: {
      admin: ['*'],
      manager: ['/admin/*', '/api/admin/*', '/reports/*'],
      customer: ['/profile', '/orders', '/api/nuxt-users/*'],
      vendor: ['/vendor/*', '/api/vendor/*', '/products/manage']
    }
  }
}

Content Management System

nuxtUsers: {
  auth: {
    whitelist: ['/register', '/public/*'],
    permissions: {
      super_admin: ['*'],
      admin: ['/admin/*', '/api/admin/*'],
      editor: ['/editor/*', '/api/editor/*', '/content/*'],
      author: ['/author/*', '/api/author/*', '/content/create'],
      reviewer: ['/review/*', '/api/review/*']
    }
  }
}

Security Features

Whitelist Approach

• Default Deny: By default, permissions is an empty object {}, meaning no routes are accessible
• Explicit Allow: You must explicitly define permissions to grant access
• Secure by Default: New routes are automatically protected until explicitly permitted

Wildcard Support

• * - Matches any path (full access)
• /* - Matches all sub-paths under a base path
• ** - Matches any number of path segments
• Complex patterns like /api/*/users/* for flexible matching

Role Hierarchy

You can implement role hierarchies by giving higher-level roles access to lower-level paths:

permissions: {
  super_admin: ['*'],           // Access to everything
  admin: ['/admin/*', '/api/admin/*'],  // Access to admin areas
  manager: ['/manage/*', '/api/manage/*'], // Access to management
  user: ['/profile', '/dashboard']      // Basic user access
}

Creating Users with Roles

You can create users with specific roles using the CLI:

# Create a standard user
npx nuxt-users create-user -e [email protected] -n "John Doe" -p password123 -r user

# Create an admin user
npx nuxt-users create-user -e [email protected] -n "Admin User" -p adminpass123 -r admin

# Create an editor user
npx nuxt-users create-user -e [email protected] -n "Editor User" -p editorpass123 -r editor

# Create a moderator user
npx nuxt-users create-user -e [email protected] -n "Moderator User" -p modpass123 -r moderator

The default role is user if not specified. Role values should match keys in auth.permissions unless auth.allowCustomRoles is true (or permissions are not configured yet).

Best Practices

1. Start with Whitelist: Begin by whitelisting public routes that don't need authentication
2. Use Specific Permissions: Avoid using * for regular users - be specific about what they can access
3. Test Permissions: Always test your permission configuration with different user roles
4. Document Roles: Keep a clear documentation of what each role can access
5. Regular Review: Periodically review and update permissions as your application evolves

Troubleshooting

Common Issues

🔄 Authenticated users redirected to login (Redirect Loop):

This is the most common issue - your authenticated users (including admins) are being redirected back to login when trying to access any page.

Cause: No permissions are configured. By default, permissions: {} means no one can access anything.

Solution:

// nuxt.config.ts
nuxtUsers: {
  auth: {
    permissions: {
      admin: ['*'], // Admin can access everything
      user: ['/profile', '/api/nuxt-users/me'] // Basic user access
    }
  }
}

Debug: Check browser console for messages like:

[Nuxt Users] client.middleware.auth.global: User with role admin denied access to /profile

User can't access a route they should have access to:

• Check if the route is in the whitelist (whitelisted routes bypass permissions)
• Verify the user's role matches the permissions configuration
• Ensure the path pattern matches exactly (including leading/trailing slashes)

All users are being redirected to login:

• Check if permissions is configured (empty permissions deny all access)
• Verify that at least one role has the necessary permissions
• Ensure the user's role exists in the permissions configuration

Wildcards not working as expected:

• Use /* for sub-path matching (e.g., /admin/* matches /admin/users)
• Use * for full access (e.g., admin: ['*'])
• Test complex patterns with the actual paths you're trying to protect

Programmatic Access Control

For programmatic access control using the usePublicPaths composable, refer to the Composables documentation.