浙江政务服务网SSO接口规范标准.docx
《浙江政务服务网SSO接口规范标准.docx》由会员分享,可在线阅读,更多相关《浙江政务服务网SSO接口规范标准.docx(74页珍藏版)》请在冰豆网上搜索。
浙江政务服务网SSO接口规范标准
卷号
usp4.12
卷内编号
密级
项目编号:
usp4.12
SSO接口规范
本文档使用部门:
■主管领导■项目组
□客户(市场)□维护人员■用户
修订历史记录
日期
版本
AMD
修订内容简述
修订人
备注
2012-3-17
4.2
A
周旭光
注:
A-添加,M-修改,D-删除
1.目的
本规范详细定义了SSO对外提供接口规范和调用方法。
约定
⏹方法名区分大小写,参数名均是小写。
⏹SSO系统同时支持两种数据格式xml和json。
接入资源只要实现一种格式即可
⏹WebService接口返回值(还有args参数)json或者xml格式传输:
1.XML返回格式如下:
对象格式:
xmlversion=“1.0”encoding=“UTF-8”?
>
zhangs
张三
列表格式:
xmlversion=“1.0”encoding=“UTF-8”?
>
2
2.JSON返回格式如下:
对象格式
{“loginname”:
”zhangs”}
列表格式
{“total”:
2,”user”:
[{“loginname”:
”zhangs”,”username”:
”张三”},{“loginname”:
”lisi”,”username”:
”李四”}]}
⏹接口类型:
本文档支持webservice、http、js三种接口类型。
一个接口可能同时支持一种或者多种类型。
⏹注:
接入资源的接口方式为http方式时,需要设置编码方式。
HTTPcontentType设置成text/xml如:
response.setContentType(“text/xml;charset=utf-8”);
⏹如果采用http方式,请增加参数method,值为方法名字。
⏹后缀域名相同的组织所拥有的用户名必须唯一。
⏹用户只能在后缀域名相同的组织之间进行调换。
⏹组织以orgcoding为唯一主键。
⏹认证参数:
servicecode与servicepwd由SSO管理员在SSO注册接入资源之后,提供给接入资源。
2.SSOAPI接口
2.1.用户管理
2.1.1.用户增加修改
2.1.1.1.接口说明
该接口是实现接入资源用户信息到SSO同步的接口规范。
由SSO提供接口,接入资源(webservice客户端)调用SSO(webservice服务端)接口主动将用户信息推给SSO。
2.1.1.2.接口类型
webservice/http
2.1.1.3.接口方法
synchronizeUser
2.1.1.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
args
参数集合。
由json或者xml格式组成。
该参数是动态参数,每次传递的将是必填参数和修改的参数。
如修改了组织名,则只传递组织名和必填参数。
(对象格式)
是
String
无限制
datatype
数据格式0xml1json
是
String
≤10
describe
修改说明
否
String
≤255
Args参数由如下:
名称
说明
是否必填
数据类型
长度
username
用户的真实姓名(新增时,不能为空)
否
String
≤255
loginname
登录名
是
String
≤255
encryptiontype
密码加密类型
值为:
1.表示明文
2.表示Base64(UTF-8字符集操作)
3.MD5(标准32位小写)
4.AES(sun自带库加密,密钥【servicepwd】为SSO提供)
5.3DES(sun自带库加密,密钥【servicepwd】为SSO提供)
否
String
1
loginpwd
密码(编辑统一用户时为空默认为原密码)
否
String
≤255
email
邮件
否
String
≤255
mobile
手机号码(常用手机)
否
String
11
mobile2
手机号码2(备用手机)
否
String
11
telephone
座机号码(常用电话)
否
String
11
telephone2
座机号码2(备用电话)
否
String
11
virtualnum
虚拟网号
否
String
11
postcode
邮编
否
String
≤255
cakey
CA证书KEY
否
String
≤255
sex
性别1男2女
默认为1
否
String
1
birthday
生日
否
String
≤255
country
国籍
否
String
≤255
province
省籍
否
String
≤255
city
城市
否
String
≤255
officeaddress
办公地址
否
String
≤255
officenum
办公室号
否
String
11
officephone
办公电话
否
String
≤255
officefax
办公传真
否
String
≤255
homephone
家庭电话
否
String
≤255
homeaddress
家庭地址
否
String
≤255
idtype
证件类型证件类型
1身份证2.护照3.军官证4.士兵证5.户口簿默认为1.身份证
否
String
1
idnum
证件号码
否
String
≤18
useable
用户激活状态1激活,2未激活
默认为:
1激活
否
String
1
orderby
排序
否
String
无符号Integer整型
headpicture
头像地址:
http:
//[sso4]/[headpicture]
注意:
该地址为外网能访问的地址
否
String
≤255
2.1.1.5.返回参数
名称
说明
数据类型
长度(字节)
result
结果:
0:
同步成功(等待管理员审核)(针对接入系统设置审核)
2001:
接入资源未被允许同步
2002:
接入资源不是统一用户体系
2003:
接入资源无权操作该用户
2004:
登录名非法(正则表达是配置)
2005:
用户所在组织(部门)不存在
2006:
排序号为非数字
2007:
loginpwd参数不能为空
2008:
orgcoding不规范
2009:
用户被锁定,信息不能修改。
2010:
已经存在相同登录名
2011:
用户调动组织,用户不存在。
2012:
args参数非法
2013:
用户类型错误
2014:
不支持的密码加密类型
2015:
密码解密出错
2016:
用户调整组织发生错误
2017:
username参数不能为空
2018:
常用电话已经存在
2019:
常用电话不能为空
2099:
其他错误
String
errmsg
错误说明
String
2.1.2.根据SSO用户id获取用户详细信息
2.1.2.1.接口说明
该接口是实现接入资源到SSO获取用户相关详细信息。
只能获取接入资源中的用户信息。
2.1.2.2.接口类型
webservice/http
2.1.2.3.接口方法
getUserInfoById
2.1.2.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
userid
用户在SSO的身份唯一标示
是
String
≤255
datatype
数据格式xmljson。
默认xml
是
String
≤10
2.1.2.5.返回参数
失败返回
名称
说明
数据类型
长度(字节)
result
结果:
0:
成功
2801:
接入资源不是统一用户体系
2802:
接入资源无权操作该用户
2803:
userid非法
2804:
不存在的用户
2899:
其他错误
String
errmsg
错误说明
String
userid
用户在SSO分配的身份唯一号
String
32
username
用户的真实姓名
String
≤255
loginname
登录名
String
≤255
email
邮件
String
≤255
mobile
手机号码
String
11
postcode
邮编
String
≤255
cakey
CA证书KEY
String
≤255
sex
性别1男2女
String
1
birthday
生日
String
≤255
country
国籍
String
≤255
province
省籍
String
≤255
city
城市
String
≤255
officeaddress
办公地址
String
≤255
officephone
办公电话
String
≤255
officefax
办公传真
String
≤255
homephone
家庭电话
String
≤255
homeaddress
家庭地址
String
≤255
idtype
证件类型证件类型
1身份证2.护照3.军官证4.士兵证5.户口簿默认为1.身份证
String
1
idnum
证件号码
String
≤18
useable
用户激活状态1激活,2未激活
String
1
orderby
排序
String
Int类型
headpicture
头像地址:
http:
//[sso4]/[headpicture]
注意:
该地址为外网能访问的地址
String
≤255
2.2.认证和单点登录标准接口(commnetAuth)
2.3认证和单点登录标准接口的调用地址。
其中未对功能指定地址的默认使用以下地址
Webservice地址:
http:
//[ip]:
[port]/[sso4]/service/SsoAuthService?
wsdl
http地址:
http:
//[ip]:
[port]/[sso4]/servlet/ssoauth
2.2.1.票据认证
2.2.1.1.接口说明
该接口是实现接入资源验证临时票据的有效性。
如果有效,将返回绑定该票据的用户信息
2.2.1.2.接口类型
webservice/http
2.2.1.3.接口方法
ticketValidation
2.2.1.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
st
票据
是
Strng
32
datatype
数据格式xmljson。
默认xml
是
String
≤10
2.2.1.5.返回参数
认证失败返回:
名称
说明
数据类型
长度(字节)
result
结果:
0:
成功
3001:
st已经超时失效
3002:
st不是票据类型
3003:
st不属于该接入资源
3004:
st格式不对
3099:
其他错误
errmsg
错误说明
String
authcode
授权码(一次性,有效时间一分钟)
String
≤255
loginname
登录的用户名
String
≤255
username
用户姓名
String
≤255
maploginname
如果是映射系统,并且配置了映射用户,则返回该映射系统配置的映射用户登录名
memo
其它附加字段
String
≤255
2.2.2.根据授权码获取令牌
2.2.2.1.接口说明
该接口是实现接入资源使用授权码获取接入资源令牌、刷新令牌、代理令牌等票据信息。
代理令牌必须接入拥有代理权才返回
2.2.2.2.接口类型
webservice/http
2.2.2.3.接口方法
getToken
2.2.2.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
authcode
授权码
是
Strng
32
datatype
数据格式xmljson。
默认xml
是
String
≤10
2.2.2.5.返回参数
认证失败返回:
名称
说明
数据类型
长度(字节)
result
结果:
0:
成功
3101:
授权码已经超时失效
3102:
不是有效的授权码类型
3103:
授权码不属于该接入资源
3104:
授权码格式不对
3199:
其他错误
errmsg
错误说明
String
accesstoken
访问令牌
String
32
accvalidtime
访问令牌存在时间单位:
秒
String
refreshtoken
刷新令牌
String
32
refreshvalidtime
刷新令牌存在时间单位:
秒
String
proxytoken
代理令牌(拥有代理权的接入资源才返回)
String
32
proxyvalidtime
代理令牌存在时间单位:
秒
String
2.2.3.更新接入资源令牌
2.2.3.1.接口说明
该接口是实现接入资源使用刷新令牌,更新将要过期的接入资源令牌,获取最新的接入资源令牌。
2.2.3.2.接口类型
webservice/http
2.2.3.3.接口方法
refAccessToken
2.2.3.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
refreshtoken
刷新令牌
是
Strng
32
datatype
数据格式xmljson。
默认xml
是
String
≤10
2.2.3.5.返回参数
认证失败返回:
名称
说明
数据类型
长度(字节)
result
结果:
0:
成功
3201:
刷新令牌已经超时失效
3202:
该令牌不是刷新令牌
3203:
刷新令牌不属于该接入资源
3204:
刷新令牌格式不对
3299:
其他错误
errmsg
错误说明
String
accesstoken
访问令牌
String
32
accvalidtime
访问令牌存在时间单位:
秒
String
proxytoken
代理令牌(拥有代理权的接入资源才返回)
String
32
proxyvalidtime
代理令牌存在时间单位:
秒
String
2.2.4.根据代理令牌获取第三方接入资源票据
2.2.4.1.接口说明
该接口是实现接入资源使用刷新令牌,更新将要过期的接入资源令牌,获取最新的接入资源令牌。
2.2.4.2.接口类型
webservice/http
2.2.4.3.接口方法
generateST
2.2.4.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
proxyapp
被代理接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
32
proxytoken
代理令牌
是
Strng
32
datatype
数据格式xmljson。
默认xml
是
String
≤10
2.2.4.5.返回参数
认证失败返回:
名称
说明
数据类型
长度(字节)
result
结果:
0:
成功
3301:
代理令牌已经超时失效
3302:
被代理接入资源不存在
3303:
被代理系统不存在该用户
3304:
该令牌不属于代理令牌
3305:
接入资源没有代理权
3306:
代理令牌不属于该接入资源
3307:
代理令牌格式不对
3399:
其他错误
errmsg
错误说明
String
st
被代理接入资源票据
String
32
2.2.5.根据访问令牌获取票据
2.2.5.1.接口说明
该接口是实现接入资源使用刷新令牌,更新将要过期的接入资源令牌,获取最新的接入资源令牌。
2.2.5.2.接口类型
webservice/http
2.2.5.3.接口方法
getST
2.2.5.4.输入参数
Webservice参数列表:
名称
说明
是否必填
数据类型
长度(字节)
servicecode
接入资源在SSO注册成功后的业务代码,由【SSO管理员】提供。
是
String
无限制
time
时间戳,当前时间
年月日时分秒
例:
2009年10月10日12时12分12秒格式为20091010121212
是
String
14
sign
MD5(servicecode+servicepwd+time),将业务代码、业务密钥、发送时间按顺序连接并进行md5加密。
注:
1、参数servicepwd由【SSO管理员】提供;2、MD5算法是标准算法,可使用java内部实现;3、MD5后的值为32位并且小写。
是
String
32
accesstoken
访问令牌
是
Strng
32
datatype
数据格式xmljson。
默认xml
是
String
≤10
2.2.5.5.返回参数
认证失败返回:
名称
说明
数据类型
长度(字节)
result
结果:
0:
成功
3701:
访问令牌已经超时失效
3702:
该令牌不属于访问令牌
3703:
访问令牌不属于该接入资源
3704:
访问令牌格式不对
3799:
其他错误
errmsg
错误说明
String
st
票据
String
32
2.2.6.用户认证
2.2.6.1.接口说明