SSO对接
一、SSO简介
SSO（Single Sign-On，单点登录），是一种帮助用户快捷访问网络中多个站点或应用的安全通信技术。
SSO基于一种安全的通信协议，该协议通过多个系统之间的用户身份信息的交换来实现单点登录。使用SSO时，用户只需要登录一次，就可以访问多个系统，不需要记忆多个口令密码。
亿联融合通信已支持Oauth2.0对接第三方的组织架构实现账号鉴权，架构同步。
说明：UC V46版本已新增支持CAS和Saml协议的SSO以及客户端SSO登陆。
二、SSO价值
三、SSO对接可行性评估流程
当您有SSO对接需求时，请提供统一认证平台的Oauth2.0、CAS、Saml接口文档给亿联售前工程师，我们将评估对接可行性。评估通过后，将由我们的技术人员安排配置对接。
四、Oauth2.0协议
简介
OAuth（Open Authorization）是一个关于授权（authorization）的开放网络标准，允许用户授权第三方应用访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方移动应用或分享他们数据的所有内容。
OAuth在全世界得到广泛应用，目前的版本是2.0版。
图1 亿联SSO交互逻辑概述图(Oauth2.0协议)
SSO交互详述
Tips：以上流程仅演示了Oauth2.0协议下的一种体验效果，若您需要从自己的网页点击，实现直接跳转登录UC网页个人后台，UC也已支持该场景，对应上述流程，是从第6步开始交互。
UC侧SSO配置详解
1）访问UC企业管理平台网页
（https://x.x.x.x/manager/login，其中x.x.x.x请替换为您部署的UC服务器配置的可解析域名或IP地址），登录企业管理员账号。
2）找到企业设置--SSO
3）配置参数释义
| 配置项名称 | 是否需要配置 | 示例 |
|---|---|---|
| SSO登录 | 是，需设置为“开启”状态。 |  |
| Web默认跳转SSO登录页面 | 否， 若需要访问UC企业管理平台网页时，一律默认跳转SSO登录页，可开启。 | |
| 认证类型 | 是，选择OAuth 2.0。 | |
| 服务器地址 | 是 ，需统一认证平台提供其地址。 | 例：https://test.yealink.com |
| 企业域名 | 否，UC系统会自动生成，无需修改。 | |
| 登录页面URL | 是 ，统一认证平台提供的鉴权页面，用户在此页面输入相应的账号、密码或者扫码登录。无需完整URL。 | 例：/oauth2/authorize |
| 注销页面URL | 否，若需要在UC网页个人后台点击退出登录时，同步也将认证平台的对应用户账号一起退出登录，则可配置认证平台提供的用户登出接口。无该需求可不配置。无需完整URL。 | |
| 获取Token URL | 是 ，统一认证平台提供的用于从鉴权生成临时Code，获取访问用户信息的Token。无需完整URL。 | 例：/oauth2/token |
| 用户信息查询 URL | 是 ，统一认证平台提供的获取用户信息的Endpoint, 无需完整URL。 | 例：/oauth2/userinfo |
| APP ID | 是 ，需统一认证平台提供，鉴权获取code和token时使用 | |
| APP Secret | 是 ，需统一认证平台提供，鉴权获取code和token时使用 | |
| 授权范围 | 是 为登录用户申请的访问权限范围，支持填写多个，使用英文逗号隔开。 | 例：all |
| 服务地址 | 否，配置SSO完毕后，由UC自动生成，具体请看下述回调地址说明。 | |
| 用户ID属性 | 是 ，作为UC和统一认证平台账号关联的唯一标识。 | 例：user_id |
| 名称属性 | 是，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户名称属性时使用。 | 例：user_name |
| 用户名属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户名属性时使用。 | |
| 分机号属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户分机号属性时使用。 | 例：extension |
| 别名属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户别名属性时使用。 | |
| 性别属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户性别属性时使用。 | 例：gender |
| 部门ID属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户所在部门分组唯一ID时使用。 | 例：groupId |
| 部门名称属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户所在部分分组名称时使用。 | 例 ：groupName |
| 职位属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户职位属性时使用。 | 例：title |
| 密码 | 是，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户密码使用。 | 例：初始密码 |
| 邮箱属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户邮箱属性时使用。 | 例：email |
| 电话号码属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户手机号属性时使用。 | 例：phone |
根据以上表格，将必填参数配置完毕后，点击保存即可。
4）亿联UC回调地址说明
UC V46版本开始，回调地址均在web上配置sso时，自动生成，以下述为例，自行根据应用场景修改即可。
注意：认证平台请放通{域名或ip}/thirdparty/api/v1/auth/sso/callback*的回调地址，星号表示通配，即放通{域名或ip}/thirdparty/api/v1/auth/sso/callback开头的所有地址。
示例
{域名或ip}/thirdparty/api/v1/auth/sso/callback?params=eyJwYXJ0eUlkIjoiNTJiNmE3ZTIzMDNkNDMzNjlmMzhmOTdjYThiZmNlODIiLCJjbGllbnRUeXBlIjoyLCJmcm9tSWRwIjp0cnVlLCJ3ZWJIb3N0IjoiaHR0cHM6Ly91YzR4ZGVtby55ZWFsaW5rb3BzLmNvbSJ9
参数说明：
{域名或ip}：表示UC服务器配置的域名或IP；
params：等号后的值可使用base64解密，如示例解码为{"partyId":"52b6a7e2303d43369f38f97ca8bfce82","clientType":2,"fromIdp":true,"webHost":"https://uc4xdemo.yealinkops.com"}
根据应用场景是web跳转登录或是唤醒客户端sso登录，对"clientType":2的值进行修改，2代表唤醒客户端sso登录，0代表跳转web登录sso。修改成对应数值后，使用base64原封加密回去，拼接到params=后即可。
其他参数不需要修改。
五、CAS协议
简介
Central Authentication Service简称CAS，是 Yale 大学发起的一个企业级的、开源的项目，旨在为Web 应用系统（B/S架构）提供一种可靠的单点登录解决方法（属于 Web SSO ）CAS 开始于 2001 年， 并在 2004 年 12 月正式成为 JA-SIG 的一个项目。CAS是一个纯粹的认证服务器，没有授权功能；它包括CAS 1.0、CAS2.0、CAS3.0版本，这三个版本的认证流程基本类似。
SSO交互详述
Tips：以上流程仅演示了CAS协议下的一种体验效果，若您需要从自己的网页点击，实现直接跳转登录UC网页个人后台，UC也已支持该场景，对应上述流程，是从第6步开始交互。
UC侧SSO配置详解
1）访问UC企业管理平台网页
（https://x.x.x.x/manager/login，其中x.x.x.x请替换为您部署的UC服务器配置的可解析域名或IP地址），登录企业管理员账号。
2）找到企业设置--SSO
3）配置参数释义
| 配置项名称 | 是否需要配置 | 示例 |
|---|---|---|
| SSO登录 | 是，需设置为“开启”状态。 | |
| Web默认跳转SSO登录界面 | 否， 若需要访问UC企业管理平台网页时，一律默认跳转SSO登录页，可开启。 | |
| 认证类型 | 是，选择CAS。 | |
| 服务器地址 | 是 ，需CAS认证平台提供其地址。 | 例：https://test.yealink.com |
| 企业域名 | 否，UC系统会自动生成，无需修改。 | |
| 登录页面URL | 是 ，统一认证平台提供的鉴权页面，用户在此页面输入相应的账号、密码或者扫码登录。无需完整URL。 | 例：/sso/login |
| 注销页面URL | 否，若需要在UC网页个人后台点击退出登录时，同步也将认证平台的对应用户账号一起退出登录，则可配置认证平台提供的用户登出接口。无该需求可不配置。无需完整URL。 | |
| 获取ST票据URL | 否，正常CAS认证平台会在用户登录成功后，会自动响应给UC，若有特殊需要UC主动调用获取ST时，可提供给UC配置。无需完整URL。 | |
| ST验证和用户信息查询URL | 是，由CAS认证平台提供，UC收到ST票据响应后，将调用此接口，向CAS认证平台验证ST有效性，认证平台验证有效后需响应验证结果和用户信息给UC。无需完整URL | 例：/serviceValidate |
| 服务地址 | 否，配置SSO完毕后，由UC自动生成，具体请看下述回调地址说明。 | |
| 请求类型 | 是，默认为GET，可选POST，请根据CAS认证平台要求的ST验证和用户信息查询URL接口请求方法选择。 | 例：GET |
| 用户ID属性 | 是 ，作为UC和统一认证平台账号关联的唯一标识。 | 例：user_id |
| 名称属性 | 是，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户名称属性时使用。 | 例：user_name |
| 用户名属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户名属性时使用。 | |
| 分机号属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户分机号属性时使用。 | 例：extension |
| 别名属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户别名属性时使用。 | |
| 性别属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户性别属性时使用。 | 例：gender |
| 部门ID属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户所在部门分组唯一ID时使用。 | 例：groupId |
| 部门名称属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户所在部分分组名称时使用。 | 例 ：groupName |
| 职位属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户职位属性时使用。 | 例：title |
| 密码 | 是，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户密码使用。 | 例：初始密码 |
| 邮箱属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户邮箱属性时使用。 | 例：email |
| 电话号码属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户手机号属性时使用。 | 例：phone |
4）亿联UC回调地址说明
UC V46版本开始，回调地址均在web上配置sso时，自动生成，以下述为例，自行根据应用场景修改即可。
注意：认证平台请放通{域名或ip}/thirdparty/api/v1/auth/sso/callback*的回调地址，星号表示通配，即放通{域名或ip}/thirdparty/api/v1/auth/sso/callback开头的所有地址。
示例
{域名或ip}/thirdparty/api/v1/auth/sso/callback?params=eyJwYXJ0eUlkIjoiNTJiNmE3ZTIzMDNkNDMzNjlmMzhmOTdjYThiZmNlODIiLCJjbGllbnRUeXBlIjoyLCJmcm9tSWRwIjp0cnVlLCJ3ZWJIb3N0IjoiaHR0cHM6Ly91YzR4ZGVtby55ZWFsaW5rb3BzLmNvbSJ9
参数说明：
{域名或ip}：表示UC服务器配置的域名或IP；
params：等号后的值可使用base64解密，如示例解码为{"partyId":"52b6a7e2303d43369f38f97ca8bfce82","clientType":2,"fromIdp":true,"webHost":"https://uc4xdemo.yealinkops.com"}
根据应用场景是web跳转登录或是唤醒客户端sso登录，对"clientType":2的值进行修改，2代表唤醒客户端sso登录，0代表跳转web登录sso。修改成对应数值后，使用base64原封加密回去，拼接到params=后即可。
其他参数不需要修改。
六、SAML协议
简介
SAML全称是安全断言标记语言（Security Assertion Markup Language）是一个基于XML的开源标准数据格式，其中定义了按照安全规范所需要的通信的协议和格式。用于在不同的安全域之间交换认证和数据授权。
SAML的重要用途：
单点登录（SSO Single Sign-ON）；
联合认证（Federated Identity）；
在其他架构内使用SAML，比如WS-Security。
SAML 协议三个主要角色：
SP（Service Provider）：向用户提供服务的web 端应用。（独立应用）
IDP（Identity Provide）：向SP提供用户身份信息 （SSO认证系统）
用户：通过登录IDP获取身份断言，并向SP返回身份断言来使用SP提供的服务。
SSO交互详述
Tips：以上流程仅演示了SAML协议下的一种体验效果，若您需要从自己的网页点击，实现直接跳转登录UC网页个人后台，UC也已支持该场景，对应上述流程，是从第6步开始交互。
UC侧SSO配置详解
1）访问UC企业管理平台网页
（https://x.x.x.x/manager/login，其中x.x.x.x请替换为您部署的UC服务器配置的可解析域名或IP地址），登录企业管理员账号。
2）找到企业设置--SSO
3）配置参数释义
| 配置项名称 | 是否需要配置 | 示例 |
|---|---|---|
| SSO登录 | 是，需设置为“开启”状态。 | |
| Web默认跳转SSO登录界面 | 否， 若需要访问UC企业管理平台网页时，一律默认跳转SSO登录页，可开启。 | |
| 认证类型 | 是，选择SAML。 | |
| 服务器地址 | 是 ，需IDP认证平台提供其地址。 | 例：https://test.yealink.com |
| 企业域名 | 否，UC系统会自动生成，无需修改。 | |
| 登录页面URL | 是 ，统一认证平台提供的鉴权页面，用户在此页面输入相应的账号、密码或者扫码登录。无需完整URL。 | 例：/sso/login |
| 注销页面URL | 否，若需要在UC网页个人后台点击退出登录时，同步也将认证平台的对应用户账号一起退出登录，则可配置认证平台提供的用户登出接口。无该需求可不配置。无需完整URL。 | |
| 用户信息查询 URL | 否，正常IDP认证平台会在用户登录成功后，会通过SAML响应给UC，UC自行解析。若有特殊需要UC主动调用接口获取用户信息时，可提供给UC配置。无需完整URL。 | |
| 证书 | 否，由IDP认证平台提供，UC上传导入到服务器内，用于提供给UC加密发给IDP的saml Request，以及UC用来解密IDP响应回来的saml Response。 | |
| 签发者（IdP实体ID） | 是，由IDP认证平台提供，可选和下方的服务提供商(SP)实体ID配合使用，用来验证报文的是否是认可的双方所传递的。 | |
| 服务提供商(SP)实体ID | 否，由IDP认证平台提供，可选和上方的签发者（IdP实体ID）配合使用，用来验证报文的是否是认可的双方所传递的。 | |
| 服务地址 | 否，配置SSO完毕后，由UC自动生成，具体请看下述回调地址说明。 | |
| 绑定 | 是，默认为HTTP-POST，可选HTTP-Redirect，用于定义IDP回调UC地址的方式，对应上述流程图中的第6步。 | |
| 签名哈希算法 | 是，默认为SHA-1，可选SHA-256，用来定义验证报文签名的算法类型。 | |
| 用户ID属性 | 是 ，作为UC和统一认证平台账号关联的唯一标识。 | 例：user_id |
| 名称 | 是，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户名称属性时使用。 | 例：user_name |
| 用户名属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户名属性时使用。 | |
| 分机号属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户分机号属性时使用。 | 例：extension |
| 别名属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户别名属性时使用。 | |
| 性别 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户性别属性时使用。 | 例：gender |
| 部门ID属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户所在部门分组唯一ID时使用。 | 例：groupId |
| 部门名称属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户所在部分分组名称时使用。 | 例 ：groupName |
| 职位属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户职位属性时使用。 | 例：title |
| 密码 | 是，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户密码使用。 | 例：初始密码 |
| 邮箱属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户邮箱属性时使用。 | 例：email |
| 电话号码属性 | 否 ，作为UC同步创建统一认证平台对应用户关联账号，指定UC用户手机号属性时使用。 | 例：phone |
4）亿联UC回调地址说明
UC V46版本开始，回调地址均在web上配置sso时，自动生成，以下述为例，自行根据应用场景修改即可。
注意：认证平台请放通{域名或ip}/thirdparty/api/v1/auth/sso/callback*的回调地址，星号表示通配，即放通{域名或ip}/thirdparty/api/v1/auth/sso/callback开头的所有地址。
示例
{域名或ip}/thirdparty/api/v1/auth/sso/callback?params=eyJwYXJ0eUlkIjoiNTJiNmE3ZTIzMDNkNDMzNjlmMzhmOTdjYThiZmNlODIiLCJjbGllbnRUeXBlIjoyLCJmcm9tSWRwIjp0cnVlLCJ3ZWJIb3N0IjoiaHR0cHM6Ly91YzR4ZGVtby55ZWFsaW5rb3BzLmNvbSJ9
参数说明：
{域名或ip}：表示UC服务器配置的域名或IP；
params：等号后的值可使用base64解密，如示例解码为{"partyId":"52b6a7e2303d43369f38f97ca8bfce82","clientType":2,"fromIdp":true,"webHost":"https://uc4xdemo.yealinkops.com"}
根据应用场景是web跳转登录或是唤醒客户端sso登录，对"clientType":2的值进行修改，2代表唤醒客户端sso登录，0代表跳转web登录sso。修改成对应数值后，使用base64原封加密回去，拼接到params=后即可。
其他参数不需要修改。
七、Web端SSO登录效果
1、场景1
tips：Oauth2.0、CAS和SAML体验效果一致。
1）访问UC登录页
2）点击SSO
3）输入企业号（仅多租户需要，单租户无需）
4）跳转统一认证平台
5）登录认证平台个人账号
6）登录成功后将自动跳转并登录上UC个人管理后台。
2、场景2
tips：Oauth2.0、CAS和SAML体验效果一致。
1）用户直接登录认证平台系统（如门户系统）
2）点击门户系统上的应用跳转按钮（链接的是亿联UC提供的回调地址）
3）自动跳转并登录上对应用户的UC个人管理后台。
八、客户端（PC和移动端）SSO登录
1、场景1
tips：Oauth2.0、CAS和SAML体验效果一致。
PC客户端：
1）下载安装好UME客户端
2）阅读并同意《用户协议》和《隐私政策》
3）配置服务器地址
4）选择SSO点击登录
5）网页自动跳转至认证平台登录页
6）用户自行登录上账号后
7）浏览器提示唤醒UME客户端
8）点击打开即可唤醒UME客户端并自动SSO登录上用户账号。
移动客户端：
1）下载安装好UME客户端
2）阅读并同意《用户协议》和《隐私政策》
3）配置服务器地址
4）选择SSO点击登录
5）UME客户端内置浏览器自动跳转至认证平台登录页
6）用户自行登录上账号
8）登录成功则UME客户端内自动跳转登录SSO用户账号。
2、场景2
tips：Oauth2.0、CAS和SAML体验效果一致。
PC客户端：
1）下载安装好UME客户端
2）用户直接登录认证平台系统（如门户系统）
3）点击业务系统上的应用跳转按钮（链接的是亿联UC提供的回调地址）
4）浏览器跳转提示打开UME客户端
5）点击打开UME客户端，即自动唤醒客户端并通过SSO登录上用户账号。
注意：若首次安装UME客户端，未同意《用户协议》和《隐私政策》，则需要先阅读同意后，再点击web业务系统上的应用跳转按钮，重新唤醒登录。
移动客户端：
1）下载安装好UME移动客户端
2）用户在移动端上直接通过认证平台登录办公app（如移动办公app类的软件）
3）点击app工作台上的应用跳转按钮（链接的是亿联UC提供的回调地址）
4）自动唤醒UME移动客户端并通过SSO登录上对应用户账号
注意：若首次安装UME客户端，未同意《用户协议》和《隐私政策》，则需要先阅读同意后，再点击办公app上的应用跳转按钮，重新唤醒登录。
