User Management

Guide to managing administrator accounts and access control in PROVESA Web

PROVESA Web uses Better Auth for secure authentication and user management. This guide covers user administration and access control.

Authentication System

PROVESA Web implements a secure authentication system with:

• Email/Password Login: Standard credential-based authentication
• Password Recovery: Email-based password reset flow
• Session Management: Secure session handling with Better Auth
• Route Protection: Admin routes protected by authentication middleware

User Roles

Currently, PROVESA Web supports a single admin role:

Role	Access Level	Description
Administrator	Full Access	Complete control over all admin panel features

Future versions may include additional roles like Editor, Viewer, or Content Manager with granular permissions.

Creating Admin Users

New administrators are created through the database seeding process during initial setup.

Initial Admin Setup

During installation, a default admin account is created:

1. Run Database Migration

   pnpm db:push
   

   This creates the necessary database tables.

2. Run Seed Command

   pnpm db:seed
   

   This creates the default admin user and theme settings.

3. Check Seed Output

   The seed script will output the default admin credentials:

   • Default email: Check the seed file in src/lib/server/db/seed.js
   • Default password: Set during seeding

Security Best Practice: Change the default admin password immediately after first login.

Managing Users

Accessing User Management

A dedicated user management interface is under development. Currently at /admin/users, which shows a placeholder page.

For now, users are managed directly through:

1. Database Tools: Using Drizzle Studio or direct database access
2. Command Line: Using database seeding scripts

Using Drizzle Studio

Drizzle Studio provides a GUI for database management:

1. Open Drizzle Studio

   pnpm db:studio
   

   This launches the database GUI in your browser.

2. Navigate to Users Table

   Find and click the user table in the left sidebar.

3. View or Edit Users

   • View existing user records
   • Edit user details directly
   • Add new user entries

Adding Users

To add a new administrator:

1. Open the user table in Drizzle Studio
2. Click “Add Row” or similar option
3. Enter user details:
   • name: Administrator’s full name
   • email: Login email (must be unique)
   • emailVerified: Set to current timestamp
4. Save the record
5. Set password using Better Auth’s password hashing

Editing Users

To modify existing users:

1. Locate the user in Drizzle Studio
2. Click to edit the row
3. Update fields as needed
4. Save changes

Common edits:

• Update name or email
• Reset password (requires hashing)
• Change verification status

Removing Users

To delete a user:

1. Find the user in the table
2. Select the row
3. Click delete/remove option
4. Confirm deletion

Ensure at least one admin user always exists to prevent lockout.

Password Management

Password Requirements

Better Auth enforces secure password standards:

• Minimum length requirements
• Secure bcrypt hashing
• Protection against common passwords

Changing Your Password

1. Log In to Admin Panel

   Access /admin with your current credentials.

2. Use Password Reset Flow

   Currently, password changes require using the password recovery flow:

   1. Log out of the admin panel
   2. Click “¿Olvidaste tu contraseña?” on login page
   3. Enter your admin email
   4. Check email for reset link
   5. Follow link to set new password

Password Recovery Process

The password recovery system works as follows:

1. Request Password Reset

   Navigate to /recuperar and enter your email address.

2. Receive Email

   A password reset email is sent via Gmail (configured in environment variables):

   • Contains secure reset token
   • Link valid for limited time
   • Sent to registered email address
3. Reset Password

   Click the link in the email to access /restablecer-password:

   • Enter new password
   • Confirm password
   • Submit to update
4. Login with New Password

   Use your new password to access the admin panel.

Email Configuration

Password recovery requires Gmail SMTP configuration.

Setting Up Gmail for Password Reset

1. Enable 2-Factor Authentication

   On your Google account, enable 2FA in security settings.

2. Generate App Password

   Create an app-specific password:

   1. Go to Google App Passwords
   2. Select “Mail” and your device
   3. Generate password
   4. Copy the 16-character password
3. Update Environment Variables

   Add to your .env file:

   GMAIL_USER="[e-mail]"
   GMAIL_APP_PASSWORD="your-16-char-app-password"
   
4. Test Email Sending

   Trigger a password reset to verify email delivery.

Never commit the .env file to version control. Keep credentials secure.

Session Management

How Sessions Work

Better Auth manages user sessions:

• Sessions stored in database
• Secure session tokens in cookies
• Automatic expiration after inactivity
• Protection against CSRF attacks

Session Configuration

Session settings are configured in src/lib/server/auth.js:

export const auth = betterAuth({
  database: db,
  emailAndPassword: {
    enabled: true,
  },
  // Additional Better Auth configuration
});

Logging Out

Users can log out from the admin panel:

1. Click the logout icon in the sidebar user profile
2. Session is terminated server-side
3. Redirected to login page

Security Best Practices

Password Security

• Use strong, unique passwords for each admin
• Change default passwords immediately
• Enable 2FA on Gmail accounts used for recovery
• Rotate passwords periodically (every 90 days)
• Never share admin credentials

Access Control

• Limit number of admin accounts
• Remove inactive user accounts
• Monitor admin activity logs
• Use unique email addresses for each admin
• Restrict admin access to trusted networks when possible

Environment Security

• Keep .env file secure and never commit it
• Use strong BETTER_AUTH_SECRET (32+ characters)
• Rotate secrets periodically
• Use environment-specific configurations
• Enable HTTPS in production

Route Protection

Admin routes are protected by authentication middleware:

Protected Routes

All routes under /admin/* require authentication:

• /admin - Main dashboard
• /admin/users - User management (under development)
• All admin panel sections

Authentication Flow

Layout Server Protection

The file src/routes/admin/+layout.server.js enforces authentication:

export const load = async (event) => {
  const { user } = event.locals;
  
  if (!user) {
    throw redirect(302, '/login');
  }
  
  return { user };
};

Troubleshooting

Common Issues

Can't access admin panel

Symptoms: Redirected to login even after entering credentials

Solutions:

• Clear browser cookies
• Check if user exists in database
• Verify password is correct
• Check Better Auth configuration
• Review server logs for errors

Password reset email not received

Symptoms: No email arrives after requesting password reset

Solutions:

• Check spam/junk folder
• Verify GMAIL_USER and GMAIL_APP_PASSWORD in .env
• Confirm Gmail app password is correct
• Check server logs for email sending errors
• Verify email address is correct in database

Session expires too quickly

Symptoms: Logged out frequently during use

Solutions:

• Check Better Auth session configuration
• Review session timeout settings
• Ensure cookies are enabled in browser
• Check for clock synchronization issues

Future User Management Features

Planned enhancements include:

• User Management UI: Dedicated interface for adding/editing users
• Role-Based Access Control: Multiple permission levels
• Activity Logging: Track admin actions and changes
• Two-Factor Authentication: Additional security layer
• User Invitations: Email-based invite system

Next Steps

Admin Panel Usage

Learn to navigate the admin interface

Deployment

Deploy your site securely to production