Koa Passport Authentication Middleware

Common errors

• TypeError: ctx.isAuthenticated is not a function

  cause The `passport.initialize()` or `passport.session()` middleware has not been applied to the Koa application, or they are not in the correct order.
  fix Ensure `app.use(passport.initialize())` and `app.use(passport.session())` are called on your Koa app after session middleware and before any routes that use Passport's context methods.

• Error: Session is not configured!

  cause Passport's session management (`passport.session()`) requires a Koa session middleware (e.g., `koa-session`) to be set up and active.
  fix Install and configure `koa-session` (or a similar session middleware) by calling `app.use(session({}, app))` before `app.use(passport.session())`. Remember to set `app.keys` for session signing.

• Error: Unknown authentication strategy "local"

  cause The authentication strategy (e.g., `passport-local`, `passport-google-oauth2`) has not been properly defined and registered with Passport.
  fix Ensure you have imported the necessary Passport strategy (e.g., `require('passport-local').Strategy`) and called `passport.use(new LocalStrategy(...))` before `passport.initialize()`.

Warnings

• breaking `koa-passport` major versions are tightly coupled with `passport` and `koa` major versions. Upgrading one without the others can lead to incompatibility issues.
  Fix: Always check the compatibility table in the `koa-passport` README when upgrading. For version 6.x, ensure `passport` is 5.x or 6.x and `koa` is 2.x.
• breaking The `logout` function's signature changed in `koa-passport` 6.0.0 from a callback-based `(options, callback) => void` to a Promise-based `(options) => Promise<void>`.
  Fix: Update `ctx.logout()` calls to await the returned promise and remove any callback arguments.
• breaking In `koa-passport` v3.0.0, `ctx.passport` was removed, and state variables like `_passport` and `user` were moved to `ctx.state`. Passport no longer monkey patches `http.IncomingMessage` directly.
  Fix: Update code accessing `ctx.passport` to use `ctx.state` instead for user and passport-related state. Review custom authentication callbacks as their arguments also changed.
• gotcha `koa-passport` relies on external session middleware (like `koa-session`) and typically a body parser (like `koa-bodyparser`) to function correctly, especially for session-based authentication and handling login form submissions.
  Fix: Ensure `koa-session` and `koa-bodyparser` (or equivalent middleware) are properly configured and `app.use()`'d *before* `passport.initialize()` and `passport.session()`.

Install

• npm install koa-passport npm
• yarn add koa-passport yarn
• pnpm add koa-passport pnpm

Imports

• passport
  wrong:

  import passport from 'koa-passport';

  correct:

  const passport = require('koa-passport');

  The official documentation and examples for koa-passport@6.x primarily use CommonJS `require`. While modern Koa often uses ESM, ensure your project setup supports CommonJS for this package, or use a tool like `ts-node/register` if mixing.
• Passport
  wrong:

  import Passport from 'passport';
  import { Strategy as LocalStrategy } from 'passport-local';

  correct:

  const Passport = require('passport');
  const LocalStrategy = require('passport-local').Strategy;

  You typically need to import the core `passport` library separately to configure strategies (e.g., `passport-local`, `passport-google-oauth2`). Stick to CommonJS `require` for consistency with `koa-passport` unless your environment is fully configured for ESM interoperability.
• Koa
  wrong:

  import Koa from 'koa';

  correct:

  const Koa = require('koa');

  While Koa itself supports both CJS and ESM, the `koa-passport` examples provided use CommonJS `require`. For seamless integration, using `require` for Koa might be necessary depending on your module resolution settings if not transpiling.

Quickstart

This example sets up a basic Koa application with `koa-passport` using a local authentication strategy. It demonstrates session management, body parsing, user serialization/deserialization, and defines routes for login, logout, and a protected profile page. It also includes a basic HTML login form.

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const session = require('koa-session');
const passport = require('koa-passport');
const LocalStrategy = require('passport-local').Strategy;

const app = new Koa();

// Session Configuration
app.keys = ['your-secret-key']; // Replace with a strong, random key in production
app.use(session({}, app));

// Body Parser
app.use(bodyParser());

// Passport Initialization
app.use(passport.initialize());
app.use(passport.session());

// Define a local authentication strategy
passport.use(new LocalStrategy(
  function(username, password, done) {
    // Simulate user lookup
    if (username === 'test' && password === 'password') {
      return done(null, { id: 1, username: 'test' });
    } else {
      return done(null, false);
    }
  }
));

// Serialize and Deserialize user for session management
passport.serializeUser(function(user, done) {
  done(null, user.id);
});

passport.deserializeUser(function(id, done) {
  // Simulate user lookup by ID
  done(null, { id: id, username: 'test' });
});

// Routes
app.use(async ctx => {
  if (ctx.path === '/login' && ctx.method === 'POST') {
    return passport.authenticate('local', async (err, user, info, status) => {
      if (user) {
        await ctx.login(user);
        ctx.body = `Hello, ${user.username}! You are logged in.`;
      } else {
        ctx.status = 401;
        ctx.body = 'Login failed.';
      }
    })(ctx);
  } else if (ctx.path === '/logout') {
    ctx.logout();
    ctx.redirect('/');
  } else if (ctx.path === '/profile') {
    if (ctx.isAuthenticated()) {
      ctx.body = `Welcome back, ${ctx.state.user.username}!`;
    } else {
      ctx.redirect('/login-page'); // Redirect to a login page
    }
  } else if (ctx.path === '/login-page') {
    ctx.body = `
      <h1>Login</h1>
      <form action="/login" method="post">
        <input type="text" name="username" placeholder="username" />
        <input type="password" name="password" placeholder="password" />
        <button type="submit">Login</button>
      </form>
    `;
  } else {
    ctx.body = `
      <h1>Home</h1>
      <p>Status: ${ctx.isAuthenticated() ? 'Logged In' : 'Logged Out'}</p>
      <p><a href="/login-page">Login</a></p>
      <p><a href="/profile">Profile</a></p>
      ${ctx.isAuthenticated() ? '<p><a href="/logout">Logout</a></p>' : ''}
    `;
  }
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));