Configuring Authentication in Supamode

Supamode uses a two-layer authentication system to control admin access. Users must pass both checks before accessing any admin functionality.

Authentication Layers

Layer 1: JWT Metadata Check

The first layer is a fast, lightweight check that reads the user's JWT token. Users must have supamode_access: true in their app_metadata to pass this check.

This check runs:

• On every API request via Hono middleware
• On database operations via the supamode.check_supamode_access() function

The JWT check filters out unauthorized users before any database queries run, reducing load on your database.

Layer 2: Account and Role Verification

The second layer verifies the user exists in supamode.accounts and has an assigned role with appropriate permissions.

This check validates:

• The account exists and is active (is_active: true)
• A role is assigned to the account
• The role has permissions for the requested operation

Without both layers passing, users see an access denied error.

Adding Admin Users

You have two options for granting admin access:

Option 1: Using the Supamode UI (Recommended)

This is the easiest approach for adding admins after initial setup.

Prerequisites: The user must already have a Supabase Auth account in your application.

Steps:

1. Navigate to the Users Explorer in Supamode
2. Search for the user by email
3. Click on their email to open their profile
4. Click the Make Admin button in the top right

5. Confirm the action in the dialog

6. Assign a role to the new admin (required for any access)

The "Make Admin" action does two things:

• Sets supamode_access: true in the user's JWT app_metadata
• Creates a record in supamode.accounts

Without a role assignment, the user can log in but cannot access any data or features.

Option 2: Using Seed Files

For initial setup or automated deployments, use seed templates to create accounts with roles pre-assigned.

const adminAccount = Account.create({
  app,
  id: 'user-uuid-from-supabase-auth',
});
adminAccount.assignRole(adminRole);

See the RBAC System documentation for complete seed file examples.

Removing Admin Access

To revoke admin access for a user:

1. Navigate to the user's profile in the Users Explorer
2. Click Remove Admin Access

This action:

• Sets supamode_access: false in their JWT
• Marks the account as inactive in supamode.accounts

The user can no longer access Supamode, but their Supabase Auth account remains intact.

Multi-Factor Authentication

MFA adds a second authentication factor (typically a TOTP app like Google Authenticator) beyond the password. We recommend enabling MFA for all admin accounts.

Setting Up MFA for Your Account

1. Navigate to /settings/authentication
2. Click Enable MFA
3. Scan the QR code with your authenticator app
4. Enter the verification code to confirm

Enforcing MFA for All Admins

After enabling MFA on your own account, you can require it for all admin users:

1. Navigate to /settings/authentication
2. Enable Require MFA for all users

If you're using a MakerKit application, MFA flows are already built into your authentication pages.

Captcha Protection

Cloudflare Turnstile captcha prevents automated attacks on login and signup pages.

Configuration

Add these environment variables to your frontend configuration:

VITE_CAPTCHA_SITE_KEY="0x4AAAAAAAB..."

Server-side, you need the CAPTCHA_SECRET_TOKEN environment variable:

CAPTCHA_SECRET_TOKEN="0x4AAAAAAAB..."

To get a Turnstile site key:

1. Go to Cloudflare Dashboard
2. Create a new Turnstile widget
3. Add your domain to allowed hostnames
4. Copy the Site Key

Once configured, captcha automatically appears on:

• Login page
• Signup page
• Password reset page

Security Headers and CSRF Protection

Supamode's Hono API includes security protections by default:

• CORS: Configured via APP_URL environment variable. Only requests from your frontend domain are allowed.
• CSRF Protection: Built into all mutating endpoints. Tokens are automatically managed.
• Secure Headers: Standard security headers (X-Frame-Options, X-Content-Type-Options, etc.) are set on all responses.

No additional configuration is required for these protections.

Troubleshooting

"Access Denied" After Making User Admin

1. Verify the user has a role assigned (not just admin status)
2. Check the role has appropriate permissions
3. Have the user log out and back in to refresh their JWT

MFA Code Not Working

1. Verify time synchronization on the user's device
2. Ensure they're using the correct authenticator account
3. If locked out, an admin with higher rank can disable MFA temporarily

User Can't See Any Tables

This usually means their role lacks data permissions. Check that:

1. The role is assigned to their account
2. The role has data permissions for the required tables
3. The user has refreshed their session after role assignment