OpenIDConnect Strategy for Remix Auth

Common errors

• Error: Response has a status of 401

  cause This usually indicates an issue with the access token being invalid or expired when calling the OIDC provider's user info endpoint, or the `userProfile` implementation failing to handle a valid response.
  fix Inspect the network request to the `userinfo` endpoint; ensure the `accessToken` is correct and not expired. Verify the OIDC provider's logs for more details. Debug your `userProfile` method's `fetch` call and response handling.

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

  cause This often occurs when `process.env.KEYCLOAK_TRUST_ISSUER` or other environment variables used to construct URLs are undefined, leading to invalid URL construction.
  fix Ensure all environment variables used in `authorizationURL`, `tokenURL`, and the `userProfile` method (like `KEYCLOAK_TRUST_ISSUER`) are correctly defined and accessible in your application's runtime environment.

• Authentication failed: invalid_client

  cause The `clientID` or `clientSecret` provided to the strategy constructor are incorrect or not recognized by the OIDC provider.
  fix Verify that `process.env.KEYCLOAK_CLIENT_ID` and `process.env.KEYCLOAK_CLIENT_SECRET` match the credentials registered for your client application within your OIDC provider's configuration.

Warnings

• gotcha This strategy heavily relies on environment variables for sensitive configuration like client IDs, secrets, and URLs. Hardcoding these values or failing to provide them will lead to authentication failures and potential security vulnerabilities.
  Fix: Ensure all required environment variables (e.g., `KEYCLOAK_TRUST_ISSUER`, `KEYCLOAK_CLIENT_ID`, `KEYCLOAK_CLIENT_SECRET`, `CALLBACK_URL`) are properly set in your deployment environment and during local development. Use tools like `dotenv` for local setups.
• gotcha The `callbackURL` must exactly match the redirect URI configured in your OpenID Connect provider (e.g., Keycloak). A mismatch will result in authentication errors, typically 'invalid_redirect_uri'.
  Fix: Double-check that the `callbackURL` configured in your strategy constructor is identical to the 'Valid Redirect URI' registered with your OIDC provider. Ensure no trailing slashes or differing casing.
• breaking As this strategy extends `remix-auth-oauth2`, understanding the underlying OAuth2 flow and potential breaking changes in `remix-auth` or `remix-auth-oauth2` is critical, as they can directly impact this strategy.
  Fix: Always review the changelogs and documentation for `remix-auth` and `remix-auth-oauth2` when upgrading to new major versions to anticipate and address any API changes or behavioral modifications.

Install

• npm install remix-auth-oidc npm
• yarn add remix-auth-oidc yarn
• pnpm add remix-auth-oidc pnpm

Imports

• OpenIDConnectStrategy
  wrong:

  const { OpenIDConnectStrategy } = require('remix-auth-oidc');

  correct:

  import { OpenIDConnectStrategy } from 'remix-auth-oidc';

  Primarily used in ESM contexts within Remix; CommonJS `require` is generally not idiomatic for new Remix projects.
• OIDCProfile

  import type { OIDCProfile } from 'remix-auth-oidc';

  This is a TypeScript type, typically imported using `import type` for clarity and to avoid bundling it in JavaScript output.
• OIDCExtraParams

  import type { OIDCExtraParams } from 'remix-auth-oidc';

  This is a TypeScript type, typically imported using `import type` for clarity and to avoid bundling it in JavaScript output.

Quickstart

This quickstart demonstrates how to set up a Keycloak OIDC strategy using `remix-auth-oidc`, including environment variable configuration, user profile mapping, and integrating it with `remix-auth`'s Authenticator. It provides a complete, runnable example of how to define and use a custom OIDC strategy, including placeholder values for local development.

import { OIDCExtraParams, OIDCProfile, OpenIDConnectStrategy } from 'remix-auth-oidc';
import { Authenticator } from 'remix-auth';
import { createCookieSessionStorage } from '@remix-run/node';

// Mock user function for quickstart; replace with your actual user retrieval logic
async function getUser(accessToken: string, refreshToken: string, extraParams: OIDCExtraParams, profile: OIDCProfile, context: unknown) {
  console.log('User profile:', profile);
  // In a real app, you'd fetch/create a user from your DB here
  return {
    id: profile.id,
    name: profile.displayName || profile.emails?.[0]?.value || 'User',
    email: profile.emails?.[0]?.value || 'unknown@example.com',
    accessToken,
    refreshToken
  };
}

type KeycloakUserInfo = {
  sub: string,
  email: string,
  preferred_username?: string,
  name?: string,
  given_name?: string,
  family_name?: string,
  picture?: string
}

export type KeycloakUser = {
  id: string
  name?: string
  email: string
  accessToken: string
  refreshToken: string
}

export class KeycloakStrategy extends OpenIDConnectStrategy<KeycloakUser, OIDCProfile, OIDCExtraParams> {
  name = 'keycloak';

  constructor() {
    super(
      {
        authorizationURL: process.env.KEYCLOAK_TRUST_ISSUER + '/protocol/openid-connect/auth' ?? 'http://localhost:8080/realms/master/protocol/openid-connect/auth',
        tokenURL: process.env.KEYCLOAK_TRUST_ISSUER + '/protocol/openid-connect/token' ?? 'http://localhost:8080/realms/master/protocol/openid-connect/token',
        clientID: process.env.KEYCLOAK_CLIENT_ID ?? 'remix-app',
        clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? 'your-client-secret',
        callbackURL: process.env.CALLBACK_URL ?? 'http://localhost:3000/auth/keycloak/callback'
      },
      async ({ accessToken, refreshToken, extraParams, profile, context }) => {
        return await getUser(
          accessToken,
          refreshToken,
          extraParams,
          profile,
          context
        );
      }
    )
  }

  protected async userProfile(accessToken: string, params: OIDCExtraParams): Promise<OIDCProfile> {
    const response = await fetch(
      `${process.env.KEYCLOAK_TRUST_ISSUER ?? 'http://localhost:8080/realms/master'}/protocol/openid-connect/userinfo`,
      {
        headers: {
          authorization: `Bearer ${accessToken}`,
        }
      }
    );
    if (!response.ok) {
      let body = await response.text();
      throw new Response(body, { status: 401 });
    }
    const data: KeycloakUserInfo = await response.json();
    return {
      provider: 'keycloak',
      id: data.sub,
      emails: [{ value: data.email }],
      displayName: data.name,
      name: {
        familyName: data.family_name,
        givenName: data.given_name,
      },
    }
  }
}

// Setup Authenticator and session storage
const sessionStorage = createCookieSessionStorage({
  cookie: {
    name: '__session',
    httpOnly: true,
    path: '/',
    sameSite: 'lax',
    secrets: [process.env.SESSION_SECRET ?? 's3cr3t'],
    secure: process.env.NODE_ENV === 'production',
  },
});

export const authenticator = new Authenticator<KeycloakUser>(sessionStorage);
authenticator.use(new KeycloakStrategy(), 'keycloak');

// Example of how you would initiate the authentication flow in a Remix action/loader
// (This part would be in a Remix route file, e.g., app/routes/auth.keycloak.tsx)
/*
import type { ActionFunctionArgs } from '@remix-run/node';
import { redirect } from '@remix-run/node';
import { authenticator } from '~/services/auth.server'; // Adjust path

export async function action({ request }: ActionFunctionArgs) {
  return authenticator.authenticate('keycloak', request, {
    successRedirect: '/dashboard',
    failureRedirect: '/login',
  });
}

// Example of callback route (e.g., app/routes/auth.keycloak.callback.tsx)
export async function loader({ request }: ActionFunctionArgs) {
  return authenticator.authenticate('keycloak', request, {
    successRedirect: '/dashboard',
    failureRedirect: '/login',
  });
}
*/