1.名词解释
1.1 完全集成子系统：
该子系统用户名与统一身份认证用户名为同一套账户，子系统没有单独的登录模块，用户合法性验证由统一身份认证系统完成。
1.2 未完全集成子系统：
该子系统有独立的用户管理模块和用户群，不与统一身份认证系统使用相同的账户，用户需要在统一身份认证系统进行统一身份认证账户与本子系统账户关联设置，统一身份认证账户才能登录进入该子系统，登录该系统后，仍然使用本子系统的账户。
1.3 令牌：令牌主要分为两种类型
用统一身份认证账户登录系统时产生的令牌，长度为36位字符串，拥有该令牌可访问任意子系统； 用子系统账户通过统一身份认证系统登录页面登录子系统时产生的令牌，长度为42位字符串，该令牌只能在指定的子系统使用，不能在其它子系统使用。
1.4 平台相关地址
单点登录地址：http://sso.nje.cn 门户网站地址：http://uia.nje.cn Web服务地址：http://sso.nje.cn/ssoservice.asmx
Web服务WSDL：http://sso.nje.cn/ssoservice.asmx?wsdl
2.简介
本文档以asp.net语言为例进行讲解。所有加入统一身份认证的子系统均需要添加一个验证模块，模块名：SSOAuth。该模块主要负责本系统的用户合法性验证工作（主要根据传递的统一身份认证令牌，验证令牌合法性，并获取登录的用户名或子系统绑定的用户名集合）
需要加入到统一身份认证平台的子系统都需要有一个名字唯一的英文编码作为自己的标识，验证模块地址（统一身份认证系统登录成功后，将直接跳转到该模块，并传递相应的令牌信息，该模块接收到令牌后，将验证令牌合法性）。
3. 子系统处理方式
假定子系统已在统一身份认证系统中注册，以下为系统相关信息：
|
子系统英文编码
|
eyou
|
|
域名
|
mail.eyou.com
|
|
验证模块地址
|
http://mail.eyou.com/SSOAuth
|
3.1未完全集成子系统处理方式
当用户第一次访问eyou受保护的系统资源时，eyou将用户请求重定向到SSOAuth模块，该模块首先从sso_tokeninfo获取到令牌的值，并判断该值的长度是否等于36位（统一身份认证令牌长度为36位）。
1) 如果为否，则说明该用户还未登录统一身份认证系统，将直接跳转到统一身份认证登录页面。跳转登录页面地址格式为：http：//sso.nje.cn/sigin.aspx?ReturnUrl=UrlEncode(“http://mail.eyou.com/SSOAuth”)，其中参数ReturnUrl为经过url加密的eyou系统的验证模块地址，用户一旦登录成功，将根据这个地址返回到子系统中来。
2) 如果为是，则说明该用户已登录统一身份认证系统，需要访问统一身份认证系统的web服务接口验证令牌的有效性，将令牌作为参数并访问指定的web服务方法（GetMapUserNames该方法返回统一身份认证系统账号对应的子系统用户名集合，多用户名以“,”分割，无映射账户则返回空字符串）。
进行登录。
① 如果该令牌有效，则会返回eyou系统中的用户名集合，并表明该用户可以成功登录eyou系统。
② 如果令牌无效则返回错误代码“103”，并跳转到统一身份认证系统登录页面
3.2完全集成子系统处理方式
当用户第一次访问eyou受保护的系统资源时，eyou将用户请求重定向到SSOAuth模块，该模块首先从sso_tokeninfo获取到令牌的值，并判断该值的长度是否等于36位（统一身份认证令牌长度为36位）。
1) 如果为否，则说明该用户还未登录统一身份认证系统，将直接跳转到统一身份认证登录页面。跳转登录页面地址格式为：http：//sso.nje.cn/sigin.aspx?ReturnUrl=UrlEncode(“http://mail.eyou.com/SSOAuth”)，其中参数ReturnUrl为经过url加密的eyou系统的验证模块地址，用户一旦登录成功，将根据这个地址返回到子系统中来。
2) 如果为是，则说明该用户已登录统一身份认证系统，需要访问统一身份认证系统的web服务接口验证令牌的有效性，将令牌作为参数并访问指定的web服务方法（GetUserNameByToken该方法返回统一身份认证用户名）。
进行登录。
① 如果该令牌有效，则会返回统一身份认证系统中的用户名，并表明该用户可以成功登录eyou系统。
② 如果无效则返回错误代码“103”，并跳转到统一身份认证系统登录页面进行登录。
3.3 登录模块通过子系统用户名、密码登录的处理方式
在统一身份认证系统登录页面，用户使用子系统用户名、密码登录对应的子系统，该方式用户只在对应的子系统登录有效，如果想要访问其他子系统，则需要再次登录。用户登录成功后，将重定向到eyou的SSOAuth模块，该模块首先从sso_tokeninfo获取到令牌的值，并判断该值的长度是否等于42位（该方式登录的令牌长度为42位）。
1) 如果为否，则说明该用户还未登录成功，将直接跳转到统一身份认证登录页面。跳转登录页面地址格式为：http：//sso.nje.cn/sigin.aspx。
2) 如果为是，则说明该用户已登录统一身份认证系统，需要访问统一身份认证系统的web服务接口验证令牌的有效性，将令牌作为参数并访问指定的web服务方法（GetUserNameByToken该方法返回子系统登录用户名）。
① 如果该令牌有效，则会返回子系统的用户名，并表明该用户可以成功登录eyou系统。
② 如果无效则返回错误代码“103”，并跳转到统一身份认证系统登录页面进行登录。
4.接口实现（完全集成系统）
模块代码： SSOAuth.aspx（主要获取令牌信息）
SSOAuth.aspx.cs（验证令牌合法性，并获取用户信息）：
|
sso_signinurl：
|
存放统一身份认证系统登录页面地址
|
|
sso_signouturl：
|
存放统一身份认证系统退出页面地址
|
|
sso_tokeninfo：
|
存放令牌的值
|
<script type="text/javascript" src="http://sso.nje.cn/JS/AuthInit.js?action=SSOAuthDo.aspx"></script>：
为引用统一身份认证系统的JavaScript代码，如果后台逻辑由其它页面（如：SSOAuthDo.aspx）处理，可将“http://sso.nje.cn/JS/AuthInit.js”改成其中“http://sso.nje.cn/JS/AuthInit.js?action=SSOAuthDo.aspx”。
<script type="text/javascript" src="http://sso.nje.cn/Authhandler.aspx?app=eyou">：
为引用统一身份认证系统的JavaScript代码，其中appcode对应的参数值为 eyou在同一身份认证系统中的系统名缩写 。
5.用户退出系统功能
子系统首先需要将子系统本身的登录信息清除，如清除session信息等。然后直接跳转到统一身份认证系统的登出模块。跳转登出页面地址格式为： http://sso.nje.cn/SignOut.aspx?ReturnUrl=UrlEncode(“http://mail.eyou.com/SSOAuth”)
，其中参数ReturnUrl为经过url加密的eyou系统的验证模块地址，用户再次登录，将根据这个地址返回到子系统中来。
6.Web服务接口
6.1.获取所有用户列表
调用方法：
public List<string>GetAllUserName(string AppCode, string EncryptString)
请求参数：
|
AppCode
|
子系统缩写
|
|
EncryptString
|
|
返回类型：
类型说明：
6.2.获得该用户的个人信息
调用方法：
public UserInfo GetUserInfoByUserName(string AppCode,string UserName,string EncryptString)
请求参数：
|
AppCode
|
子系统缩写
|
|
UserName
|
统一身份认证用户名
|
|
EncryptString
|
加密字符串（=MD5（AppCode+UserName+AppKey））
|
返回类型：
类型说明：
|
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
|
组织机构编号
|
提醒：请注意返回的对象中字段可能存在Null。面进行登录。
6.3.分页获取用户信息列表
调用方法：
public List<UserInfo> GetPagedUsers(string AppCode, string EncryptString,
int PageIndex, int PageSize, out int Count, string OrgCode, string Key)
请求参数：
|
AppCode
|
子系统缩写
|
|
EncryptString
|
加密字符串（=MD5（AppCode+AppKey）
|
|
PageIndex
|
分页索引(从1开始)
|
|
PageSize
|
分页页记录数（从1开始，1000以下）
|
|
Count
|
符合条件的用户总数
|
|
OrgCode
|
组织机构编码
|
|
Key
|
关键字（姓名、用户名模糊查询）
|
返回类型：
提醒：返回类型参考【获得该用户的个人信息】
6.4.根据用户名、子系统缩写返回角色名列表
调用方法：
public List<string>GetRoles(string AppCode,String UserName)
请求参数：
|
AppCode
|
子系统缩写
|
|
UserName
|
统一身份认证用户名
|
返回类型：
类型说明：
6.5.根据用户名、子系统缩写返回权限列表
调用方法：
public List<Function2> GetUserFunctions(string AppCode,String UserName)
请求参数：
|
AppCode
|
子系统缩写
|
|
UserName
|
统一身份认证用户名
|
返回类型：
类型说明：
|
FunctionCode
|
模块缩写
|
|
Value
|
值
|
6.6.获取统一省份认证账户或子系统关联账户
调用方法：
public string GetUserNameByToken(string TokenID)
请求参数：
返回类型：
类型说明：
6.7.根据令牌返回子系统用户名集合
调用方法：
public string GetMapUserNames(string TokenID, string AppCode)
请求参数：
返回类型：
类型说明：
|
string
|
子系统用户名集合，多个用户名由“，”分割，如"admin1,test1"
|
6.8.统一身份认证账户与子系统账户关联
调用方法：
public String RegistUserMap(string AppCode, string TokenID, string AppUserName,
string EncryptString)
请求参数：
|
AppCode
|
子系统缩写
|
|
TokenID
|
令牌
|
|
AppUserName
|
子系统用户名
|
|
EncryptString
|
加密字符串（=MD5（AppCode+TokenID+AppUserName+AppKey））
|
返回类型：
类型说明：
|
string
|
参考【7.Webservice 方法返回结果编码】
|
6.9.用户实名认证
调用方法：
public string RegistRealeUser(string AppCode, string TokenID, string AppUserName,
string EncryptString)
请求参数：
|
AppCode
|
子系统缩写
|
|
TokenID
|
令牌
|
|
AppUserName
|
子系统用户名
|
|
EncryptString
|
加密字符串（=MD5（AppCode+TokenID+AppUserName+AppKey））
|
返回类型：
类型说明：
|
string
|
参考【7.Webservice 方法返回结果编码】
|
6.10.根据用户名判断用户是否为实名用户
调用方法：
public bool IsRealNameByUserName(string UserName)
请求参数：
返回类型：
类型说明：
6.11.根据令牌判断用户是否为实名用户
调用方法：
public bool IsRealNameByTokenID(string TokenID)
请求参数：
返回类型：
类型说明：
6.12.获得该用户管理的组织机构信息
调用方法：
public List<string> GetOrgByUserName(string AppCode, string UserName, string
EncryptString)
请求参数：
|
AppCode
|
子系统缩写
|
|
UserName
|
统一身份认证用户名
|
|
EncryptString
|
加密字符串（=MD5（AppCode+UserName+AppKey））
|
返回类型：
类型说明：
6.13.获得子系统对用户信息的访问权限
调用方法：
public string GetUserInfoAccessFields(string AppCode)
请求参数：
返回类型：
类型说明：
7. Webservice 方法返回结果编码
编码说明：
|
OK
|
成功
|
|
101
|
无效AppCode
|
|
102
|
加密验证失败
|
|
103
|
令牌失效
|
|
104
|
不提供实名认证服务
|
|
105
|
是集成系统，不提供用户关系映射
|
8.统一权限管理接口说明
8.1统一权限管理简介
统一身份认证系统提供统一权限管理的功能，采用用户（User）+角色(Role)+模块(Module)+权限(Permission)的模式。统一身份认证系统为每个子系统都提供权限管理的功能，该功能主要涉及模块管理、角色管理、权限管理。子系统可以被划分成若干个功能模块，如用户管理、日志管理等，每个功能模块又可以细分成不同的权限，如用户管理模块中有添加用户、修改用户、删除用户等权限。
(1) 模块信息主要由以下信息组成：英文编号、模块名称
如：
|
UserManage
|
用户管理
|
|
RoleManage
|
角色管理
|
(2) 权限信息主要由以下信息组成：权限值（2的n次方的整数）、权限名称
如:用户管理有如下权限：查看、新增、修改、删除
如果某用户所在角色拥有上述四种操作权限，则其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
8.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 }
