Registry / auth-security / remix-auth-okta

remix-auth-okta

JSON →
library1.2.0jsnpmunverified

This package provides an authentication strategy for integrating Okta with Remix applications through the `remix-auth` library. It extends the `OAuth2Strategy` to handle Okta's specific OAuth 2.0 and OpenID Connect flows, supporting both Node.js and Cloudflare runtimes. The current stable version is 1.2.0, with updates generally following `remix-auth`'s release cadence and Okta API changes. `remix-auth-okta` enables developers to quickly set up user authentication against an Okta account, managing the redirect to Okta for login and processing the callback. Its key differentiators include tight integration with the `remix-auth` ecosystem, offering a standardized approach to adding Okta authentication, and flexibility to support both Okta's hosted login page and custom login forms within the Remix application.

npm install remix-auth-okta
INSTALL
IMPORT
SIG · REMIX-AUTH-OKTA
R
remix-auth-okta
auth-securityjavascriptv1.2.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

OktaStrategy
✓ import { OktaStrategy } from 'remix-auth-okta';
✗ const OktaStrategy = require('remix-auth-okta');
Remix applications are primarily built with ESM, making CommonJS `require` generally incorrect for modern usage. Use named imports for `OktaStrategy`.
Authenticator
✓ import { Authenticator } from 'remix-auth';
✗ const Authenticator = require('remix-auth');
The `Authenticator` class is the core utility from the `remix-auth` peer dependency, not `remix-auth-okta` itself. Ensure it's imported correctly from `remix-auth`.
User (Generic Type)
✓ interface User { id: string; email: string; } export const authenticator = new Authenticator<User>(sessionStorage);
While not directly an import from `remix-auth-okta`, defining a generic type (`User` in this example) for the `Authenticator` is crucial for type safety in TypeScript and specifies what is stored in the session. This is a common pattern and source of confusion for new users.

This quickstart demonstrates the core setup of `remix-auth-okta`. It initializes the `OktaStrategy` using environment variables for sensitive credentials, configures a basic `Authenticator` instance with a session storage, and defines the post-authentication callback to process user profile data from Okta.

// app/utils/auth.server.ts import { Authenticator } from "remix-auth"; import { OktaStrategy } from "remix-auth-okta"; import { createCookieSessionStorage } from "@remix-run/node"; // Example for session storage // Define your user type that will be stored in the session interface AppUser { id: string; email: string; } // Configure session storage (replace with your actual session setup) const sessionStorage = createCookieSessionStorage({ cookie: { name: "_session", httpOnly: true, secure: process.env.NODE_ENV === "production", // Use secure cookies in production secrets: [process.env.SESSION_SECRET ?? "s3cr3t"], // Must provide a secret maxAge: 60 * 60 * 24 * 7, // 7 days }, }); // Create an instance of the authenticator export const authenticator = new Authenticator<AppUser>(sessionStorage); // Initialize the Okta Strategy with environment variables const oktaStrategy = new OktaStrategy( { issuer: process.env.OKTA_ISSUER ?? 'YOUR_OKTA_ISSUER_MISSING', clientID: process.env.OKTA_CLIENT_ID ?? 'YOUR_OKTA_CLIENT_ID_MISSING', clientSecret: process.env.OKTA_CLIENT_SECRET ?? 'YOUR_OKTA_CLIENT_SECRET_MISSING', callbackURL: process.env.OKTA_CALLBACK_URL ?? 'http://localhost:3000/auth/okta/callback', }, async ({ accessToken, refreshToken, extraParams, profile }) => { // This callback runs after a successful Okta authentication. // Here, you would typically find or create a user in your database // based on the profile information (e.g., profile.email). console.log("Okta Profile:", profile); // Return a user object that will be stored in the session. return { id: profile.id, email: profile.email ?? 'unknown@example.com' }; } ); // Register the strategy with a unique name (e.g., "okta") authenticator.use(oktaStrategy, "okta");
Debug
Known issues
gotchaIncorrectly configuring the `callbackURL` will lead to authentication failures or redirects to the wrong origin, resulting in 'invalid_redirect_uri' errors from Okta.
fix
Ensure the `callbackURL` in your Okta application settings precisely matches the `callbackURL` configured in your `OktaStrategy` instance and your Remix callback route (e.g., `/auth/okta/callback`). Pay attention to hostname, port, and scheme (HTTP/HTTPS).
affects: >=1.0.0
breakingMajor version upgrades of `remix-auth` (the peer dependency) may introduce API changes that require corresponding updates to `remix-auth-okta` or modifications in how `Authenticator` methods are used.
fix
Always consult the release notes for both `remix-auth` and `remix-auth-okta` when performing major version upgrades. Test authentication flows thoroughly after updates.
affects: >=1.0.0
gotchaWhen using the `withCustomLoginForm: true` option, you must also provide `oktaDomain` and implement a custom login form within your Remix app that collects user credentials (username/password).
fix
If `withCustomLoginForm` is enabled, verify that `oktaDomain` is correctly configured and that your Remix action handler for `/auth/okta` is designed to process the form data (email, password) and pass it to Okta's authentication API, rather than initiating a redirect to Okta's hosted login page.
affects: >=1.0.0
gotchaMissing or incorrect environment variables for `issuer`, `clientID`, or `clientSecret` will prevent the strategy from initializing or cause immediate authentication failures (e.g., 'invalid_client').
fix
Double-check that all required Okta credentials (`OKTA_ISSUER`, `OKTA_CLIENT_ID`, `OKTA_CLIENT_SECRET`) are correctly defined in your server's environment variables and that the Remix application can access them.
affects: >=1.0.0
Errors
Common errors & fixes
Error: invalid_client
The `clientID` or `clientSecret` provided to the `OktaStrategy` is incorrect, or the Okta application configuration is invalid (e.g., wrong type or disabled).
fix
Verify `clientID` and `clientSecret` against your Okta application settings. Ensure the Okta application is configured as a 'Web' application and that the client credentials are valid.
Error: redirect_uri_mismatch
The `callbackURL` configured in `OktaStrategy` does not exactly match one of the allowed redirect URIs defined in your Okta application settings.
fix
Go to your Okta application settings and add or correct the 'Login redirect URIs' to precisely match the `callbackURL` specified in your `OktaStrategy` constructor.
ReferenceError: sessionStorage is not defined
The `sessionStorage` object passed to the `Authenticator` is not correctly imported or configured for a server-side (Node.js/Cloudflare) Remix environment.
fix
Ensure `sessionStorage` is created using a server-side utility like `@remix-run/node`'s `createCookieSessionStorage` and correctly imported into `auth.server.ts`. It must include a `secrets` array for security.
Error: Okta: Unable to retrieve user information from profile. [401 Unauthorized]
The access token obtained from Okta lacked sufficient scopes to retrieve the requested user profile information, or the token itself was invalid/expired during the profile fetch.
fix
Verify that the scopes configured in your Okta application (and potentially requested by the `OktaStrategy` if extended) include necessary profile scopes like `openid`, `profile`, `email`, etc., to allow access to user data.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies
remix-authrequiredRequired peer dependency for `remix-auth` strategies, providing the core `Authenticator` class and OAuth2 base strategy.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
remix-auth-okta — npm install remix-auth-okta · libregistry