# SDK for 单点登录

SDK for 单点登录

Authing SSO SDK 用于发起 SSO 登录、查询 SSO 登录状态、单点登出。

# 安装

# 通过 NPM 安装

$ npm install @authing/sso --save

接着可以通过以下方式使用

import AuthingSSO from '@authing/sso';

# 通过 CDN 安装

<script src="https://cdn.jsdelivr.net/npm/@authing/sso/dist/AuthingSSO.umd.min.js"></script>

<script>
  console.log(AuthingSSO);
</script>

# 开始使用

需要先注册一个 Authing (opens new window) 账号，并创建一个 OIDC 应用 (opens new window)。

# 发起登录

# 跳转登录

import AuthingSSO from '@authing/sso';

let auth = new AuthingSSO({
  appId: 'SSO_APP_ID',
  appType: '可填：oauth/oidc', // 默认 oidc
  appDomain: 'SSO_APP_DOMAIN',
});

// 发起单点登录，会跳转到登录页面，采用授权码模式，需要相关应用开启授权码模式
auth.login();

# 窗口登录

import AuthingSSO from '@authing/sso';

let auth = new AuthingSSO({
  appId: 'SSO_APP_ID',
  appType: '可填：oauth/oidc', // 默认 oidc
  appDomain: 'SSO_APP_DOMAIN',
});

// 发起单点登录，会弹出一个窗口，里面是登录页面，采用授权码模式，需要相关应用开启授权码模式
auth.windowLogin();

业务域名回调地址需要托管一个 html 文件，用于将得到的 code access_token id_token 等参数，通过 postMessage 的方式发送给父窗口，然后将本窗口关闭。

例如，回调地址填写的是 https://example.com/handle.html 这个 html 内部需要编写一段发送 postMessage 的代码，负责从 url 中取出相关参数并传递给父窗口。

Github 参考代码：https://github.com/Authing/oidc-window (opens new window)

# 跳转注册页

有时你可能希望让用户跳转到注册页面，使用示例如下：

import AuthingSSO from '@authing/sso';

let auth = new AuthingSSO({
  appId: 'APP_ID',
  appType: '可填：oauth/oidc', // 默认 oidc
  appDomain: 'APP_DOMAIN',
});

// 调用此函数可以直接跳转到注册页面
auth.register();

# 查询登录状态

let res = await auth.trackSession();
/**
 * {
 *    session: { appId: 'xxx', type: 'oidc/oauth', 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`	`oidc`
scope	否	SSO 授权域	'openid profile email phone'，查看支持的 Scope，使用自定义 Scope
state	否	自定义字符串，回调地址也会受到此参数，内容相同，可用于传递信息	随机字符串
host	否	一个对象，用于指定 GraphQL 地址	`{ oauth: 'https://core.authing.cn/graphql' }`
host.oauth	否	GraphQL 通信地址	https://core.authing.cn/graphql
responseType	否	SSO 应用授权流程，可选值为 `code`，`implicit`	`code`
redirectUrl	否	SSO 应用回调域名	在 Authing 控制台配置的第一个业务域名
nonce	否	随机数	随机数
timestamp	否	时间戳	当前时间戳

示例

let auth = new AuthingSSO({
  appId: "APP_ID",
  appType: "oidc",
  appDomain: "APP_DOMAIN"
});

请求应用的授权地址，进行登录。

参数列表：

参数名	是否必填	描述	默认
lang	否	语言，可选值为 `zh-CN` 和 `en-US`	由浏览器语言环境决定

示例：

auth.login();

# AuthingSSO.prototype.register

调用此函数可以直接跳转到注册页面。

参数列表：

参数名	是否必填	描述	默认
lang	否	语言，可选值为 `zh-CN` 和 `en-US`	由浏览器语言环境决定

示例：

auth.register();

# AuthingSSO.prototype.trackSession

查询单点登录状态，已登录时会返回会话信息和用户信息。

示例：

let res = await auth.trackSession();
/**
 * {
 *    session: { appId: 'xxx', type: 'oidc/oauth', 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
 * }
 * */

# AuthingSSO.prototype.getUrlHash

获取 Url 中的 Hash 部分内容，返回一个 JSON 对象。

示例：

let obj = auth.getUrlHash();
/**
 * {
 *    id_token: 'xxx',
 *    access_token: 'xxx'
 * }
 * */

# Get Help

Join us on Gitter: #authing-chat (opens new window)

← Guard for Web 认证核心模块 →