1. 环境准备

1.1 环境要求

Node v10.0 以上 npm v6.0 以上

1.2 whistle安装与配置

whistle(读音[ˈwɪsəl]，拼音[wēisǒu])基于Node实现的跨平台web调试代理工具，类似的工具有Windows平台上的Fiddler，主要用于查看、修改HTTP、HTTPS、Websocket的请求、响应，也可以作为HTTP代理服务器使用，不同于Fiddler通过断点修改请求响应的方式，whistle采用的是类似配置系统hosts的方式，一切操作都可以通过配置实现，支持域名、路径、正则表达式、通配符、通配路径等多种匹配方式，且可以通过Node模块扩展功能：

1.2.1 安装whistle

执行如下npm命令安装whistle （**Mac或Linux的非root用户需要在命令行前面加 sudo ，如： sudo npm install -g whistle **）

npm install -g whistle

whistle安装完成后，执行命令 whistle help 或 w2 help ，查看whistle的帮助信息

w2 help

1.2.2 启动whistle

启动whistle:

$ w2 start

Note: 如果要防止其他人访问配置页面，可以在启动时加上登录用户名和密码 -n yourusername -w yourpassword 。 重启whsitle:

$ w2 restart

停止whistle:

$ w2 stop

调试模式启动whistle(主要用于查看whistle的异常及插件开发):

$ w2 run

启动完whistle后，最后一步需要配置代理。

1.2.3 配置代理

1. 配置whistle 配置whistle代理是为了完成自定义门户的开发联调，访问https://localhost:8899/打开如下界面，按图中所示添加代理配置：

127.0.0.1:1234 shingao.beta.tencentciam.com excludeFilter://*/p excludeFilter://*/oauth2/*

注意： shingao.beta.tencentciam.com需要替换成租户的域名，在CIAM控制台->个性化设置->域名设置 中获取租户域名。

2. 安装Chrome代理插件 配置好whislte代理后，还需要安装Chrome代理插件：推荐安装SwitchyOmega

1. 代理服务器：127.0.0.1 (如果部署在远程服务器或虚拟机上，改成对应服务器或虚拟机的ip即可)
2. 默认端口：8899 (如果端口被占用，可以在启动时通过 -p 来指定新的端口，更多信息可以通过执行命令行 w2 help ( v0.7.0 及以上版本也可以使用 w2 help ) 查看)

如上所示配置完成后，开启SwitchyOmega，如果能正常打开页面，whistle安装启动完毕，可以开始使用。

1.2.4 安装根证书

最后，我们还需要开启捕获HTTPS请求，需要安装根证书，步骤如下：

1. 下载根证书，开启捕获HTTPS请求

2. 安装根证书 > 证书按下面步骤安装后，如果还出现安全提醒，这个主要原因是之前你访问过该页面，导致长连接已建立，可以等段时间再访问、或重新打开浏览器，或重启下whistle： w2 restart 如上图下载完根证书后点击rootCA.crt文件，弹出根证书安装对话框。

• Windows: Installing a root certificate on Windows 下载证书后，双击证书，根据指引安装证书。证书安装过程，要确保证书存储到 受信任的根证书颁发机构 下。
• Mac: Mac根证书怎么安装 Mac 安装证书后，需要手动信任证书，步骤如下： 打开证书管理界面，找到带有 whistle 的字样的证书，如果有多个又不确定最新安装的是哪个，可以全部删除后重新安装 双击证书后，点击 Trust 左边展开选项，红色部分选择 Always Trust （总是信任），点击左上角关闭当前界面会要求输入密码；输入密码后可 以看到证书上面红色的图标 x 不见了，到这一步说明完成证书安装。

至此，我们就完成了whistle的安装与配置，接下来就可以进行开发调试了！

2. 使用Portal SDK进行开发与调试

2.1 安装门户SDK

• npm引入方式

npm install ciam-portal-sdk

2.2 引入其他依赖

门户SDK中内置腾讯天御验证码，需要在HTML文件中引入天御验证码Js CDN（必选） 如果认证源中配置了微信扫码登录，则需要引入微信扫码登录Js CDN（可选）

2.3 开发与调试

接下来将以示例项目为例，演示如何进行自定义portal的开发与调试。

2.3.1 启动示例项目

1. 启动示例项目，打开example示例目录, 执行以下命令开发静态页面；

yarn 
yarn run start

2. 确认whstle代理配置已配置并开启；

127.0.0.1:1234 userdomainname.beta.tencentciam.com excludeFilter://*/p excludeFilter://*/oauth2/*

2.3.2 测试联调

1. 打开CIAM产品控制台->应用管理菜单, 在展示的应用列表中点击某条应用的体验按钮，页面即会代理到门户的开发页面，展示如下页面：

2. 测试联调 测试本地修改代码后，刷新上述的页面可即时看到修改，即可进行联调了。

2.4.项目部署

1. 执行项目打包

yarn run build

2. 联系CIAM售后或技术支持进行站点布署

3. Portal SDK

3.1 SDK说明

3.1.1 SDK实例化

PortalClient初始化需要传入clientId（必选）、onSuccess（非必选）、onError（非必选）

• 代码示例

import { PortalClient } from 'ciam-portal-sdk';

const authSDK = new PortalClient({
  clientId: "应用ID",
  onSuccess: () => {}, // 异常初始化成功后的回调
  onError: () => {}, // 异常初始化失败后的回调
});

• 参数说明

参数	类型	是否必填	说明	默认值
clientId	string	是	应用ID	-
onSuccess	Function	否	成功的回调	-
onError	Function	否	失败的回调	-

3.1.2 loginByUserNamePassword 账密登录

开发者可以调用loginByUserNamePassword方法完成用户名密码登录，该方法内置天御验证码安全校验，当登录三次失败后触发天御验证码校验。

• 代码示例

 await authSDK.loginByUserNamePassword(username, password, captchaConfig);

• 参数说明

参数	类型	是否必填	说明	默认值
username	string	是	用户名	-
password	string	是	密码	-
captchaConfig	obj	否	天御监听	-

CaptchaConfigProps

参数	类型	是否必填	说明	默认值
onCancel	Function	否	关闭天御弹窗监听	-
onError	Function	否	天御错误监听	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.3 loginBySMS 手机号登录

开发者可以调用loginBySMS实现手机号码登录，该方法需要搭配sendSMSCode方法共同使用，通过 sendSMSCode获取验证码后调用loginBySMS方法完成手机号登录

• 代码示例

authSDK.loginBySMS(phoneNumber, phoneArea, captha);

• 参数说明

参数	类型	是否必填	说明	默认值
phoneNumber	string	是	手机号码	-
phoneArea	string	是	国际码，目前只支持+86	-
captha	string	是	短信验证码	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.4 sendSMSCode 登录页面发送短信验证码

开发者可以调用sendSMSCode实现短信验证码发送，该接口需要在CIAM控制台配置正确的短信服务。

• 代码示例

authSDK.sendSMSCode(phoneNumber, phoneArea, captchaConfig);

• 参数说明

参数	类型	是否必填	说明	默认值
phoneNumber	string	是	手机号码	-
phoneArea	string	是	国际码，目前只支持+86	-
captchaConfig	obj	否	天御监听	-

CaptchaConfigProps

参数	类型	是否必填	说明	默认值
onCancel	Function	否	关闭天御弹窗监听	-
onError	Function	否	天御错误监听	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.5 generateWechatPCUrl 生成微信PC扫码登录链接

开发者可以通过调用 generateWechatPCUrl 快速生成微信PC扫码的登录授权链接，跳转后的链接中携带有生成微信二维码所需要的参数，应用前端再通过getWechatPcParams方法获取到微信的参数，最终渲染出登录的二维码，微信官网文档参考：网站内嵌二维码微信登录

• 示例代码

<a href="#">使用微信PC扫码登录</a>

3.1.6 getWechatPcParams 获取微信二维码的参数信息

获取微信二维码的参数信息，用于微信二维码的渲染与展示，配合generateWechatPCUrl方法使用

• 生成微信二维码示例代码

const params = authSDK.getWechatPcParams();
new WxLogin({
    self_redirect: false,
    id: "login_container",
    ...params,
    style: "black",
    href: "data:text/css;base64,QGNoYXJzZXQgInV0Zi04IjsuaW1wb3dlckJveCAucXJjb2Rle3dpZHRoOjE4MHB4O2JvcmRlcjowO21hcmdpbi10b3A6MTNweH0uaW1wb3dlckJveCAudGl0bGV7ZGlzcGxheTpub25lfS5pbXBvd2VyQm94IC5pbmZve3dpZHRoOjE2MHB4fS5zdGF0dXNfaWNvbntkaXNwbGF5Om5vbmV9LmltcG93ZXJCb3ggLnN0YXR1c3t0ZXh0LWFsaWduOmNlbnRlcn0ud3JwX2NvZGV7d2lkdGg6MjA2cHg7YmFja2dyb3VuZC1jb2xvcjojZmZmO2JvcmRlcjoxcHggc29saWQgI2U1ZTVlNTtib3JkZXItcmFkaXVzOjRweDttYXJnaW46MCBhdXRvO30ucGFuZWxDb250ZW50IC5pbmZve2Rpc3BsYXk6bm9uZX0=",
});

3.1.7 generateWechatH5Url 生成微信网页授权登录链接

开发者可以通过调用 generateWechatH5Url 快速生成微信网页的授权链接，完成微信网页的授权登录。

• 示例代码

<a href="#">使用微信H5登录</a>

3.1.8 sendEmailCodeForResetPassword 重置密码时获取邮箱验证码

开发者可以通过调用sendEmailCodeForResetPassword方法 实现重置密码页面的邮箱验证码发送，该接口需要在CIAM控制台配置正确的邮箱服务。

• 代码示例

authSDK.sendEmailCodeForResetPassword(email);

• 参数说明

参数	类型	是否必填	说明	默认值
email	string	是	邮箱值	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.9 resetPassword 重置密码

开发者可以通过调用resetPassword方法 实现重置密码功能。

• 代码示例

authSDK.resetPassword(password, captha);

• 参数说明

参数	类型	是否必填	说明	默认值
password	string	是	新密码	-
captha	string	是	验证码，通过sendEmailCodeForResetPassword方法获取	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.10 getSignUpFlow 获取注册流程配置

开发者可以通过调用getSignUpFlow方法 获取注册页面的注册流程。

• 代码示例

authSDK.getSignUpFlow();

• 参数说明

无

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.11 sendEmailCodeForSignUp 注册时获取邮箱验证码

开发者可以通过调用sendEmailCodeForSignUp方法 实现注册页面的邮箱验证码发送，该接口需要在CIAM控制台配置正确的邮箱服务。

• 代码示例

authSDK.sendEmailCodeForSignUp(email);

• 参数说明

参数	类型	是否必填	说明	默认值
email	string	是	邮箱值	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.12 sendSMSCodeForSignUp 注册时获取手机验证码

开发者可以调用sendSMSCodeForSignUp实现注册页面的短信验证码发送，该接口需要在CIAM控制台配置正确的短信服务。

• 代码示例

authSDK.sendSMSCodeForSignUp(phoneNumber, phoneArea, captchaConfig);

• 参数说明

参数	类型	是否必填	说明	默认值
phoneNumber	string	是	手机号码	-
phoneArea	string	是	国际码，目前只支持+86	-
captchaConfig	obj	否	天御监听	-

CaptchaConfigProps

参数	类型	是否必填	说明	默认值
onCancel	Function	否	关闭天御弹窗监听	-
onError	Function	否	天御错误监听	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.13 postSignUp 注册提交

开发者可以通过调用postSignUp方法 实现用户的注册，开发者需要注册提交的表单均为动态表单，即控制台注册流程中动态配置的认证/普通属性。

• 代码示例

authSDK.postSignUp(formValues, captchaConfig);

• 参数说明 | 参数 | 类型 | 是否必填 | 说明 | 默认值| | :---: | :---: | :---: | :---: | :---: | | formValues | obj | 是 | 填写的注册表单 | - | | captchaConfig | obj | 否| 天御监听 | - |

formValuesProps

参数	类型	是否必填	说明	默认值
userName	string	是	姓名	-
gender	string	是	性别	-
phoneNumber	string	是	手机号	-

CaptchaConfigProps

参数	类型	是否必填	说明	默认值
onCancel	Function	否	关闭天御弹窗监听	-
onError	Function	否	天御错误监听	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.14 loginByEmail 邮箱登录

开发者可以调用loginByEmail实现邮箱登录，该方法需要搭配sendEmailCode方法共同使用，通过 sendEmailCode获取验证码后调用loginByEmail方法完成邮箱登录

• 代码示例

authSDK.loginByEmail(email, captha);

• 参数说明

参数	类型	是否必填	说明	默认值
email	string	是	邮箱号码	-
captha	string	是	邮箱验证码	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.15 sendEmailCode 登录页面发送邮箱验证码

开发者可以调用sendEmailCode实现邮箱验证码发送，该接口需要在CIAM控制台配置正确的邮箱服务。

• 代码示例

authSDK.sendEmailCode(email);

• 参数说明

参数	类型	是否必填	说明	默认值
email	string	是	邮箱号码	-

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.16 getContext 获取登录上下文信息

• 代码示例

authSDK.getContext();

• 参数说明

无

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.17 setAgreement 设置协议管理缓存

开发者可以调用setAgreement实现同意管理功能，该方法用于存储用户的勾选配置，搭配协议数据发送postAgreement方法，共同完成协议管理功能。

• 代码示例

authSDK.setAgreement(agreementIds);

• 参数说明

参数	类型	是否必填	说明	默认值
agreementIds	string[]	是	选中的协议管理id数组，传入格式参考[id1,id2]	-

• 成功响应

同意管理配置信息写入浏览器 sessionStorage的AGREE_PROTOCOL Key

• 错误响应

控制台抛出错误信息

3.1.18 postAgreement 发送协议管理至服务端

开发者可以调用postAgreement实现同意管理功能，该方法用于协议数据发送，调用此方法时有两个前置条件：

1. 前端需要调用setAgreement方法进行勾选协议设置;
2. 前端需要提供/consent页面路由，在/consent视图中调用该方法，具体实现参考portal sample;

• 代码示例

authSDK.postAgreement();

• 参数说明 无

• 成功响应

// Promise响应体
{code: 0, message: "success", data: T, status: number, statusText: string, headers: AxiosResponseHeaders, config: AxiosRequestConfig, request?: any;}

• 错误响应

{code: -1, message: "错误信息"}

3.1.19 generateSignUpUrl 获取跳转至注册页面链接

开发者可以调用generateSignUpUrl获取跳转至注册页面链接，该方法用于跳转注册页面时调用。

• 代码示例

authSDK.generateSignUpUrl();

3.1.20 generatePreLoginUrl 获取返回至登录页面链接

开发者可以调用generatePreLoginUrl获取返回至登录页面链接，该方法用于其他页面返回登录主页面时调用。

• 代码示例

authSDK.generatePreLoginUrl();

3.2 ChangeLog

1.7.0

2024-10-24

• FEATURE: Portal SDK适配短信OTP认证源和应用注册流程的“开启图形验证码保护”配置

1.6.6

2024-10-24

• FIX: 修复generateWechatPCUrl、generateWechatH5Url方法生成的微信链接无法正常登录

1.6.2

2023-04-24

• DOCS: 更新文档的图片链接

1.6.0

2022-09-20

• FEATURE: SDK新增同意管理的方法：setAgreement、postAgreement，适用于门户添加协议管理能力时使用，具体使用说明见上述文档
• FEATURE: SDK新增获取跳转至注册页面的方法：generateSignUpUrl，具体使用说明见上述文档
• FEATURE: SDK新增获取返回登录链接的方法：generatePreLoginUrl，具体使用说明见上述文档

1.5.0

2022-08-03

• FEATURE: 天御验证码更新为控制台配置模式

1.4.0

2022-07-27

• FEATURE: 新增loginByEmail、sendEmailCode、getContext 三个API，具体使用说明见上述文档

1.3.0

2022-07-18

• FEATURE: loginByUserNamePassword、sendSMSCode、sendSMSCodeForSignUp、postSignUp 添加captchaConfig参数，开放天御验证码onError、onCancel监听，使用办法见文档

v1.2.x

2022-05-28

• BREAKCHANGE: new PortalClient()不再支持dtoConfig参数，改为内部自动获取，不需要开发者手动传入；
• BREAKCHANGE: 去掉redirectWechatPC、redirectWechatH5方法，改为生成链接，由开发者决定交互形为；
• FEATURE: new PortalClient() 新增onSuccess、onError监听，SDK内异步初始化后调用回调监听；
• FEATURE: SDK增加generateWechatPCUrl、generateWechatH5Url方法，用于微信公众号实现快速登录认证；
• FEATURE: SDK添加sendEmailCodeForResetPassword、resetPassword方法，用于密码重置功能开发；
• FEATURE: SDK添加getSignUpFlow、sendEmailCodeForSignUp、sendSMSCodeForSignUp、postSignUp方法，用于注册功能开发；

v1.0.0

2022-04-08

• FEATURE： 发布v1.0