Registry / web-framework / remix-auth-oidc

remix-auth-oidc

JSON →
library1.0.0jsnpmunverified

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.

npm install remix-auth-oidc
INSTALL
IMPORT
SIG · REMIX-AUTH-OIDC
R
remix-auth-oidc
web-frameworkjavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenIDConnectStrategy
import { OpenIDConnectStrategy } from 'remix-auth-oidc';
const { OpenIDConnectStrategy } = require('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.

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', }); } */
Debug
Known issues
gotchaThis 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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
breakingAs 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Response has a status of 401
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')
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
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.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
remix-authrequiredCore authentication library that this strategy integrates with.
remix-auth-oauth2requiredThis strategy extends and heavily leans on the OAuth2 strategy, so understanding and potentially having it as a transitive dependency is crucial.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
remix-auth-oidc — npm install remix-auth-oidc · libregistry