CAS Plugin for Better Auth

Common errors

• CAS Login Failed: Service URL Mismatch

  cause The `service` parameter in the CAS login request does not match an allowlisted URL on the CAS server, or the `redirectUri` configured in the plugin is incorrect.
  fix Ensure the `redirectUri` option in `createStandardCasPlugin` is set to the exact, absolute URL of your CAS callback endpoint (e.g., `http://localhost:3000/api/auth/cas/callback`) and that this URL is allowlisted on your CAS server.

• User appears logged in after local signOut()

  cause The CAS SSO session cookie remains active even after a local `better-auth` session is cleared, leading to immediate re-authentication via CAS if the user attempts to log in again.
  fix Implement a comprehensive logout strategy that clears both the local `better-auth` session and redirects the user to the CAS server's logout endpoint. Refer to the 'Recommended global logout' example in the README.

Warnings

• gotcha Users may appear to 'auto-login' immediately after a local logout from your application because CAS maintains its own separate SSO session cookie. Clearing only the local session will not invalidate the CAS session.
  Fix: Implement a global logout route that first clears the local Better Auth session and then redirects the user to the CAS `/logout` endpoint with a `service` parameter pointing back to your application's public URL. Refer to the 'Recommended global logout' section in the README.
• gotcha Many CAS deployments require the `service` URL (the callback URL provided during login) to be explicitly allowlisted. A mismatch between the URL generated by the plugin and the allowlisted URL will result in CAS rejecting the authentication attempt.
  Fix: Explicitly set the `redirectUri` option in `createStandardCasPlugin` to your application's exact, absolute callback URL. This ensures the `service` parameter in the CAS login request matches the allowlisted value.
• breaking As this package is in a pre-1.0 release (0.1.x), the API and configuration options are subject to change without adhering to strict semantic versioning. While stable for initial use, be prepared for potential API adjustments in minor or patch releases.
  Fix: Monitor the project's changelog and release notes closely when updating to new versions. Thoroughly test your integration after any update to ensure continued functionality.

Install

• npm install better-auth-cas npm
• yarn add better-auth-cas yarn
• pnpm add better-auth-cas pnpm

Imports

• createStandardCasPlugin
  wrong:

  const createStandardCasPlugin = require('better-auth-cas').createStandardCasPlugin;

  correct:

  import { createStandardCasPlugin } from 'better-auth-cas';

  The library ships with TypeScript types and is primarily designed for ESM usage. While CJS is technically possible with transpilation, direct `require` is not the idiomatic approach.
• auth

  import { auth } from '@/lib/auth';

  The `auth` instance is typically an instance of `betterAuth` initialized in a local application file, not directly imported from `better-auth-cas`.
• NextRequest, NextResponse

  import { NextRequest, NextResponse } from 'next/server';

  These types are used in examples demonstrating integration within a Next.js environment, particularly for logout handlers. They are not direct exports of `better-auth-cas`.

Quickstart

Initializes `better-auth` with the standard CAS plugin, demonstrating how to configure the CAS base URL, callback path, and provider ID. It also highlights optional configuration for `redirectUri` and `profileMapping` using environment variables.

import { betterAuth } from 'better-auth';
import { createStandardCasPlugin } from 'better-auth-cas';

// In a production environment, casBaseUrl should come from environment variables.
const casBaseUrl = process.env.CAS_BASE_URL || 'https://cas.example.com/cas';
const callbackPath = process.env.CAS_CALLBACK_PATH || '/api/auth/cas/callback';
const providerId = process.env.CAS_PROVIDER_ID || 'cas';

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
  },
  plugins: [
    createStandardCasPlugin({
      casBaseUrl: casBaseUrl,
      callbackPath: callbackPath,
      providerId: providerId,
      // Optional: Set redirectUri if your CAS server requires an exact match for the service URL
      // redirectUri: process.env.CAS_REDIRECT_URI || 'http://localhost:3000/api/auth/cas/callback',
      // Optional: Custom profile mapping if CAS attributes differ from defaults
      // profileMapping: {
      //   stableId: ['sAMAccountName', 'uid'],
      //   name: ['displayName'],
      //   email: ['mail'],
      //   image: ['thumbnailPhoto']
      // }
    }),
  ],
});