GitHubStrategy

一个用于 GitHub 应用和 OAuth 应用的 Remix Auth 策略

支持的运行时

运行时	支持
Node.js	✅
Cloudflare	✅

如何使用

安装

npm add remix-auth remix-auth-github

创建一个 OAuth 应用程序

按照 GitHub 文档中的步骤创建一个新的应用程序并获取客户端 ID 和密钥。

用法

你可以通过将其添加到你的身份验证器实例并配置正确的端点来使用此策略。

export let authenticator = new Authenticator<User>();

authenticator.use(
  new GitHubStrategy(
    {
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      redirectURI: "https://example.app/auth/callback",
      scopes: ["user:email"], // optional
    },
    async ({ tokens, request }) => {
      // here you can use the params above to get the user and return it
      // what you do inside this and how you find the user is up to you
      return await getUser(tokens, request);
    }
  ),
  // this is optional, but if you setup more than one GitHub instance you will
  // need to set a custom name to each one, by default is "github"
  "provider-name"
);

然后你需要设置你的路由，对于 OAuth2 流程，你需要调用 authenticate 方法两次。

首先，你将使用你在身份验证器中设置的提供程序名称调用 authenticate 方法。

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

[!NOTE] 此路由可以是 action 或 loader，这取决于你是通过 POST 还是 GET 请求触发流程。

这将启动 OAuth2 流程并将用户重定向到提供商的登录页面。一旦用户登录并授权你的应用程序，提供商会将用户重定向回你的应用程序重定向 URI。

你现在需要在该 URI 上设置一个路由来处理来自提供商的回调。

export async function loader({ request }: Route.LoaderArgs) {
  let user = await authenticator.authenticate("provider-name", request);
  // now you have the user object with the data you returned in the verify function
}

[!NOTE] 此路由必须是 loader，因为重定向将触发一个 GET 请求。

一旦你获得了策略验证函数返回的 user 对象，你就可以使用该信息做任何你想做的事情。这可以是将会话中的用户存储，在数据库中创建一个新用户，将帐户链接到数据库中的现有用户等。

使用刷新令牌

该策略公开了一个 refreshToken 方法，你可以使用它来刷新访问令牌。

let strategy = new GitHubStrategy<User>(options, verify);
let tokens = await strategy.refreshToken(refreshToken);

刷新令牌是验证函数接收的 tokens 对象的一部分。如何存储它来调用 strategy.refreshToken 以及刷新后如何处理 tokens 对象取决于你。

最常见的方法是将刷新令牌存储在用户数据中，然后在刷新令牌后更新会话。

authenticator.use(
  new GitHubStrategy<User>(
    options,
    async ({ tokens, request }) => {
      let user = await getUser(tokens, request);
      return {
        ...user,
        accessToken: tokens.accessToken()
        refreshToken: tokens.hasRefreshToken() ? tokens.refreshToken() : null,
      }
    }
  )
);

// later in your code you can use it to get new tokens object
let tokens = await strategy.refreshToken(user.refreshToken);

获取用户资料

一旦你有了 OAuth2 令牌对象，你可以使用访问令牌从 GitHub API 获取用户资料。

let response = await fetch("https://api.github.com/user", {
  headers: {
    Accept: "application/vnd.github+json",
    Authorization: `Bearer ${tokens.accessToken()}`,
    "X-GitHub-Api-Version": "2022-11-28",
  },
});

let user = await response.json();

// Somehow parse the user object to ensure it has the correct shape

获取用户电子邮件

同样，你可以使用访问令牌从 GitHub API 获取用户的电子邮件。

[!IMPORTANT] 在验证用户时，你需要请求 user:email 范围。

let response = await fetch("https://api.github.com/user/emails", {
  headers: {
    Accept: "application/vnd.github+json",
    Authorization: `Bearer ${tokens.accessToken()}`,
    "X-GitHub-Api-Version": "2022-11-28",
  },
});

let emails = await response.json();

// Somehow parse the emails object to ensure it has the correct shape