{"id":16742,"library":"remix-auth-oidc","title":"OpenIDConnect Strategy for Remix Auth","description":"remix-auth-oidc is an authentication strategy for the Remix web framework, specifically designed to integrate with the remix-auth library to facilitate OpenID Connect (OIDC) authentication flows. It extends the existing OAuth2Strategy provided by remix-auth-oauth2, offering a robust foundation for OIDC providers like Keycloak. The current stable version is 1.0.0, indicating a stable API. While release cadence isn't explicitly stated, the library aligns with Remix's development and is actively maintained. Its key differentiator is its focus on OIDC, building upon the more general OAuth2 strategy to provide specific OIDC profile parsing and flow management, making it easier to integrate with identity providers that adhere strictly to OIDC specifications. It supports both Node.js and Cloudflare runtimes, making it versatile for various deployment environments. Developers commonly extend this base class to create specific strategies for their chosen OIDC providers.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/matt-l-w/remix-auth-oidc","tags":["javascript","remix","remix-auth","auth","authentication","strategy","oidc","openidconnect","oauth","typescript"],"install":[{"cmd":"npm install remix-auth-oidc","lang":"bash","label":"npm"},{"cmd":"yarn add remix-auth-oidc","lang":"bash","label":"yarn"},{"cmd":"pnpm add remix-auth-oidc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication library that this strategy integrates with.","package":"remix-auth","optional":false},{"reason":"This strategy extends and heavily leans on the OAuth2 strategy, so understanding and potentially having it as a transitive dependency is crucial.","package":"remix-auth-oauth2","optional":false}],"imports":[{"note":"Primarily used in ESM contexts within Remix; CommonJS `require` is generally not idiomatic for new Remix projects.","wrong":"const { OpenIDConnectStrategy } = require('remix-auth-oidc');","symbol":"OpenIDConnectStrategy","correct":"import { OpenIDConnectStrategy } from 'remix-auth-oidc';"},{"note":"This is a TypeScript type, typically imported using `import type` for clarity and to avoid bundling it in JavaScript output.","symbol":"OIDCProfile","correct":"import type { OIDCProfile } from 'remix-auth-oidc';"},{"note":"This is a TypeScript type, typically imported using `import type` for clarity and to avoid bundling it in JavaScript output.","symbol":"OIDCExtraParams","correct":"import type { OIDCExtraParams } from 'remix-auth-oidc';"}],"quickstart":{"code":"import { OIDCExtraParams, OIDCProfile, OpenIDConnectStrategy } from 'remix-auth-oidc';\nimport { Authenticator } from 'remix-auth';\nimport { createCookieSessionStorage } from '@remix-run/node';\n\n// Mock user function for quickstart; replace with your actual user retrieval logic\nasync function getUser(accessToken: string, refreshToken: string, extraParams: OIDCExtraParams, profile: OIDCProfile, context: unknown) {\n  console.log('User profile:', profile);\n  // In a real app, you'd fetch/create a user from your DB here\n  return {\n    id: profile.id,\n    name: profile.displayName || profile.emails?.[0]?.value || 'User',\n    email: profile.emails?.[0]?.value || 'unknown@example.com',\n    accessToken,\n    refreshToken\n  };\n}\n\ntype KeycloakUserInfo = {\n  sub: string,\n  email: string,\n  preferred_username?: string,\n  name?: string,\n  given_name?: string,\n  family_name?: string,\n  picture?: string\n}\n\nexport type KeycloakUser = {\n  id: string\n  name?: string\n  email: string\n  accessToken: string\n  refreshToken: string\n}\n\nexport class KeycloakStrategy extends OpenIDConnectStrategy<KeycloakUser, OIDCProfile, OIDCExtraParams> {\n  name = 'keycloak';\n\n  constructor() {\n    super(\n      {\n        authorizationURL: process.env.KEYCLOAK_TRUST_ISSUER + '/protocol/openid-connect/auth' ?? 'http://localhost:8080/realms/master/protocol/openid-connect/auth',\n        tokenURL: process.env.KEYCLOAK_TRUST_ISSUER + '/protocol/openid-connect/token' ?? 'http://localhost:8080/realms/master/protocol/openid-connect/token',\n        clientID: process.env.KEYCLOAK_CLIENT_ID ?? 'remix-app',\n        clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? 'your-client-secret',\n        callbackURL: process.env.CALLBACK_URL ?? 'http://localhost:3000/auth/keycloak/callback'\n      },\n      async ({ accessToken, refreshToken, extraParams, profile, context }) => {\n        return await getUser(\n          accessToken,\n          refreshToken,\n          extraParams,\n          profile,\n          context\n        );\n      }\n    )\n  }\n\n  protected async userProfile(accessToken: string, params: OIDCExtraParams): Promise<OIDCProfile> {\n    const response = await fetch(\n      `${process.env.KEYCLOAK_TRUST_ISSUER ?? 'http://localhost:8080/realms/master'}/protocol/openid-connect/userinfo`,\n      {\n        headers: {\n          authorization: `Bearer ${accessToken}`,\n        }\n      }\n    );\n    if (!response.ok) {\n      let body = await response.text();\n      throw new Response(body, { status: 401 });\n    }\n    const data: KeycloakUserInfo = await response.json();\n    return {\n      provider: 'keycloak',\n      id: data.sub,\n      emails: [{ value: data.email }],\n      displayName: data.name,\n      name: {\n        familyName: data.family_name,\n        givenName: data.given_name,\n      },\n    }\n  }\n}\n\n// Setup Authenticator and session storage\nconst sessionStorage = createCookieSessionStorage({\n  cookie: {\n    name: '__session',\n    httpOnly: true,\n    path: '/',\n    sameSite: 'lax',\n    secrets: [process.env.SESSION_SECRET ?? 's3cr3t'],\n    secure: process.env.NODE_ENV === 'production',\n  },\n});\n\nexport const authenticator = new Authenticator<KeycloakUser>(sessionStorage);\nauthenticator.use(new KeycloakStrategy(), 'keycloak');\n\n// Example of how you would initiate the authentication flow in a Remix action/loader\n// (This part would be in a Remix route file, e.g., app/routes/auth.keycloak.tsx)\n/*\nimport type { ActionFunctionArgs } from '@remix-run/node';\nimport { redirect } from '@remix-run/node';\nimport { authenticator } from '~/services/auth.server'; // Adjust path\n\nexport async function action({ request }: ActionFunctionArgs) {\n  return authenticator.authenticate('keycloak', request, {\n    successRedirect: '/dashboard',\n    failureRedirect: '/login',\n  });\n}\n\n// Example of callback route (e.g., app/routes/auth.keycloak.callback.tsx)\nexport async function loader({ request }: ActionFunctionArgs) {\n  return authenticator.authenticate('keycloak', request, {\n    successRedirect: '/dashboard',\n    failureRedirect: '/login',\n  });\n}\n*/","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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'.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Response has a status of 401"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'protocol')"},{"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.","cause":"The `clientID` or `clientSecret` provided to the strategy constructor are incorrect or not recognized by the OIDC provider.","error":"Authentication failed: invalid_client"}],"ecosystem":"npm"}