> For the complete documentation index, see [llms.txt](https://authing.gitbook.io/authing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://authing.gitbook.io/authing/sdk/sdk-for-sso.md).
# SDK for 单点登录
## 安装
### 通过 NPM 安装
```
$ npm install @authing/sso --save
```
接着可以通过以下方式使用
```
import AuthingSSO from "@authing/sso";
```
### 通过 CDN 安装
```
```
## 开始使用
需要先注册一个 [Authing](https://authing.cn/login) 账号，并[创建一个 OIDC 应用](/authing/authentication/oidc/create-oidc.md)。
### 发起登录
#### **跳转登录**
```
import AuthingSSO from "@authing/sso";
let auth = new AuthingSSO({
appId: "SSO_APP_ID",
appType: "可填：oauth/oidc/saml", // 默认 oidc
appDomain: "SSO_APP_DOMAIN"
});
// 发起单点登录，会跳转到登录页面，采用授权码模式，需要相关应用开启授权码模式
auth.login();
```
#### **窗口登录**
```
import AuthingSSO from "@authing/sso";
let auth = new AuthingSSO({
appId: "SSO_APP_ID",
appType: "可填：oauth/oidc/saml", // 默认 oidc
appDomain: "SSO_APP_DOMAIN"
});
// 发起单点登录，会弹出一个窗口，里面是登录页面，采用授权码模式，需要相关应用开启授权码模式
auth.windowLogin();
```
业务域名回调地址需要托管一个 html 文件，用于将得到的 code access\_token id\_token 等参数，通过 postMessage 的方式发送给父窗口，然后将本窗口关闭。
例如，回调地址填写的是 [https://example.com/handle.html](https://example.com/handle.html%EF%BC%8C%E8%BF%99%E4%B8%AA)，这个 html 内部需要编写一段发送 postMessage 的代码，负责从 url 中取出相关参数并传递给父窗口。
Github 参考代码：
### 查询登录状态
```
let res = await auth.trackSession();
/**
* {
* session: { appId: 'xxx', type: 'oidc/oauth/saml', userId: 'yyy'},
* userInfo: {
* "_id": "USER_ID",
* "email": "USER_EMAIL",
* "registerInClient": "CLIENT_ID",
* "token": "JTW_TOKEN",
* "tokenExpiredAt": "2019-10-28 10:15:32",
* "photo": "PICTURE",
* "company": "",
* "nickname": "NICKNAME",
* "username": "USERNAME",
* },
* urlParams: {
* code: 'xxx', // 这些参数是从 url 中获取到的，需要开发者自己存储以备使用
* id_token: 'ID_TOKEN',
* access_token: 'ACCESS_TOKEN'
* }
* }
*
* 如果 session 不存在，返回：
*
* {
* session: null
* }
* */
```
### 登出
```
let res = await auth.logout();
/**
* {
* message: "单点登出成功",
* code: 200
* }
* */
```
## API
### AuthingSSO.prototype.constructor
构造函数，接受一个对象作为参数。对象中的参数列表如下：
| 参数名 | 是否必填 | 描述 | 默认 |
| ------------ | ---- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| appId | 是 | SSO 应用的 ID | - |
| appDomain | 是 | SSO 应用域名，例如 `app1.authing.cn` | - |
| appType | 否 | SSO 应用的 类型，可选值为 `oidc`，`oauth`，`saml` | `oidc` |
| scope | 否 | SSO 授权域 | 'openid profile email phone'，查看[支持的 scope](https://docs.authing.cn/authing/advanced/oidc/oidc-params#scope-can-shu-dui-ying-de-yong-hu-xin-xi) |
| state | 否 | 自定义字符串，回调地址也会受到此参数，内容相同，可用于传递信息 | 随机字符串 |
| host | 否 | 一个对象，用于指定 GraphQL 地址 | {
oauth: '' }
|
| host.oauth | 否 | GraphQL 通信地址 | |
| responseType | 否 | SSO 应用授权流程，可选值为 `code`，`implicit` | `code` |
| redirectUrl | 否 | SSO 应用回调域名 | 在 Authing 控制台配置的第一个业务域名 |
| nonce | 否 | 随机数 | 随机数 |
| timestamp | 否 | 时间戳 | 当前时间戳 |
示例
```
let auth = new AuthingSSO({
appId: "SSO_APP_ID",
appType: "oidc",
appDomain: "SSO_APP_DOMAIN"
});
```
### AuthingSSO.prototype.login
示例
```
auth.login();
```
### AuthingSSO.prototype.trackSession
示例
```
let res = await auth.trackSession();
/**
* {
* session: { appId: 'xxx', type: 'oidc/oauth/saml', userId: 'yyy'},
* userInfo: {
* "_id": "USER_ID",
* "email": "USER_EMAIL",
* "registerInClient": "CLIENT_ID",
* "token": "JTW_TOKEN",
* "tokenExpiredAt": "2019-10-28 10:15:32",
* "photo": "PICTURE",
* "company": "",
* "nickname": "NICKNAME",
* "username": "USERNAME",
* },
* urlParams: {
* code: 'xxx', // 这些参数是从 url 中获取到的，需要开发者自己存储以备使用
* id_token: 'ID_TOKEN',
* access_token: 'ACCESS_TOKEN'
* }
* }
*
* 如果 session 不存在，返回：
*
* {
* session: null
* }
* */
```
### AuthingSSO.prototype.logout
示例
```
let res = await auth.logout();
/**
* {
* message: "单点登出成功",
* code: 200
* }
* */
```
## 获取帮助
1. Join us on Gitter: [#authing-chat](https://gitter.im/authing-chat/community)