Remix Auth Keycloak Strategy

Common errors

• Error: Response not found for strategy "keycloak"

  cause This usually indicates that the `authenticator.authenticate` call in your Remix action or loader is not correctly configured or the strategy name ('keycloak' by default) doesn't match.
  fix Ensure that `authenticator.use(keycloakStrategy, "keycloak")` is called with the correct strategy name and that the `authenticator.authenticate("keycloak", request, ...)` calls in your routes also use `"keycloak"`.

• TypeError: Cannot read properties of undefined (reading 'authenticate')

  cause The `authenticator` instance was not properly initialized or exported/imported in the file where it's being used.
  fix Verify that `export const authenticator = new Authenticator<User>(sessionStorage);` is in a server-side utility file (e.g., `app/utils/auth.server.ts`) and is correctly imported into your route files.

• Keycloak: Invalid client or redirect URI

  cause This error originates from the Keycloak server and means there's a mismatch in the `clientID`, `clientSecret`, or `callbackURL` provided by your Remix application and what Keycloak expects.
  fix Double-check the `clientID`, `clientSecret`, and `callbackURL` in your `KeycloakStrategy` configuration against your Keycloak client settings. Pay close attention to trailing slashes and case sensitivity for the URL.

Warnings

• breaking This package is a direct replacement for `remix-auth-keycloak`, which was archived on December 2nd, 2023. Users migrating from the old package must update their `package.json` and all import statements from `remix-auth-keycloak` to `remix-keycloak`.
  Fix: Uninstall `remix-auth-keycloak` and install `remix-keycloak`. Update all import paths to reference `remix-keycloak`.
• gotcha The `KeycloakStrategy` requires several configuration options (domain, realm, clientID, clientSecret, callbackURL) that are critical for connecting to your Keycloak instance. Incorrect values will lead to authentication failures.
  Fix: Ensure all Keycloak configuration parameters match your Keycloak client setup precisely, especially `clientID`, `clientSecret`, and `callbackURL`. The `callbackURL` must be registered in Keycloak for your client.
• gotcha For production deployments, `useSSL` should almost always be `true`. Misconfiguring SSL can lead to security vulnerabilities or connection issues, especially when Keycloak is served over HTTPS.
  Fix: Set `useSSL: true` in your `KeycloakStrategy` configuration when deploying to production environments. Ensure your Keycloak instance and your Remix application are accessible via HTTPS.
• gotcha The authentication `callbackURL` configured in `KeycloakStrategy` must exactly match one of the valid redirect URIs configured for your client in the Keycloak admin console. A mismatch will result in a redirect error from Keycloak.
  Fix: Verify that the `callbackURL` in your strategy instance is identical to an authorized redirect URI in your Keycloak client settings. Include the full URL, including protocol and port if applicable.

Install

• npm install remix-keycloak npm
• yarn add remix-keycloak yarn
• pnpm add remix-keycloak pnpm

Imports

• KeycloakStrategy
  wrong:

  import { Keycloak } from 'remix-auth-keycloak'

  correct:

  import { KeycloakStrategy } from 'remix-keycloak'

  The strategy class for Keycloak. Ensure you import from 'remix-keycloak', not the old 'remix-auth-keycloak' package.
• Authenticator

  import { Authenticator } from 'remix-auth'

  remix-keycloak integrates with remix-auth; Authenticator is imported from 'remix-auth', not remix-keycloak itself. This is standard for remix-auth strategies.
• loader

  export let loader: LoaderFunction = ({ request }) => { /* ... */ }

  Remix loaders handle GET requests. When setting up callback routes, the loader will typically be used for the initial authentication success/failure redirect.
• action

  export let action: ActionFunction = ({ request }) => { /* ... */ }

  Remix actions handle POST requests. The action is used to initiate the Keycloak authentication flow, usually via a form submission.

Quickstart

This quickstart demonstrates how to set up `KeycloakStrategy` with `remix-auth`, configure environment variables, and define the authentication and callback routes required for a complete Keycloak login flow in a Remix application. It also shows a basic `User` interface and session storage setup.

import { Authenticator } from "remix-auth";
import { KeycloakStrategy } from "remix-keycloak";
import { createCookieSessionStorage } from "@remix-run/node";

interface User {
  id: string;
  email: string;
  name: string;
}

// Create a session storage for the authenticator
const sessionStorage = createCookieSessionStorage({
  cookie: {
    name: "_session",
    sameSite: "lax",
    path: "/",
    httpOnly: true,
    secrets: [process.env.SESSION_SECRET ?? 'super-secret-key'],
    secure: process.env.NODE_ENV === "production",
  },
});

export const authenticator = new Authenticator<User>(sessionStorage);

const keycloakStrategy = new KeycloakStrategy(
  {
    useSSL: process.env.KEYCLOAK_USE_SSL === 'true',
    domain: process.env.KEYCLOAK_DOMAIN ?? 'your-keycloak-domain.com',
    realm: process.env.KEYCLOAK_REALM ?? 'your-realm',
    clientID: process.env.KEYCLOAK_CLIENT_ID ?? 'your-client-id',
    clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? 'your-client-secret',
    callbackURL: process.env.KEYCLOAK_CALLBACK_URL ?? 'http://localhost:3000/auth/keycloak/callback',
  },
  async ({ accessToken, refreshToken, extraParams, profile }) => {
    // In a real application, you would typically find or create a user in your DB
    // based on the profile data from Keycloak.
    console.log("Keycloak Profile:", profile);
    console.log("Access Token:", accessToken);
    // For this example, we'll return a mock user
    return {
      id: profile.id || profile.emails?.[0]?.value || 'anonymous',
      email: profile.emails?.[0]?.value || 'user@example.com',
      name: profile.displayName || 'Keycloak User'
    };
  }
);

authenticator.use(keycloakStrategy, "keycloak");

// Example route: app/routes/login.tsx
// export default function Login() {
//   return (
//     <form action="/auth/keycloak" method="post">
//       <button>Login with Keycloak</button>
//     </form>
//   );
// }

// Example route: app/routes/auth/keycloak.tsx
// import type { ActionFunction } from "@remix-run/node";
// import { authenticator } from "~/utils/auth.server"; // Adjust path as needed

// export let action: ActionFunction = ({ request }) => {
//   return authenticator.authenticate("keycloak", request);
// };

// Example route: app/routes/auth/keycloak/callback.tsx
// import type { LoaderFunction } from "@remix-run/node";
// import { redirect } from "@remix-run/node";
// import { authenticator } from "~/utils/auth.server"; // Adjust path as needed

// export let loader: LoaderFunction = ({ request }) => {
//   return authenticator.authenticate("keycloak", request, {
//     successRedirect: "/dashboard",
//     failureRedirect: "/login",
//   });
// };