{"id":15645,"library":"http-cas-client","title":"Node.js CAS Client Middleware","description":"http-cas-client provides a comprehensive Central Authentication Service (CAS) client middleware for Node.js environments, supporting CAS 1.0, 2.0+, and 3.0+ protocols. As of version 0.4.3, it offers core features like Single Sign-On (SSO), CAS Proxy capabilities (including proxy chain checking), and Single Logout (SLO). The library is designed to be framework-agnostic, providing direct integration with Node's native `http` module and specific wrappers for popular frameworks like Koa2, with support for both session-based and no-session modes. While actively maintained, the package is still in a pre-1.0 state, indicating potential for further evolution before a stable API is declared. Key differentiators include its explicit support for various CAS protocol versions and its flexibility in integration patterns, including cluster-friendliness (though this feature is marked 'TODO' in the README) and principal adaptation for debugging.","status":"active","version":"0.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/lemonce/cas-client","tags":["javascript","cas","node","client","apereo","CAS3","CAS2","cas-client","koa","typescript"],"install":[{"cmd":"npm install http-cas-client","lang":"bash","label":"npm"},{"cmd":"yarn add http-cas-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-cas-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Needed for Koa2 framework integration wrappers.","package":"koa","optional":true},{"reason":"Common dependency for Koa2 applications, interacts with http-cas-client middleware.","package":"koa-bodyparser","optional":true},{"reason":"Required for session-based CAS client integration with Koa2.","package":"koa-session","optional":true}],"imports":[{"note":"Primarily used with Node.js native http module. The `require` syntax is shown in examples but `import` is preferred for modern ESM projects.","wrong":"const httpCasClient = require('http-cas-client');","symbol":"httpCasClient","correct":"import httpCasClient from 'http-cas-client';"},{"note":"Specifically for Koa2 integration without session management. Requires importing from a subpath.","wrong":"const koaCasClient = require('http-cas-client'); // Incorrect path\nconst koaCasClient = require('http-cas-client/wrap/koa2');","symbol":"koaCasClient","correct":"import koaCasClient from 'http-cas-client/wrap/koa2';"},{"note":"Specifically for Koa2 integration with session management. Requires importing from a subpath and a `koa-session` middleware.","wrong":"const koaSessionCasClient = require('http-cas-client'); // Incorrect path\nconst koaSessionCasClient = require('http-cas-client/wrap/koa2-session');","symbol":"koaSessionCasClient","correct":"import koaSessionCasClient from 'http-cas-client/wrap/koa2-session';"},{"note":"Type import for the Principal object returned by the middleware, useful for TypeScript projects.","symbol":"Principal","correct":"import type { Principal } from 'http-cas-client';"}],"quickstart":{"code":"import http from 'http';\nimport httpCasClient from 'http-cas-client';\n\nconst casServerUrlPrefix = process.env.CAS_SERVER_URL_PREFIX || 'http://localhost:9000/cas';\nconst serverName = process.env.APP_SERVER_NAME || 'http://127.0.0.1';\n\nconst handler = httpCasClient({\n\tcasServerUrlPrefix: casServerUrlPrefix,\n\tserverName: serverName,\n    // Example of setting a custom logger\n    logger: console\n});\n\nhttp.createServer(async (req, res) => {\n\tif (!await handler(req, res)) {\n\t\t// If the handler returns false, it means a redirect or other action was taken,\n\t\t// and the response has already been handled. Stop further processing.\n\t\treturn res.end();\n\t}\n\n\t// The principal and ticket are attached to the request object after successful authentication.\n\tconst { principal, ticket } = req;\n\n\tconsole.log('Authenticated Principal:', principal);\n\tconsole.log('CAS Ticket:', ticket);\n\n\t// Your application logic for authenticated users\n\tres.writeHead(200, { 'Content-Type': 'text/html' });\n\tres.end(`<h1>Hello, ${principal?.user || 'Guest'}!</h1><p>Attributes: ${JSON.stringify(principal?.attributes)}</p><p><a href=\"${casServerUrlPrefix}/logout\">Logout</a></p>`);\n}).listen(80,\n    () => console.log(`Application listening on port 80. CAS Server: ${casServerUrlPrefix}`)\n);","lang":"typescript","description":"Demonstrates basic CAS client integration with Node.js's native HTTP server, authenticating users and accessing their principal information."},"warnings":[{"fix":"Ensure `koa-bodyparser` is registered *before* the `http-cas-client` middleware in your Koa application's middleware chain.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require('http-cas-client/wrap/koa2')` and then use it directly as a function for native `http` server.","error":"TypeError: handler is not a function"},{"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.","cause":"The `casServerUrlPrefix` or `serverName` configuration is incorrect, preventing the CAS server from validating the service ticket.","error":"Error: Ticket validation failed: Invalid ticket or service URL mismatch."},{"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';`).","cause":"Using `koaCasClient` or `koaSessionCasClient` wrappers without having Koa installed or imported.","error":"ReferenceError: Koa is not defined"}],"ecosystem":"npm"}