tsl-sso-sdk

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

$3

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

$3

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

$3

- yarn 安装

yarn add tsl-sso-sdk -S

- npm 安装

npm install tsl-sso-sdk --save

$3

#### 1. 检查授权状态

- 方法： checkAuthorized: (options: AuthOptions, type: "inject" | "redirect" = "inject") => Promise
- 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 ）
- 用法

``js
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 授权后的回跳地址
- 用法

`js
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
- 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 // 次按钮边框 }; 样式配置
- 用法

`js
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
- LogoutOptions 说明
- token: string 授权成功后获取到的 token
- auth_uri?: string 授权地址
- 用法

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

--

> vue 项目实例

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

`js
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

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

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

`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

`js
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()
})
}
}
``