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:

typescript

import { 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:

typescript

{
  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:

Option	Type	Default	Description
`secret`	string	`""`	Signing secret (256-bit minimum for production)
`alg`	string	`"HS256"`	Algorithm: HS256, HS384, HS512
`expires`	number	-	Token expiry in seconds
`issuer`	string	-	Token issuer claim (iss)
`fields`	string[]	`["id", "email", "role"]`	User fields in payload

Step 3: Configure Cookie Settings

Auth cookies store JWT tokens for browser sessions:

typescript

{
  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:

Option	Type	Default	Description
`secure`	boolean	`true`	HTTPS-only flag
`httpOnly`	boolean	`true`	Block JS access
`sameSite`	string	`"lax"`	CSRF protection
`expires`	number	`604800`	Expiry in seconds
`renew`	boolean	`true`	Auto-extend expiry
`pathSuccess`	string	`"/"`	Post-login redirect
`pathLoggedOut`	string	`"/"`	Post-logout redirect

Step 4: Configure Password Strategy

Set up password hashing and requirements:

typescript

{
  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:

Option	Security	Performance	Use Case
`plain`	None	Fastest	Development only, never production
`sha256`	Good	Fast	Default, suitable for most cases
`bcrypt`	Best	Slower	Recommended for production

Step 5: Define Roles

Configure roles for authorization:

typescript

{
  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:

typescript

{
  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:

typescript

import { 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:

Method	Path	Description
POST	`/api/auth/password/login`	Login with email/password
POST	`/api/auth/password/register`	Register new user
GET	`/api/auth/me`	Get current user
POST	`/api/auth/logout`	Log out (clear cookie)
GET	`/api/auth/strategies`	List enabled strategies

Environment Variables

Recommended env vars for auth:

bash

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

Generate a secure secret:

bash

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

Development vs Production

Setting	Development	Production
`jwt.secret`	Can use placeholder	Required, strong secret
`cookie.secure`	`false`	`true` (HTTPS only)
`strategies.password.config.hashing`	`sha256`	`bcrypt`
`allow_register`	`true`	Consider `false` for closed systems

Dev config shortcut:

typescript

const 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:

typescript

{
  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:

typescript

{
  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:

typescript

{
  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:

typescript

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

Weak Password Hashing

Problem: Using

plain

sha256

in production

Fix: Use bcrypt for production:

typescript

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

Verification

After setup, verify auth works:

1. Check enabled strategies:

bash

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

2. Register a test user:

bash

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

3. Login:

bash

curl -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):

bash

curl 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

bknd-setup-auth

NPX Install

Tags

SKILL.md Content

Setup Authentication

Prerequisites

When to Use UI Mode

When to Use Code Mode

Code Approach

Step 1: Enable Auth with Minimal Config

Step 2: Configure JWT Settings

Step 3: Configure Cookie Settings

Step 4: Configure Password Strategy

Step 5: Define Roles

Step 6: Configure Registration

Full Production Example

Auth Endpoints

Environment Variables

Development vs Production

Common Pitfalls

Missing JWT Secret in Production

Cookie Not Set (HTTPS Issues)

Role Not Found

Registration Disabled

Weak Password Hashing

Verification

Security Checklist

DOs and DON'Ts

Related Skills