ustb_sso 1.1.0

USTB Single Sign-On Authentication Library (Dart)

USTB-SSO (Dart)

USTB Single Sign-On Authentication Library (Dart)
北京科技大学单点登录（SSO）身份认证实现库（Dart）

This module is the Dart implementation of USTB-SSO.
此模块是 USTB-SSO 项目的 Dart 实现。

^{This project only supports Chinese docs. If you are an English user, feel free to contact us.}

介绍 _Intro

特点： 简单易用；自文档化；依赖最少原则；全面的错误反馈。

实现的功能

• 发起认证：
  支持向北科大 SSO 服务器发起针对指定应用的身份认证请求；
• 进行认证：
  支持使用微信二维码或短信验证码来完成身份认证；
• 完成认证：
  支持在认证成功后，获取已被认证的客户端实例或 Cookie 实例。

使用方法 _Usage

安装

使用 Dart 的包管理工具 pub 来安装：

dart pub add ustb_sso

前置知识

要想实现通过 SSO 来北科大的某个指定的应用，需要先准备 3 个参数：

1. 该应用的实体编号（entity_id）；
2. 该应用的认证终点 URL（redirect_uri）；
3. 该应用的内部状态名（state）。

我们已经在 ustb_sso.prefabs 中以常量的形式存储了部分已知应用的参数。如果您需要接入其他应用，请自行在网页中抓取 https://sso.ustb.edu.cn/idp/authCenter/authenticate 这个请求的请求参数来获得。

示例：微信扫码登录

以下代码演示了如何通过通过微信扫码登录来获取北科大 AI 助手（2025 年版）的令牌 Cookie。

import 'dart:io';
import 'package:ustb_sso/ustb_sso.dart';

void main() async {
  final session = HttpSession();
  final auth = QrAuthProcedure(  // ※
    entityId: Prefabs.chatUstbEduCn.entityId,
    redirectUri: Prefabs.chatUstbEduCn.redirectUri,
    state: Prefabs.chatUstbEduCn.state,
    session: session,
  );

  print('Starting authentication...');
  await auth.openAuth();
  
  await auth.useWechatAuth();
  await auth.useQrCode();

  final qrImageBytes = await auth.getQrImage();  // ▲
  await File('qr.png').writeAsBytes(qrImageBytes);

  print('Waiting for confirmation... Please scan the QR code');
  final passCode = await auth.waitForPassCode();

  print('Validating...');
  final rsp = await auth.completeQrAuth(passCode);

  print('Response status: ${rsp.statusCode}');
  const cookieName = 'cookie_vjuid_login';
  print('Cookie: $cookieName = ${session.cookies.get(cookieName)}');
}

当代码运行到 ▲ 位置时，您需要使用微信来扫描文件夹中生成的 qr.png 图片中的二维码，并在微信上确认登录。

代码的 ※ 位置使用的 Prefabs.chatUstbEduCn 就是我们的库所提供的预设应用参数，以便开发者快捷调用。有关其他的预设应用参数，请参见此文件。

session 是一个 HttpSession 实例（类似于 Python 的 requests.Session），用于存储 Cookie 等客户端数据。后续如果需要使用 Cookie 令牌去做其他的 API 请求，可以直接调用 session 的相关方法。

示例：短信验证码登录

如果没有微信扫码的条件，则可以使用短信验证码进行登录。以下是使用短信验证码进行登录的示例。

import 'dart:io';
import 'package:ustb_sso/ustb_sso.dart';

void main() async {
  final session = HttpSession();
  final auth = SmsAuthProcedure(
    entityId: Prefabs.chatUstbEduCn.entityId,
    redirectUri: Prefabs.chatUstbEduCn.redirectUri,
    state: Prefabs.chatUstbEduCn.state,
    session: session,
  );

  print('Starting authentication...');
  await auth.openAuth();
  await auth.checkSmsAvailable();

  stdout.write('Please enter your phone number: ');
  final phoneNumber = stdin.readLineSync()!;
  await auth.sendSms(phoneNumber);

  stdout.write('Please enter the SMS code: ');
  final smsCode = stdin.readLineSync()!;
  final token = await auth.submitSmsCode(phoneNumber, smsCode);

  print('Validating...');
  final rsp = await auth.completeSmsAuth(token);

  print('Response status: ${rsp.statusCode}');
  const cookieName = 'cookie_vjuid_login';
  print('Cookie: $cookieName = ${session.cookies.get(cookieName)}');
}

开发指南 _{Dev Guide}

如果您想对 USTB-SSO (Dart) 进行开发，以下指引可能有所帮助。

开始开发

1. 安装 Dart SDK >= 3.9.0；
2. 克隆仓库到本地；
3. 安装所有依赖项：

   dart pub get
   

测试

1. 运行测试代码：

   dart test
   

2. 运行示例代码：

   dart run example/demo.dart
   

3. 分析代码质量：

   dart analyze
   

4. 格式化代码：

   dart format .
   

许可证 _Licensing

本项目基于 MIT 开源许可证，详情参见 License 页面。