前端单点登录 SDK【sso-sdk】

使用说明

前端单点登录 SDK 基于 OAuth2.0 规范封装，该 SDK 用于前端项目快速对接研发中心统一登录中心 。使用该 SDK 时我们默认你已经掌握了 OAuth2.0 和 统一登录中心 ，若还不了解请先点击查阅。

适用范围

sso-sdk 采用原生 JS 封装，适用于所有的前端项目

安装

• yarn 安装

yarn add tsl-sso-sdk -S

• npm 安装

npm install tsl-sso-sdk --save

API

1. 检查授权状态

• 方法： checkAuthorized: (options: AuthOptions, type: "inject" | "redirect" = "inject") => Promise<string>
• AuthOptions 说明
  • client_id: string 应用 client_id
  • auth_uri?: string 授权地址，默认正式环境
  • response_type?: string auth2.0 的 response_type
  • state?: string auth2.0 的 state
• type 说明
  • type: "inject" | "redirect" 检查授权方式，默认值：inject （ 页面授权模式请指定值为：redirect ）
• 用法

import sso from "tsl-sso-sdk";
sso
  .checkAuthorized({
    client_id: ""
  })
  .then((code) => {
    // 已经授权成功
  })
  .catch(() => {
    // 未授权，如需获取code, 需先进行授权
  });

说明：checkAuthorized 方法的第二个参数需和选择的授权模式进行严格对应，及页面授权时 type=redirect，弹框授权时 type=inject

2. 页面授权

• 方法： login: (options: LoginOptions) => void
• LoginOptions 说明
  • client_id: string 应用 client_id
  • auth_uri?: string 授权地址，默认正式环境
  • response_type?: string auth2.0 的 response_type
  • state?: string auth2.0 的 state
  • redirect_uri?: string 授权后的回跳地址
• 用法

import sso from "tsl-sso-sdk";
sso
  .checkAuthorized({
    client_id: ""
  })
  .then((code) => {
    // 已经授权成功
  })
  .catch(() => {
    sso.login({
      client_id: ""
    });
  });

3. 弹框授权

• 方法： render: (container: HTMLElement | string, options: RenderOptions, attribute?: AttributeOptions) => Promise<string>
• container 说明
  • container: HTMLElement | string 需要渲染弹框窗口的容器元素
• RenderOptions 说明
  • client_id: string 应用 client_id
  • auth_uri?: string 授权地址，默认正式环境
  • redirect_uri?: string 授权后的回跳地址
• AttributeOptions 说明
  • fn: { remember: boolean; // 记住密码 phone: boolean; // 手机登录 forget_password: boolean; // 忘记密码 }; 功能配置，默认 false
  • theme: string | number // 主题 1-廖蓝(默认) 2-正旦青 3-靛蓝 内嵌主题
  • title: string // 标题 默认“账号密码登录”，要求长度1-20，必须由中英文、特殊字符_-&*%#()<>【】（）《》：…“”或空格组成，且不能只有空格，否则不生效
  • style: { themeColor: string; // 主题颜色（input框聚焦下边框、记住登录状态勾选框、"忘记密码"文字、主按钮背景色 mainTextColor: string; // 主文字颜色（标题、input框输入文字）panelBgColor: string; // 背景颜色 titlePosition: string; // 标题位置 left-左 center-中 right-右 mainBtnTextColor: string; // 主按钮文字颜色 mainBtnBorder: string; // 主按钮边框 mainBtnDisabledBgColor: string; // 主按钮禁用时背景色 subBtnBgColor: string; // 次按钮背景色 subBtnTextColor: string; // 次按钮文字颜色 subBtnBorder: string // 次按钮边框 }; 样式配置
• 用法

import sso from "tsl-sso-sdk";
sso
  .checkAuthorized({
    client_id: ""
  })
  .then((code) => {
    // 已经授权成功
  })
  .catch(() => {
    sso
      .render("ssoContainer", {
        client_id: ""
      })
      .then((code) => {
        // 授权成功
      })
      .catch((e) => {
        // 授权失败
      });
  });

说明：弹框授权有较多限制，请详细阅读以下事项

1. 协议：使用的授权目标地址必须为 https（请使用统一登录的域名地址进行授权）
2. 证书：因内网无证书，所以内网环境（开发、测试等环境）访问者需自行安装 CA 证书
3. 兼容：因弹框授权模式基于 iframe 机制进行开发，部分低版本浏览器并不支持，请确保项目的目标运行环境可控且为现代浏览器。

4. 退出登录

• 方法： logout: (options: LogoutOptions) => Promise<boolean>
• LogoutOptions 说明
  • token: string 授权成功后获取到的 token
  • auth_uri?: string 授权地址
• 用法

import sso from "tsl-sso-sdk";
sso
  .logout({
    token: ""
  })
  .then(() => {
    // 退出登录成功
  })
  .catch((e) => {
    // 退出登录失败
  });

--

vue 项目实例

1. 在全局路由守卫中进行授权

import store from "@/store";
import sso from "tsl-sso-sdk";
const loginGuard = (to, from, next, options) => {
  const isLogin = !!store.getters["account/user"];
  // 未登录
  if (!isLogin) {
    sso
      .checkAuthorized({
        client_id: ""
      })
      .then((code) => {
        // 1. 拿到code调用后端API换取token
        // 2. 获取到token后放入store中
        // 3. 最后调用 next() 进入页面
      })
      .catch(() => {
        sso.login({
          client_id: ""
        });
      });
  } else {
    next();
  }
};

高校机房完整案例

1. 和后端对接获取 client id 并在项目的环境配置文件中配置 VUE_APP_CLIENT_ID，且在统一用户中心对应的应用中将登录成功回跳地址（步骤 3 中会解释何为回跳地址）加入白名单

2. 安装 tsl-sso-sdk

3. 拷贝 node_modules/tsl-sso-sdk/sso.html 至 public 目录下

4. 在环境配置文件中配置

   VUE_APP_SSO_URL // 单点登录服务地址

   VUE_APP_SSO_REDIRECT_URL // 登录成功回跳地址，应为当前项目地址拼接/sso.html eg: http://{ip}:{port}/sso.html

5. 新建登录页并配置对应路由 /login

   const routes = [
     {
       path: "/login",
       components: () => import("../views/login")
     },
     {
       // ...
     }
   ];

6. 在 guards.js 文件中配置路由守卫

   import store from "@/store";
   import sso from "tsl-sso-sdk";
   const loginGuard = (to, from, next, options) => {
     const isLogin = !!store.getters["account/user"];
     // 未登录
     if (to.path !== "/login" && !isLogin) {
       sso
         .checkAuthorized({
           client_id: process.env.VUE_APP_CLIENT_ID, // 当前项目的client id
           auth_uri: process.env.VUE_APP_SSO_URL, // 单点登录服务地址
           redirect_uri: process.env.VUE_APP_SSO_REDIRECT_URL // 登录成功回跳地址
         })
         .then((code) => {
           dealCode(code); // 处理code: 取token, 存token, 进入应用页面等操作
         })
         .catch(() => {
           next("/login"); // 进入登录页, 渲染单点登录iframe进行登录操作
         });
     } else {
       next();
     }
   };

7. 进入登录页 src/views/login/index.vue mounted 时渲染单点登录 iframe

   import { defineComponent, reactive } from "vue";
   export default defineComponent {
       setup() {
           const attrOptions = reactive({ // 自定义单点登录功能和样式
               fn: {},
               theme: 1,
               style: {}
           });
           const authOptions = {
               client_id: "", // 当前项目的client id, 一般在环境配置文件中配置VUE_APP_CLIENT_ID
           	auth_uri: process.env.VUE_APP_SSO_URL, // 3中配置的单点登录地址
           	redirect_uri: process.env.VUE_APP_SSO_REDIRECT_URL // 3中配置的回跳地址
           }
           const renderSSO = () => {
               sso.render("ssoContainer", authOptions, attrOptions).then(code => dealCode(code)).catch()
           }
           onMounted(() => {
               renderSSO()
           })
       }
   }