Remix 的简单身份验证

npm install remix-auth

Remix Auth

为 Remix 和 React Router 应用提供的简单身份验证。

特性

完整的服务器端身份验证
完整的 TypeScript 支持
基于策略的身份验证
实现自定义策略

概述

Remix Auth 是一个完整的开源身份验证解决方案，适用于 Remix 和 React Router 应用程序。

它深受 Passport.js 的启发，但完全从头开始重写，以便在 Web Fetch API 之上工作。Remix Auth 可以以最小的设置添加到任何基于 Remix 或 React Router 的应用程序中。

与 Passport.js 一样，它使用策略模式来支持不同的身份验证流程。每个策略都作为单独的 npm 包单独发布。

安装

要使用它，请从 npm（或 yarn）安装它

npm install remix-auth

此外，安装一个策略。策略列表可在社区策略讨论中找到。

[!TIP] 查看策略支持的 Remix Auth 版本，因为它们可能未更新到最新版本。

用法

导入 Authenticator 类，并使用一个泛型类型进行实例化，该泛型类型将是您从策略中获取的用户数据类型。

// Create an instance of the authenticator, pass a generic with what
// strategies will return
export let authenticator = new Authenticator<User>();

User 类型是您的策略在识别经过身份验证的用户后将为您提供的任何类型。它可以是完整的用户数据，也可以是带有令牌的字符串。这完全取决于您。

之后，注册策略。在此示例中，我们将使用 FormStrategy 来查看您要使用的策略的文档，以查看您可能需要的任何配置。

import { FormStrategy } from "remix-auth-form";

// Tell the Authenticator to use the form strategy
authenticator.use(
  new FormStrategy(async ({ form }) => {
    let email = form.get("email");
    let password = form.get("password");
    // the type of this user must match the type you pass to the Authenticator
    // the strategy will automatically inherit the type if you instantiate
    // directly inside the `use` method
    return await login(email, password);
  }),
  // each strategy has a name and can be changed to use another one
  // same strategy multiple times, especially useful for the OAuth2 strategy.
  "user-pass"
);

一旦我们至少注册了一个策略，就该设置路由了。

首先，创建一个 /login 页面。在这里，我们将呈现一个表单以获取用户的电子邮件和密码，并使用 Remix Auth 来验证用户身份。

import { Form } from "react-router";
import { authenticator } from "~/services/auth.server";

// Import this from correct place for your route
import type { Route } from "./+types";

// First we create our UI with the form doing a POST and the inputs with the
// names we are going to use in the strategy
export default function Screen() {
  return (
    <Form method="post">
      <input type="email" name="email" required />
      <input
        type="password"
        name="password"
        autoComplete="current-password"
        required
      />
      <button>Sign In</button>
    </Form>
  );
}

// Second, we need to export an action function, here we will use the
// `authenticator.authenticate method`
export async function action({ request }: Route.ActionArgs) {
  // we call the method with the name of the strategy we want to use and the
  // request object
  let user = await authenticator.authenticate("user-pass", request);

  let session = await sessionStorage.getSession(request.headers.get("cookie"));
  session.set("user", user);

  throw redirect("/", {
    headers: { "Set-Cookie": await sessionStorage.commitSession(session) },
  });
}

// Finally, we need to export a loader function to check if the user is already
// authenticated and redirect them to the dashboard
export async function loader({ request }: Route.LoaderArgs) {
  let session = await sessionStorage.getSession(request.headers.get("cookie"));
  let user = session.get("user");
  if (user) throw redirect("/dashboard");
  return data(null);
}

sessionStorage 可以使用 React Router 的会话存储助手创建，您可以决定要使用哪种会话存储机制，或者您计划如何在身份验证后保留用户数据，也许您只需要一个普通的 cookie。

高级用法

根据用户数据将用户重定向到不同的路由

假设我们有 /dashboard 和 /onboarding 路由，并且在用户进行身份验证后，您需要检查他们数据中的某些值，以了解他们是否已加入。

export async function action({ request }: Route.ActionArgs) {
  let user = await authenticator.authenticate("user-pass", request);

  let session = await sessionStorage.getSession(request.headers.get("cookie"));
  session.set("user", user);

  // commit the session
  let headers = new Headers({ "Set-Cookie": await commitSession(session) });

  // and do your validation to know where to redirect the user
  if (isOnboarded(user)) return redirect("/dashboard", { headers });
  return redirect("/onboarding", { headers });
}

处理错误

如果发生错误，身份验证器和策略将直接抛出错误。您可以捕获它并根据需要进行处理。

export async function action({ request }: Route.ActionArgs) {
  try {
    return await authenticator.authenticate("user-pass", request);
  } catch (error) {
    if (error instanceof Error) {
      // here the error related to the authentication process
    }

    throw error; // Re-throw other values or unhandled errors
  }
}

[!TIP] 一些策略可能会抛出重定向响应，这在 OAuth2/OIDC 流程中很常见，因为它们需要将用户重定向到身份提供程序，然后再重定向回应用程序，请确保重新抛出任何非已处理的错误。在 catch 块的开头使用 if (error instanceof Response) throw error; 来首先重新抛出任何响应，以防您想以不同的方式处理它。

注销用户

由于您负责在登录后保留用户数据，因此如何处理注销将取决于此。您可以简单地从会话中删除用户数据，也可以创建新的会话，甚至可以使会话无效。

export async function action({ request }: Route.ActionArgs) {
  let session = await sessionStorage.getSession(request.headers.get("cookie"));
  return redirect("/login", {
    headers: { "Set-Cookie": await sessionStorage.destroySession(session) },
  });
}

保护路由

要保护路由，您可以使用 loader 函数来检查用户是否已通过身份验证。如果未通过身份验证，您可以将他们重定向到登录页面。

export async function loader({ request }: Route.LoaderArgs) {
  let session = await sessionStorage.getSession(request.headers.get("cookie"));
  let user = session.get("user");
  if (!user) throw redirect("/login");
  return null;
}

这超出了 Remix Auth 的范围，因为用户数据的存储位置取决于您的应用程序。

一个简单的方法是创建一个 authenticate 助手。

export async function authenticate(request: Request, returnTo?: string) {
  let session = await sessionStorage.getSession(request.headers.get("cookie"));
  let user = session.get("user");
  if (user) return user;
  if (returnTo) session.set("returnTo", returnTo);
  throw redirect("/login", {
    headers: { "Set-Cookie": await sessionStorage.commitSession(session) },
  });
}

然后在您的加载器和操作中调用它

export async function loader({ request }: Route.LoaderArgs) {
  let user = await authenticate(request, "/dashboard");
  // use the user data here
}

创建策略

所有策略都扩展了 Remix Auth 导出的 Strategy 抽象类。您可以通过扩展此类并实现 authenticate 方法来创建自己的策略。

import { Strategy } from "remix-auth/strategy";

export namespace MyStrategy {
  export interface VerifyOptions {
    // The values you will pass to the verify function
  }
}

export class MyStrategy<User> extends Strategy<User, MyStrategy.VerifyOptions> {
  name = "my-strategy";

  async authenticate(
    request: Request,
    options: Strategy.AuthenticateOptions
  ): Promise<User> {
    // Your logic here
  }
}

在您的 authenticate 方法的某个时刻，您需要调用 this.verify(options) 来调用应用程序定义的 verify 函数。

export class MyStrategy<User> extends Strategy<User, MyStrategy.VerifyOptions> {
  name = "my-strategy";

  async authenticate(
    request: Request,
    options: Strategy.AuthenticateOptions
  ): Promise<User> {
    return await this.verify({
      /* your options here */
    });
  }
}

这些选项将取决于您传递给 Strategy 类的第二个泛型。

您要传递给 verify 方法的内容取决于您和您的身份验证流程的需求。

存储中间状态

如果您的策略需要存储中间状态，您可以使用覆盖 contructor 方法来期望一个 Cookie 对象，甚至是一个 SessionStorage 对象。

import { SetCookie } from "@mjackson/headers";

export class MyStrategy<User> extends Strategy<User, MyStrategy.VerifyOptions> {
  name = "my-strategy";

  constructor(
    protected cookieName: string,
    verify: Strategy.VerifyFunction<User, MyStrategy.VerifyOptions>
  ) {
    super(verify);
  }

  async authenticate(
    request: Request,
    options: Strategy.AuthenticateOptions
  ): Promise<User> {
    let header = new SetCookie({
      name: this.cookieName,
      value: "some value",
      // more options
    });
    // More code
  }
}

header.toString() 的结果将是一个字符串，您必须使用 Set-Cookie 标头将其发送到浏览器，这可以通过抛出带有标头的重定向来完成。

export class MyStrategy<User> extends Strategy<User, MyStrategy.VerifyOptions> {
  name = "my-strategy";

  constructor(
    protected cookieName: string,
    verify: Strategy.VerifyFunction<User, MyStrategy.VerifyOptions>
  ) {
    super(verify);
  }

  async authenticate(
    request: Request,
    options: Strategy.AuthenticateOptions
  ): Promise<User> {
    let header = new SetCookie({
      name: this.cookieName,
      value: "some value",
      // more options
    });
    throw redirect("/some-route", {
      headers: { "Set-Cookie": header.toString() },
    });
  }
}

然后，您可以使用 @mjackson/headers 包中的 Cookie 对象在下一个请求中读取该值。

import { Cookie } from "@mjackson/headers";

export class MyStrategy<User> extends Strategy<User, MyStrategy.VerifyOptions> {
  name = "my-strategy";

  constructor(
    protected cookieName: string,
    verify: Strategy.VerifyFunction<User, MyStrategy.VerifyOptions>
  ) {
    super(verify);
  }

  async authenticate(
    request: Request,
    options: Strategy.AuthenticateOptions
  ): Promise<User> {
    let cookie = new Cookie(request.headers.get("cookie") ?? "");
    let value = cookie.get(this.cookieName);
    // More code
  }
}

许可证

请参阅LICENSE。

作者

Sergio Xalambrí