Authentication
Our authentication system is built on Next.js App Router with Auth.js (formerly NextAuth), providing a comprehensive solution for user authentication including OAuth providers, email/password login, two-factor authentication, email verification, and password reset functionality. It's designed with multi-tenant architecture in mind, ensuring secure user isolation across different schools and organizations.
Core Features
Our authentication module delivers enterprise-grade security with a developer-friendly experience:
- Multi-Provider Authentication – Support for Credentials, Google, and Facebook OAuth providers with seamless integration
- JWT-Based Sessions – Secure session management with automatic token refresh and validation
- Role-Based Access Control – Granular permissions with roles including DEVELOPER, ADMIN, TEACHER, STUDENT, GUARDIAN, and more
- Two-Factor Authentication – Enhanced security with 2FA support for sensitive operations
- Email Verification Flow – Complete email verification system with token-based confirmation
- Password Reset Functionality – Secure password recovery with time-limited tokens
- Multi-Tenant Support – School isolation ensuring users can only access their designated organization
- Elegant Route Protection – Smart middleware that automatically handles public and protected routes
Architecture Overview
Our authentication system follows a layered architecture that prioritizes security, scalability, and developer experience:
Core Authentication Files
The foundation of our authentication system consists of several key files that work together to provide a robust authentication experience:
src/auth.ts
– Main Auth.js configuration with callbacks and session managementsrc/auth.config.ts
– Provider configurations for Google, Facebook, and Credentialssrc/middleware.ts
– Auth-based route protection with intelligent public route handlingsrc/routes.ts
– Route definitions for authentication and public access patternssrc/next-auth.d.ts
– TypeScript declarations for extended user types and session data
Component Architecture
Our authentication components are organized for maximum reusability and maintainability:
Core Components (src/components/auth/
)
user.ts
– User database queries with multi-tenant supportuser-info.tsx
– User information display componentuser-button.tsx
– User dropdown/menu button with role-based optionssocial.tsx
– OAuth provider login buttons with consistent stylinglogout-button.tsx
– Secure logout functionality with session cleanuplogin-button.tsx
– Login trigger button with provider selectionrole-gate.tsx
– Role-based access control component for UI protectioncard-wrapper.tsx
– Authentication form wrapper with consistent stylingheader.tsx
– Authentication form headers with branding supportback-button.tsx
– Navigation back button for form flowsform-error.tsx
– Error message display with user-friendly formattingform-success.tsx
– Success message display for positive feedbackvalidation.ts
– Zod schemas for comprehensive form validationtokens.ts
– Token generation and management utilitiesmail.ts
– Email sending functionality with template supportauth.ts
– Auth utility functions for common operationsaccount.ts
– Account management utilitiesadmin-action.ts
– Admin-specific actions and permissionsuse-current-user.ts
– Hook for current user data with cachinguse-current-role.ts
– Hook for current user role with real-time updates
Feature-Specific Directories
login/
– Complete login form and server actionsjoin/
– User registration form and validation actionsreset/
– Password reset request components and flowspassword/
– Password management and reset functionalityverification/
– Email verification and 2FA componentserror/
– Comprehensive error handling componentssetting/
– User settings and profile management
Multi-Tenant Architecture
Our authentication system is built with multi-tenancy as a first-class concern, ensuring secure isolation between different organizations:
User Model Features
- School Isolation – Users are associated with specific schools via
schoolId
field - Compound Unique Constraint – Same email can exist across different schools securely
- Role-Based Access – Comprehensive role system including DEVELOPER, ADMIN, TEACHER, STUDENT, GUARDIAN, ACCOUNTANT, STAFF, USER
- OAuth Integration – Google and Facebook integration with automatic email verification
Database Queries
Our database layer is optimized for multi-tenant operations:
getUserByEmail()
usesfindFirst()
to handle multi-tenant email uniquenessgetUserById()
provides secure user lookups by ID with school isolation- Account linking for OAuth providers with tenant-aware associations
Route Protection Strategy
Our middleware implements an intelligent route protection system that balances security with accessibility:
Public Routes
The system automatically handles public documentation routes:
// All /docs routes are automatically public
pathname.startsWith("/docs/")
This elegant solution ensures all documentation routes are public by default without requiring manual configuration updates when adding new docs pages.
Protected Routes
- Platform routes (
/dashboard
,/project
,/task
, etc.) require authentication - Role-based access control through
RoleGate
component - Automatic redirect to login with callback URL preservation for seamless UX
Environment Configuration
Our authentication system requires specific environment variables for full functionality:
# Core Authentication
AUTH_SECRET=your_auth_secret
# OAuth Providers
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
FACEBOOK_CLIENT_ID=your_facebook_client_id
FACEBOOK_CLIENT_SECRET=your_facebook_client_secret
# Email Services
RESEND_API_KEY=your_resend_api_key
# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
Usage Patterns
Protected Route Implementation
Use the auth()
function from your route handlers to protect server-side routes:
import { auth } from "@/auth";
export default async function ProtectedPage() {
const session = await auth();
if (!session) {
// Handle unauthorized access
redirect("/login");
}
return <div>Protected Content</div>;
}
Client Component Integration
Use our provided hooks for seamless client-side authentication:
"use client";
import { useCurrentUser } from "@/components/auth/use-current-user";
export default function UserComponent() {
const user = useCurrentUser();
return <div>Hello, {user?.name}</div>;
}
Role-Based Access Control
Implement granular permissions using the RoleGate
component:
import { RoleGate } from "@/components/auth/role-gate";
import { UserRole } from "@prisma/client";
<RoleGate allowedRole={UserRole.ADMIN}>
<AdminPanel />
</RoleGate>
Deployment Considerations
Vercel Deployment
When deploying to Vercel, ensure proper configuration:
-
Environment Variables:
- Set
NEXTAUTH_URL
to your production URL (https://yourdomain.com
) - Configure all OAuth provider credentials in Vercel environment settings
- Add
NODE_ENV=production
to environment variables
- Set
-
Facebook OAuth Configuration:
- Callback URL must exactly match:
https://yourdomain.com/api/auth/callback/facebook
- App must be in "Live" mode, not "Development Mode"
- "Facebook Login" product must be added with proper permissions
- Callback URL must exactly match:
-
Build Configuration:
- Use the provided
next.config.js
with proper Prisma configuration - Ensure
vercel-build.js
is correctly set up to generate Prisma client - Verify your
schema.prisma
hasbinaryTargets = ["native", "rhel-openssl-3.0.x"]
- Use the provided
Extending the Module
To extend this authentication module for your specific needs:
- Add New Providers – Update
auth.config.ts
to include additional OAuth providers - Custom Logic – Modify
auth.ts
callbacks for custom authentication flows - New Components – Add components in
src/components/auth/
following established patterns - Database Schema – Extend the database schema for additional user fields
- Route Protection – Update middleware for new route protection patterns
Troubleshooting
Common issues and their solutions:
- Environment Variables – Ensure all required variables are properly set
- OAuth Callbacks – Verify callback URLs in provider consoles match your application
- Facebook OAuth – Check app domain and callback URLs are configured correctly
- Debug Endpoints – Use
/api/auth/debug/facebook
for Facebook OAuth debugging - Server Logs – Review Vercel dashboard logs for detailed error information
This authentication system provides a solid foundation for building secure, scalable applications with enterprise-grade user management capabilities.