{"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.","language":"javascript","status":"active","last_verified":"Wed Apr 22","install":{"commands":["npm install remix-auth-oidc"],"cli":null},"imports":["import { OpenIDConnectStrategy } from 'remix-auth-oidc';","import type { OIDCProfile } from 'remix-auth-oidc';","import type { OIDCExtraParams } from 'remix-auth-oidc';"],"auth":{"required":false,"env_vars":[]},"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}