Passport-GitHub 项目技术文档

1. 安装指南

安装依赖

要使用 passport-github，首先需要通过 npm 安装该模块：

$ npm install passport-github

2. 项目的使用说明

创建应用程序

在使用 passport-github 之前，您必须在 GitHub 上注册一个应用程序。如果您还没有注册，可以在 GitHub 的设置面板中创建一个新的应用程序。创建完成后，您将获得一个客户端 ID 和客户端密钥，这些信息需要提供给策略。此外，您还需要配置一个回调 URL，该 URL 应与应用程序中的路由匹配。

配置策略

GitHub 认证策略通过 GitHub 账户和 OAuth 2.0 令牌来认证用户。创建策略时，需要提供从 GitHub 获取的客户端 ID 和密钥。策略还需要一个 verify 回调函数，该函数接收访问令牌、可选的刷新令牌以及包含认证用户 GitHub 个人资料的 profile。verify 回调函数必须调用 cb 并提供一个用户以完成认证。

var GitHubStrategy = require('passport-github').Strategy;

passport.use(new GitHubStrategy({
    clientID: GITHUB_CLIENT_ID,
    clientSecret: GITHUB_CLIENT_SECRET,
    callbackURL: "http://127.0.0.1:3000/auth/github/callback"
  },
  function(accessToken, refreshToken, profile, cb) {
    User.findOrCreate({ githubId: profile.id }, function (err, user) {
      return cb(err, user);
    });
  }
));

企业版 GitHub

如果您使用的是企业版的 GitHub，您需要传递三个额外的参数：authorizationURL、tokenURL 和 userProfileURL。

var GitHubStrategy = require('passport-github').Strategy;

passport.use(new GitHubStrategy({
    clientID: GITHUB_CLIENT_ID,
    clientSecret: GITHUB_CLIENT_SECRET,
    authorizationURL: "https://ENTERPRISE_INSTANCE_URL/login/oauth/authorize",
    tokenURL: "https://ENTERPRISE_INSTANCE_URL/login/oauth/access_token",
    userProfileURL: "https://ENTERPRISE_INSTANCE_URL/api/v3/user",
    callbackURL: "http://127.0.0.1:3000/auth/github/callback"
  },
  function(accessToken, refreshToken, profile, cb) {
    User.findOrCreate({ githubId: profile.id }, function (err, user) {
      return cb(err, user);
    });
  }
));

认证请求

使用 passport.authenticate() 并指定 'github' 策略来认证请求。例如，在 Express 应用程序中作为路由中间件：

app.get('/auth/github',
  passport.authenticate('github'));

app.get('/auth/github/callback', 
  passport.authenticate('github', { failureRedirect: '/login' }),
  function(req, res) {
    // 认证成功，重定向到首页
    res.redirect('/');
  });

3. 项目API使用文档

GitHubStrategy 构造函数

GitHubStrategy 构造函数用于创建一个新的 GitHub 认证策略。它接受以下参数：

• clientID: GitHub 应用程序的客户端 ID。
• clientSecret: GitHub 应用程序的客户端密钥。
• callbackURL: 认证成功后的回调 URL。
• authorizationURL (可选): 企业版 GitHub 的授权 URL。
• tokenURL (可选): 企业版 GitHub 的令牌 URL。
• userProfileURL (可选): 企业版 GitHub 的用户个人资料 URL。

verify 回调函数

verify 回调函数用于处理认证成功后的逻辑。它接收以下参数：

• accessToken: 访问令牌。
• refreshToken: 刷新令牌（可选）。
• profile: 包含用户 GitHub 个人资料的对象。
• cb: 回调函数，用于返回用户对象或错误。

4. 项目安装方式

通过 npm 安装 passport-github 模块：

$ npm install passport-github

安装完成后，您可以在项目中引入并使用该模块进行 GitHub 认证。