remix-auth-oauth2

Install the strategy using npm to add OAuth2 support to your Remix application.

npm add remix-auth-oauth2

The OAuth2 flow requires calling authenticator.authenticate twice: once to initiate the redirect to the provider, and once in the callback route to handle the response.

1. Initiation Route: Call authenticate in an action (for POST) or loader (for GET). This redirects the user to the provider.
2. Callback Route: Create a route matching your redirectURI. This must be a loader because the provider redirects via a GET request. Calling authenticate here will process the code and return the user object.

// 1. Initiation Route
export async function action({ request }: Route.ActionArgs) {
  await authenticator.authenticate("provider-name", request);
}

// 2. Callback Route (must be a loader)
export async function loader({ request }: Route.LoaderArgs) {
  let user = await authenticator.authenticate("provider-name", request);
  // user is now available
}

You can pass an object to the cookie option in the OAuth2Strategy configuration to customize the session cookie (e.g., name, maxAge, path, httpOnly, sameSite, secure).

new OAuth2Strategy(
  {
    cookie: {
      name: "oauth2",
      maxAge: 60 * 60 * 24 * 7, // 1 week
      path: "/auth",
      httpOnly: true,
      sameSite: "lax",
      secure: process.env.NODE_ENV === "production",
    },
    clientId: CLIENT_ID,
    // ... other options
  },
  async ({ tokens, request }) => { ... }
)

You can revoke a user's access token with the provider by calling revokeToken on the strategy instance.

await strategy.revokeToken(user.accessToken);

The OAuth2Strategy exposes a refreshToken method to obtain new tokens using a stored refresh token. The refresh token is available via tokens.refreshToken() inside the strategy's verify function.

// Inside your verify function, you might return the refresh token as part of the user object
async ({ tokens, request }) => {
  let user = await getUser(tokens, request);
  return {
    ...user,
    accessToken: tokens.accessToken(),
    refreshToken: tokens.hasRefreshToken() ? tokens.refreshToken() : null,
  };
}

// Later, to refresh:
let strategy = new OAuth2Strategy<User>(options, verify);
let tokens = await strategy.refreshToken(user.refreshToken);

Instead of manually providing all endpoints, you can use the static discover method. It fetches the provider's configuration from /.well-known/openid-configuration to automatically populate authorization, token, and revocation endpoints. It also attempts to use S256 for code challenges if supported.

Warning: This performs a network fetch during strategy creation, which adds latency to your application startup. It is recommended to use this once to find the endpoints, then hardcode them in your configuration.

authenticator.use(
  await OAuth2Strategy.discover<User>(
    "https://provider.com",
    {
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      redirectURI: "https://example.app/auth/callback",
      scopes: ["openid", "email", "profile"],
    },
    async ({ tokens, request }) => {
      return await getUser(tokens, request);
    }
  )
);

You can obtain a new set of tokens using a refresh token by calling the refreshToken method on your strategy instance. This is useful when an access token has expired.

let tokens = await strategy.refreshToken(refreshToken);
console.log(tokens.accessToken());

If your provider supports OpenID Connect (OIDC), you can use the static OAuth2Strategy.discover method. This method automatically fetches the configuration from the provider's .well-known/openid-configuration endpoint, so you don't have to manually specify endpoints like authorizationEndpoint or tokenEndpoint.

import { OAuth2Strategy } from "remix-auth-oauth2";

let strategy = await OAuth2Strategy.discover(
  "https://accounts.google.com",
  {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    redirectURI: "https://your-app.com/auth/callback",
    scopes: ["openid", "email", "profile"],
  },
  async ({ tokens }) => {
    return getUserProfile(tokens.access_token);
  },
);

If you have configured a tokenRevocationEndpoint in your strategy options, you can use the revokeToken method to invalidate an access token at the identity provider.

// Get it from where you stored it
let accessToken = await getAccessToken();
await strategy.revokeToken(tokens.access_token);