HUST 统一身份认证系统 模拟登录

提供对 统一身份认证系统(CAS) 的模拟登录（支持验证码识别）。可以调用提供的函数获取登录信息。

Tip	可以摘出来一部分代码作为参考或直接使用，也可以按照下文的方法集成入你的 Node.js 程序。

一个简单的示例

仓库根目录下的 sample.js 是一个简单的示例文件，它简单展示了怎样使用相关的函数。

在文件中填写可用的用户名和密码及其它参数之后，就可以像下面这样运行：

npm install
node sample.js

Tip	具体函数请参考下文 “可以导入的函数” 部分。

集成入你的 Node.js 程序

这里假设你的程序位于 index.js ：

node index.js

第一步：把本仓库集成进你的项目目录中

首先，需要把本仓库的文件放置到任一子目录中（这里假设要放置到 toolkit 子目录中）。

• 可以直接将本仓库的文件复制入 toolkit 目录；

• 也可使用 Git Submodule 功能在你的项目中把本仓库添加为子模块，使之位于 toolkit 目录下：

  $ git submodule add https://github.com/xuxinhang/HUST-CAS-login-emulator.git toolkit
  $ git submodule update --remote
  $ cd toolkit
  $ npm install
  $ cd ..

你可以任选一种方法。现在你的目录结构应该类似下面的样子：

+ your-project
|-  package.json
|-  index.js
|-  其它你自己的文件或目录...
|+  toolkit
  |-   package.json
  |-   node_modules
  |-   其它来自本仓库的文件...

第二步：导入相关的函数

在 index.js 中，可以从 toolkit 目录导入相关的函数

const { emulateLogin, dispatchRequest, /* or more */ } = require('./toolkit');

函数参考

emulateLogin(options)

使用 options 作为参数来模拟CAS登录过程，并返回登录认证信息。

options <Object> 登录时使用的参数

具体可以接受的 key 如下

{
  username: '',   // <string> CAS 登录用户名
  password: '',   // <string> CAS 登录密码
  serviceURL: '', // <string> 服务跳转地址
}

username 和 password 是你在登录页要填入的用户名和密码。

服务跳转地址是登录页URL的查询字符串中的 service 项所对应的URL。例如，如果登录页的URL为

https://pass.hust.edu.cn/cas/login?service=http%3A%2F%2Fone.hust.edu.cn%2Fdcp%2Findex.jsp

那么 serviceURL 为

http://one.hust.edu.cn/dcp/index.jsp

你就可以使用这个URL作为字符串传入 emulateLogin 了。

Note	请一定要根据你想访问的服务所对应的实际的登录页的URL来确定 serviceURL，任意的或者你想当然以为的 serviceURL 可能会导致无法正常登录。

返回值 <Promise>

resolve 时返回一个 <Object> 内含相关的登录身份认证信息：

{
  serviceAuthCookies: {
    JSESSIONID: '...',
    // ... ...
    // 用于身份验证的 cookie
  },
}

接下来，你就可以利用这些信息来请求对应的服务的页面或者接口了。

Note	一般来说，使用某一服务的 serviceURL 进行模拟登录得到的身份认证信息只能用于属于该服务的接口。

Tip	请参考上文“一个简单的示例”来了解怎样执行一次模拟登录，并使用返回的登录信息。

recognizeCaptcha(image)

根据传入的验证码图片识别出字符。

image <Buffer>

二进制形式的验证码图片内容

返回值 <Promise>

resolve 时返回由识别出的字符组成的数组

Note	CAS使用的验证码机制可能会在未来更改

dispatchRequest(options)

根据传入的选项对象发送网络请求。

options <Object> 请求选项

{
  method: 'GET', // <string> HTTP Method
  url: '',       // <string> 目标 URL
  cookies: {},   // <Object> 以 Key-Value 给出的 Cookie
  headers: {},   // <Object> 以 Key-Value 给出的自定义 HTTP 头
  payload: '',   // <string> 请求体
}

返回值 <Promise>

resolve 时返回一个对象，包含本次请求的状态、返回内容、 Cookie 等。

{
  resp: ,         // <http.IncomingMessage> Node.js HTTP 模块的响应对象
  headers: {},    // HTTP 响应头 (直接取自 resp.headers)
  payload: '',    // HTTP 响应体
  setCookies: {}, // Set-Cookie 头，经解析后以 Key-Value 形式给出
}

简单的示例

发送带自定义头与 Cookie 的 POST 请求

const { headers: responseHeaders } = await dispatchRequest({
  method: 'POST',
  url: formAction,
  cookies: {
    'Language': 'zh_CN',
    'MY_COOKIE': 'The quick brown fox jumps over the lazy dog',
  },
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  payload: '...',
});

发送带 Cookie 的 GET 请求

const { payload } = await dispatchRequest({
  url: 'http://g.cn',
  cookies: {
    'MY_COOKIE': 'The quick brown fox jumps over the lazy dog',
  },
});