Node.js CAS Client Middleware

Common errors

• TypeError: handler is not a function

  cause Attempting to `require('http-cas-client/wrap/koa2')` and then use it directly as a function for native `http` server.
  fix Ensure you are importing the correct module: `const httpCasClient = require('http-cas-client');` for native HTTP, or `const koaCasClient = require('http-cas-client/wrap/koa2');` for Koa.

• Error: Ticket validation failed: Invalid ticket or service URL mismatch.

  cause The `casServerUrlPrefix` or `serverName` configuration is incorrect, preventing the CAS server from validating the service ticket.
  fix Double-check that `casServerUrlPrefix` points to the correct base URL of your CAS server and `serverName` is the exact, publicly accessible URL of your Node.js application.

• ReferenceError: Koa is not defined

  cause Using `koaCasClient` or `koaSessionCasClient` wrappers without having Koa installed or imported.
  fix Install Koa (`npm install koa`) and ensure it's imported at the top of your file (`const Koa = require('koa');` or `import Koa from 'koa';`).

Warnings

• gotcha When using the Koa2 wrapper, placing `koa-bodyparser` middleware *after* `http-cas-client` can prevent `bodyparser` from receiving `req.socket` data, leading to parsing issues.
  Fix: Ensure `koa-bodyparser` is registered *before* the `http-cas-client` middleware in your Koa application's middleware chain.
• gotcha The library primarily uses CommonJS `require` syntax in its examples. While it ships TypeScript types, direct ESM `import` might require careful configuration or a build step in some Node.js environments.
  Fix: For modern ESM projects, use `import` statements and ensure your `tsconfig.json` and `package.json` (type: 'module') are configured correctly for module resolution. If issues arise, consider transpilation or using the `require` syntax temporarily if your project supports both.
• gotcha The `serverName` option must accurately reflect the base URL (protocol, host, and port) where your Node.js application is accessible. Misconfiguration will lead to incorrect CAS service URLs and failed authentication redirects.
  Fix: Set `serverName` to the complete base URL of your application, e.g., `'http://localhost:3000'` or `'https://your-domain.com'`. Ensure it's reachable by the CAS server.
• gotcha The library is in a pre-1.0 version (0.4.3). While seemingly stable, minor versions may introduce breaking changes without a major version increment, as per typical pre-1.0 SemVer practices.
  Fix: Pin your dependency to an exact version (`~0.4.3` instead of `^0.4.3`) and review release notes carefully when upgrading to newer minor versions.

Install

• npm install http-cas-client npm
• yarn add http-cas-client yarn
• pnpm add http-cas-client pnpm

Imports

• httpCasClient
  wrong:

  const httpCasClient = require('http-cas-client');

  correct:

  import httpCasClient from 'http-cas-client';

  Primarily used with Node.js native http module. The `require` syntax is shown in examples but `import` is preferred for modern ESM projects.
• koaCasClient
  wrong:

  const koaCasClient = require('http-cas-client'); // Incorrect path
  const koaCasClient = require('http-cas-client/wrap/koa2');

  correct:

  import koaCasClient from 'http-cas-client/wrap/koa2';

  Specifically for Koa2 integration without session management. Requires importing from a subpath.
• koaSessionCasClient
  wrong:

  const koaSessionCasClient = require('http-cas-client'); // Incorrect path
  const koaSessionCasClient = require('http-cas-client/wrap/koa2-session');

  correct:

  import koaSessionCasClient from 'http-cas-client/wrap/koa2-session';

  Specifically for Koa2 integration with session management. Requires importing from a subpath and a `koa-session` middleware.
• Principal

  import type { Principal } from 'http-cas-client';

  Type import for the Principal object returned by the middleware, useful for TypeScript projects.

Quickstart

Demonstrates basic CAS client integration with Node.js's native HTTP server, authenticating users and accessing their principal information.

import http from 'http';
import httpCasClient from 'http-cas-client';

const casServerUrlPrefix = process.env.CAS_SERVER_URL_PREFIX || 'http://localhost:9000/cas';
const serverName = process.env.APP_SERVER_NAME || 'http://127.0.0.1';

const handler = httpCasClient({
	casServerUrlPrefix: casServerUrlPrefix,
	serverName: serverName,
    // Example of setting a custom logger
    logger: console
});

http.createServer(async (req, res) => {
	if (!await handler(req, res)) {
		// If the handler returns false, it means a redirect or other action was taken,
		// and the response has already been handled. Stop further processing.
		return res.end();
	}

	// The principal and ticket are attached to the request object after successful authentication.
	const { principal, ticket } = req;

	console.log('Authenticated Principal:', principal);
	console.log('CAS Ticket:', ticket);

	// Your application logic for authenticated users
	res.writeHead(200, { 'Content-Type': 'text/html' });
	res.end(`<h1>Hello, ${principal?.user || 'Guest'}!</h1><p>Attributes: ${JSON.stringify(principal?.attributes)}</p><p><a href="${casServerUrlPrefix}/logout">Logout</a></p>`);
}).listen(80,
    () => console.log(`Application listening on port 80. CAS Server: ${casServerUrlPrefix}`)
);