<commit_before>title: Passport
---

**『登录鉴权』** 是一个常见的业务场景，包括『账号密码登录方式』和『第三方统一登录』。

其中，后者我们经常使用到，如 Google， GitHub，QQ 统一登录，它们都是基于 [OAuth](https://oauth.net/2/) 规范。

[Passport] 是一个扩展性很强的认证中间件，支持 `Github`，`Twitter`，`Facebook` 等知名服务厂商的 `Strategy`，同时也支持通过账号密码的方式进行登录授权校验。

Egg 在它之上提供了 [egg-passport] 插件，把初始化、鉴权成功后的回调处理等通用逻辑封装掉，使得开发者仅需调用几个 API 即可方便的使用 Passport 。

[Passport] 的执行时序如下：
- 用户访问页面
- 检查 Session
- 拦截跳鉴权登录页面
- Strategy 鉴权
- 校验和存储用户信息
- 序列化用户信息到 Session
- 跳转到指定页面

## 使用 egg-passport

下面，我们将以 GitHub 登录为例，来演示下如何使用。

### 安装

```bash
$ npm i --save egg-passport
$ npm i --save egg-passport-github
```

更多插件参见 [GitHub Topic - egg-passport](https://github.com/topics/egg-passport) 。

### 配置

**开启插件：**

```js
// config/plugin.js
exports.passport = {
  enable: true,
  package: 'egg-passport',
};

exports.passportGithub = {
  enable: true,
  package: 'egg-passport-github',
};
```

**配置:**

注意：[egg-passport] 标准化了配置字段，统一为 `key` 和 `secret` 。

```js
// config/default.js
config.passportGithub = {
  key: 'your_clientID',
  secret: 'your_clientSecret'
};
```

**注意：**
- 创建一个 [GitHub OAuth Apps](https://github.com/settings/applications/new)，得到 `clientID` 和 `clientSecret` 信息。
- 填写 `callbackURL`，如 `http://127.0.0.1:7001/passport/github/callback`
  - 线上部署时需要更新为对应的域名
  - 路径为配置的 `options.callbackURL`，默认为 `/passport/${strategy}/callback`

### 挂载路由

```js
// app/router.js
module.exports = app => {
  const { router, controller } = app;

  // 挂载鉴权路由
  app.passport.mount('github');
<commit_msg>docs(passport): config passport-github behind of proxy (#2318)<commit_after>title: Passport
---

**『登录鉴权』** 是一个常见的业务场景，包括『账号密码登录方式』和『第三方统一登录』。

其中，后者我们经常使用到，如 Google， GitHub，QQ 统一登录，它们都是基于 [OAuth](https://oauth.net/2/) 规范。

[Passport] 是一个扩展性很强的认证中间件，支持 `Github`，`Twitter`，`Facebook` 等知名服务厂商的 `Strategy`，同时也支持通过账号密码的方式进行登录授权校验。

Egg 在它之上提供了 [egg-passport] 插件，把初始化、鉴权成功后的回调处理等通用逻辑封装掉，使得开发者仅需调用几个 API 即可方便的使用 Passport 。

[Passport] 的执行时序如下：
- 用户访问页面
- 检查 Session
- 拦截跳鉴权登录页面
- Strategy 鉴权
- 校验和存储用户信息
- 序列化用户信息到 Session
- 跳转到指定页面

## 使用 egg-passport

下面，我们将以 GitHub 登录为例，来演示下如何使用。

### 安装

```bash
$ npm i --save egg-passport
$ npm i --save egg-passport-github
```

更多插件参见 [GitHub Topic - egg-passport](https://github.com/topics/egg-passport) 。

### 配置

**开启插件：**

```js
// config/plugin.js
exports.passport = {
  enable: true,
  package: 'egg-passport',
};

exports.passportGithub = {
  enable: true,
  package: 'egg-passport-github',
};
```

**配置:**

注意：[egg-passport] 标准化了配置字段，统一为 `key` 和 `secret` 。

```js
// config/default.js
config.passportGithub = {
  key: 'your_clientID',
  secret: 'your_clientSecret',
  // callbackURL: '/passport/github/callback',
  // proxy: false,
};
```

**注意：**
- 创建一个 [GitHub OAuth Apps](https://github.com/settings/applications/new)，得到 `clientID` 和 `clientSecret` 信息。
- 填写 `callbackURL`，如 `http://127.0.0.1:7001/passport/github/callback`
  - 线上部署时需要更新为对应的域名
  - 路径为配置的 `options.callbackURL`，默认为 `/passport/${strategy}/callback`
- 如应用部署在 Nginx/HAProxy 之后，需设置插件 `proxy` 选项为 `true`, 并检查以下配置：
  - 代理附加 HTTP 头字段：`x-forwarded-proto` 与 `x-forwarded-host`
  - 配置中 `config.proxy` 应设置为 `true`

### 挂载路由

```js
// app/router.js
module.exports = app => {
  const { router, controller } = app;

  // 挂载鉴权路由
  app.passport.mount('github');

{'fraction_non_alphanumeric': 0.1788467468393463, 'fraction_numerical': 0.008017267961763799, 'mean_word_length': 4.397670549084858, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5614769', 'n_tokens_mistral': 1800, 'n_tokens_neox': 1924, 'n_words': 246}