南京智慧教育云服务认证中心-统一身份认证系统单点登录接口说明

1.名词解释

2.简介

6.SSOAuth接口

6.1.验证授权码是否有效 6.2.获得该用户个人信息 6.3.根据令牌返回统一身份认证用户名 6.4.根据令牌判断用户是否为实名用户 6.5.获得子系统对用户信息的访问权限 6.6.根据令牌、子系统缩写返回角色名列表 6.7.根据令牌、子系统缩写返回权限列表 6.8.根据令牌返回子系统用户名集合 6.9.统一身份认证账户与子系统账户关联 6.10.用户实名认证 6.11.获得该用户管理的组织机构名称

7.返回结果编码

8.MD5加密算法(C#)

9.时间戳(C#)

10.统一权限管理接口说明

10.1统一权限管理简介 10.2统一权限管理Web服务接口

统一身份认证系统单点登录接口说明

1.名词解释

1.1 完全集成子系统：

该子系统用户名与统一身份认证用户名为同一套账户，子系统没有单独的登录模块，用户合法性验证由统一身份认证系统完成。

1.2 未完全集成子系统：

该子系统有独立的用户管理模块和用户群，不与统一身份认证系统使用相同的账户，用户需要在统一身份认证系统进行统一身份认证账户与本子系统账户关联设置，统一身份认证账户才能登录进入该子系统，登录该系统后，仍然使用本子系统的账户。

1.3 Code码：

临时令牌，用于换取下面的正式令牌，使用后自动失效。

1.4 令牌：

正式令牌为36位字符串，用于验证登录状态和换取用户信息。

1.5 平台相关地址

单点登录地址：http://sso.jyjsfz.cn 门户网站地址：http://uia.jyjsfz.cn 接口文档地址：http://sso.jyjsfz.cn/apidoc/index

2.简介

本文档以asp.net语言为例进行讲解。所有加入统一身份认证的子系统均需要添加一个验证模块，模块名：SSOAuth。该模块主要负责本系统的用户合法性验证工作（主要根据传递的统一身份认证令牌，验证令牌合法性，并获取登录的用户名或子系统绑定的用户名集合）

需要加入到统一身份认证平台的子系统都需要有一个名字唯一的英文编码作为自己的标识，验证模块地址（统一身份认证系统登录成功后，将直接跳转到该模块，并传递相应的令牌信息，该模块接收到令牌后，将验证令牌合法性）。

3. 子系统处理方式

假定子系统已在统一身份认证系统中注册，以下为系统相关信息：

名称	值
子系统英文编码	eyou
域名	mail.eyou.com
验证模块地址	http://mail.eyou.com/SSOAuth

3.1未完全集成子系统处理方式

当用户第一次访问eyou受保护的系统资源时，eyou将用户请求重定向到SSOAuth模块，该模块首先获取到Code码，如果获取不到需要跳转到Authorization.aspx页面（需携带验证参数及回调地址），该页面会验证用户是否登录：

1) 如果未登录则自动跳转到登录页面，登录成功后将携带Code码跳回SSOAuth模块； 2) 如果已登录则携带Code码跳回SSOAuth模块；

重复获取Code码，调用api/SSOAuth/AccessToken接口使用该Code码换取令牌，验证令牌的有效性，调用api/SSOAuth/GetMapUserNamesByTokenID接口使用令牌获取统一身份认证系统账号对应的子系统用户名集合，多用户名以“,”分割，无映射账户则返回空字符串）。

① 如果该令牌有效，则会返回eyou系统中的用户名集合，并表明该用户可以成功登录eyou系统。
② 如果令牌无效则返回错误代码“103”，并跳转到统一身份认证系统登录页面

3.2完全集成子系统处理方式

1) 如果未登录则自动跳转到登录页面，登录成功后将携带Code码跳回SSOAuth模块； 2) 如果已登录则携带Code码跳回SSOAuth模块；

重复获取Code码，调用api/SSOAuth/AccessToken接口使用该Code码换取令牌，验证令牌的有效性，调用api/SSOAuth/GetUserInfoByTokenID接口使用令牌获取统一身份认证用户信息）。

① 如果该令牌有效，则会返回统一身份认证系统中的用户名，并表明该用户可以成功登录eyou系统。
② 如果无效则返回错误代码“103”，并跳转到统一身份认证系统登录页面进行登录。

4.接口实现（完全集成系统）

模块代码：
SSOAuth.aspx（无内容）

SSOAuth.aspx.cs（验证令牌合法性，并获取用户信息）：

5.用户退出系统功能

子系统首先需要将子系统本身的登录信息清除，如清除session信息等。然后直接跳转到统一身份认证系统的登出模块。跳转登出页面地址格式为： http://sso.jyjsfz.cn/SignOut.aspx?ReturnUrl=UrlEncode(“http://mail.eyou.com/SSOAuth”) ，其中参数ReturnUrl为经过url加密的eyou系统的验证模块地址，用户再次登录，将根据这个地址返回到子系统中来。

6.SSOAuth接口

6.1.验证授权码是否有效

地址：http://sso.jyjsfz.cn/api/ssoauth/AccessToken?AppCode={1}&EncryptString={2}&TimeSpan={3}&Code={4}

6.2.获得该用户个人信息

地址：http://sso.jyjsfz.cn/api/ssoauth/GetUserInfoByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

字段说明：

字段	说明
UserName	统一身份认证用户名
RealName	真实姓名
NickName	昵称
IDCard	IDCard
Email	电子邮箱
IsRealName	是否真实姓名（1是0否）
TelePhone	电话
FamilyPhone	家庭电话
OfficePhone	办公室电话
Address	地址
Sex	性别
BirthDay	出生年月
Title	职称
Country	城市
Unit	单位
QQ	QQ
MSN	MSN
UserType	用户类型（教师、学生等）
Org	组织机构名称
OrgCode	组织机构编号

6.3.根据令牌返回统一身份认证用户名

地址：http://sso.jyjsfz.cn/api/ssoauth/GetUserNameByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

6.4.根据令牌判断用户是否为实名用户

地址：http://sso.jyjsfz.cn/api/ssoauth/IsRealNameByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

6.5.获得子系统对用户信息的访问权限

地址：http://sso.jyjsfz.cn/api/ssoauth/GetUserInfoAccessFields?AppCode={1}&EncryptString={2}&TimeSpan={3}

6.6.根据令牌、子系统缩写返回角色名列表

地址：http://sso.jyjsfz.cn/api/ssoauth/GetRolesByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

6.7.根据令牌、子系统缩写返回权限列表

地址：http://sso.jyjsfz.cn/api/ssoauth/GetUserFunctionsByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

字段说明：

字段	说明
FunctionCode	模块缩写
Value	值

6.8.根据令牌返回子系统用户名集合

地址：http://sso.jyjsfz.cn/api/ssoauth/GetMapUserNamesByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

6.9.统一身份认证账户与子系统账户关联

地址：http://sso.jyjsfz.cn/api/ssoauth/RegistUserMap?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}&AppUserName={5}

6.10.用户实名认证

地址：http://sso.jyjsfz.cn/api/ssoauth/RegistRealeUser?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}&AppUserName={5}

6.11.获得该用户管理的组织机构名称

地址：http://sso.jyjsfz.cn/api/ssoauth/GetOrgByTokenID?AppCode={1}&EncryptString={2}&TimeSpan={3}&TokenID={4}

7. 返回结果编码

编码说明：

编码	说明
OK	成功
101	无效AppCode
102	加密验证失败
103	令牌失效
104	不提供实名认证服务
105	是集成系统，不提供用户关系映射

8. MD5加密算法(C#)

9. 时间戳(C#)

10.统一权限管理接口说明

10.1统一权限管理简介

统一身份认证系统提供统一权限管理的功能，采用用户（User）+角色(Role)+模块(Module)+权限(Permission)的模式。统一身份认证系统为每个子系统都提供权限管理的功能，该功能主要涉及模块管理、角色管理、权限管理。子系统可以被划分成若干个功能模块，如用户管理、日志管理等，每个功能模块又可以细分成不同的权限，如用户管理模块中有添加用户、修改用户、删除用户等权限。

(1) 模块信息主要由以下信息组成：英文编号、模块名称

如：

英文编码	模块名称
UserManage	用户管理
RoleManage	角色管理

(2) 权限信息主要由以下信息组成：权限值（2的n次方的整数）、权限名称

如:用户管理有如下权限：查看、新增、修改、删除

权限值	权限名称
2	查看
4	新增
8	修改
16	删除

如果某用户所在角色拥有上述四种操作权限，则其Permission=2+4+8+16=30。
下面进行权限检测，判断“(Role + Module)”所对应的Permission是否包含上述四种操作权限中的每一个。解决问题关键：使用“&”运算符。比如：
判断Permission是否包含“查看”的权限值，就用 if((Permission & 2) == 2)
判断Permission是否包含“新增”的权限值，就用 if((Permission & 4) == 4)
判断Permission是否包含“修改”的权限值，就用 if((Permission & 8) == 8)
判断Permission是否包含“删除”的权限值，就用 if((Permission & 16) == 16)
原理(转化为二进制，进行“与”运算)：
30 & 2 = 00011110 & 00000010 = 00000010
30 & 4 = 00011110 & 00000100 = 00000100
30 & 8 = 00011110 & 00001000 = 00001000
30 & 16 = 00011110 & 00010000 = 00010000

10.2统一权限管理Web服务接口

(1) public List GetRoles(string AppCode,String UserName) 该方法可以获得某一用户所具有的角色列表信息

(2) public List GetUserFunctions(string AppCode,String UserName) 该方法可以获得某一用户能够访问的功能编号、功能权值列表信息

(3) 类Function2定义代码 public class Function2

{
    /// 模块缩写
    public string FunctionCode
    /// 值
    public int? Value
}