# 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)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://authing.gitbook.io/authing/sdk/sdk-for-sso.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.