---

name: bknd-setup-auth description: Use when initializing or configuring the Bknd authentication system. Covers enabling auth, configuring password strategy, setting up JWT and cookie options, defining roles, and production security settings.

Setup Authentication

Initialize and configure the Bknd authentication system with strategies, JWT, cookies, and roles.

Prerequisites

• Bknd project initialized
• Code-first configuration (auth config is code-only)
• For OAuth: provider credentials (client ID, client secret)

When to Use UI Mode

• Viewing current auth configuration
• Toggling strategies on/off
• Testing auth endpoints via admin panel

UI steps: Admin Panel > Auth > Settings

Note: Full auth configuration requires code mode. UI only shows/toggles existing settings.

When to Use Code Mode

• Initial authentication setup
• Configuring JWT secrets and expiry
• Setting up password hashing
• Defining roles and permissions
• Production security hardening

Code Approach

Step 1: Enable Auth with Minimal Config

Start with basic password authentication:

Copyimport { serve } from "bknd/adapter/bun";
import { em, entity, text } from "bknd";

const schema = em({
  posts: entity("posts", { title: text().required() }),
});

serve({
  connection: { url: "file:data.db" },
  config: {
    data: schema.toJSON(),
    auth: {
      enabled: true,
    },
  },
});

This enables:

• Password strategy (default)
• Auto-created users entity
• JWT-based sessions
• /api/auth/* endpoints

Step 2: Configure JWT Settings

JWT tokens authenticate API requests. Configure for security:

Copy{
  auth: {
    enabled: true,
    jwt: {
      secret: process.env.JWT_SECRET,  // Required in production
      alg: "HS256",                     // Algorithm: HS256, HS384, HS512
      expires: 604800,                  // Expiry in seconds (7 days)
      issuer: "my-app",                 // Optional issuer claim
      fields: ["id", "email", "role"],  // Fields included in token
    },
  },
}

JWT options:

Step 3: Configure Cookie Settings

Auth cookies store JWT tokens for browser sessions:

Copy{
  auth: {
    enabled: true,
    jwt: { secret: process.env.JWT_SECRET },
    cookie: {
      secure: true,           // HTTPS only (set false for local dev)
      httpOnly: true,         // Block JavaScript access
      sameSite: "lax",        // CSRF protection: "strict" | "lax" | "none"
      expires: 604800,        // Cookie expiry in seconds (7 days)
      path: "/",              // Cookie path scope
      renew: true,            // Auto-extend on requests
      pathSuccess: "/",       // Redirect after login
      pathLoggedOut: "/",     // Redirect after logout
    },
  },
}

Cookie options:

Step 4: Configure Password Strategy

Set up password hashing and requirements:

Copy{
  auth: {
    enabled: true,
    jwt: { secret: process.env.JWT_SECRET },
    strategies: {
      password: {
        type: "password",
        enabled: true,
        config: {
          hashing: "bcrypt",   // "plain" | "sha256" | "bcrypt"
          rounds: 4,           // bcrypt rounds (1-10)
          minLength: 8,        // Minimum password length
        },
      },
    },
  },
}

Hashing options:

Step 5: Define Roles

Configure roles for authorization:

Copy{
  auth: {
    enabled: true,
    jwt: { secret: process.env.JWT_SECRET },
    roles: {
      admin: {
        implicit_allow: true,  // Can do everything
      },
      editor: {
        implicit_allow: false,
        permissions: [
          { permission: "data.posts.read", effect: "allow" },
          { permission: "data.posts.create", effect: "allow" },
          { permission: "data.posts.update", effect: "allow" },
        ],
      },
      user: {
        implicit_allow: false,
        is_default: true,  // Default role for new registrations
        permissions: [
          { permission: "data.posts.read", effect: "allow" },
        ],
      },
    },
    default_role_register: "user",  // Role assigned on registration
  },
}

Step 6: Configure Registration

Control user self-registration:

Copy{
  auth: {
    enabled: true,
    allow_register: true,           // Enable/disable registration
    default_role_register: "user",  // Role for new users
    entity_name: "users",           // User entity name (default: "users")
    basepath: "/api/auth",          // Auth API base path
  },
}

Full Production Example

Complete auth setup with security best practices:

Copyimport { serve, type BunBkndConfig } from "bknd/adapter/bun";
import { em, entity, text, date } from "bknd";

const schema = em({
  users: entity("users", {
    email: text().required().unique(),
    name: text(),
    avatar: text(),
    created_at: date({ default_value: "now" }),
  }),
  posts: entity("posts", {
    title: text().required(),
    content: text(),
  }),
});

type Database = (typeof schema)["DB"];
declare module "bknd" {
  interface DB extends Database {}
}

const config: BunBkndConfig = {
  connection: { url: process.env.DB_URL || "file:data.db" },
  config: {
    data: schema.toJSON(),
    auth: {
      enabled: true,
      basepath: "/api/auth",
      entity_name: "users",
      allow_register: true,
      default_role_register: "user",

      // JWT configuration
      jwt: {
        secret: process.env.JWT_SECRET!,
        alg: "HS256",
        expires: 604800,  // 7 days
        issuer: "my-app",
        fields: ["id", "email", "role"],
      },

      // Cookie configuration
      cookie: {
        secure: process.env.NODE_ENV === "production",
        httpOnly: true,
        sameSite: "lax",
        expires: 604800,
        renew: true,
        pathSuccess: "/dashboard",
        pathLoggedOut: "/login",
      },

      // Password strategy
      strategies: {
        password: {
          type: "password",
          enabled: true,
          config: {
            hashing: "bcrypt",
            rounds: 4,
            minLength: 8,
          },
        },
      },

      // Roles
      roles: {
        admin: {
          implicit_allow: true,
        },
        editor: {
          implicit_allow: false,
          permissions: [
            { permission: "data.posts.read", effect: "allow" },
            { permission: "data.posts.create", effect: "allow" },
            { permission: "data.posts.update", effect: "allow" },
            { permission: "data.posts.delete", effect: "allow" },
          ],
        },
        user: {
          implicit_allow: false,
          is_default: true,
          permissions: [
            { permission: "data.posts.read", effect: "allow" },
          ],
        },
      },
    },
  },
  options: {
    seed: async (ctx) => {
      // Create initial admin on first run
      const adminExists = await ctx.em.repo("users").findOne({
        where: { email: { $eq: "admin@example.com" } },
      });

      if (!adminExists) {
        await ctx.app.module.auth.createUser({
          email: "admin@example.com",
          password: process.env.ADMIN_PASSWORD || "changeme123",
          role: "admin",
        });
        console.log("Admin user created");
      }
    },
  },
};

serve(config);

Auth Endpoints

After setup, these endpoints are available:

Environment Variables

Recommended env vars for auth:

Copy# .env
JWT_SECRET=your-256-bit-secret-minimum-32-characters-long
ADMIN_PASSWORD=secure-initial-admin-password

Generate a secure secret:

Copy# Generate 64-character random string
openssl rand -hex 32

Development vs Production

Dev config shortcut:

Copyconst isDev = process.env.NODE_ENV !== "production";

{
  auth: {
    enabled: true,
    jwt: {
      secret: isDev ? "dev-secret-not-for-production" : process.env.JWT_SECRET!,
      expires: isDev ? 86400 * 30 : 604800,  // 30 days dev, 7 days prod
    },
    cookie: {
      secure: !isDev,
    },
    strategies: {
      password: {
        type: "password",
        config: {
          hashing: isDev ? "sha256" : "bcrypt",
        },
      },
    },
  },
}

Common Pitfalls

Missing JWT Secret in Production

Problem: Cannot sign JWT without secret error

Fix: Set JWT secret via environment variable:

Copy{
  auth: {
    jwt: {
      secret: process.env.JWT_SECRET,  // Never hardcode in production
    },
  },
}

Cookie Not Set (HTTPS Issues)

Problem: Auth cookie not set in browser

Fix: Set secure: false for local development:

Copy{
  auth: {
    cookie: {
      secure: process.env.NODE_ENV === "production",  // false for localhost
    },
  },
}

Role Not Found

Problem: Role "admin" not found when creating users

Fix: Define roles before referencing them:

Copy{
  auth: {
    roles: {
      admin: { implicit_allow: true },  // Define first
      user: { implicit_allow: false },
    },
    default_role_register: "user",  // Now can reference
  },
}

Registration Disabled

Problem: Registration not allowed error

Fix: Enable registration:

Copy{
  auth: {
    allow_register: true,  // Default is true, but check if explicitly disabled
  },
}

Weak Password Hashing

Problem: Using plain or sha256 in production

Fix: Use bcrypt for production:

Copy{
  auth: {
    strategies: {
      password: {
        config: {
          hashing: "bcrypt",
          rounds: 4,  // Balance security and performance
        },
      },
    },
  },
}

Verification

After setup, verify auth works:

1. Check enabled strategies:

Copycurl http://localhost:7654/api/auth/strategies

2. Register a test user:

Copycurl -X POST http://localhost:7654/api/auth/password/register \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "password123"}'

3. Login:

Copycurl -X POST http://localhost:7654/api/auth/password/login \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "password123"}'

4. Check current user (with token):

Copycurl http://localhost:7654/api/auth/me \
  -H "Authorization: Bearer <token-from-login>"

Security Checklist

Before deploying to production:

• Set strong jwt.secret (256-bit minimum)
• Use hashing: "bcrypt" for password strategy
• Set cookie.secure: true (HTTPS only)
• Set cookie.httpOnly: true (default)
• Set cookie.sameSite: "lax" or "strict"
• Configure jwt.expires (don't leave unlimited)
• Review allow_register setting
• Create admin user via seed (not via public registration)
• Store secrets in environment variables

DOs and DON'Ts

DO:

• Use environment variables for secrets
• Use bcrypt hashing in production
• Set JWT expiry times
• Define roles before assigning them
• Test auth flow after configuration changes

DON'T:

• Hardcode JWT secrets in code
• Use plain hashing in production
• Skip setting cookie.secure in production
• Leave registration open if not needed
• Forget to create initial admin user

Related Skills

• bknd-create-user - Create user accounts programmatically
• bknd-login-flow - Implement login/logout functionality
• bknd-registration - Set up user registration flows
• bknd-oauth-setup - Configure OAuth providers (Google, GitHub)
• bknd-create-role - Define roles for authorization
• bknd-session-handling - Manage user sessions