Online Documentation

接入在线文档

接入前必读

当要开始将应用接入统一身份认证时,请确认申请的应用是否已通过管理员审核通过
在应用申请填写应用基本信息时,填写的应用应用访问地址和端口,这里填写的是域名或ip,而不是URL,请勿加http://等协议头。
比如填写的应用访问地址和域名为,t.edu.cn,在使用CAS Client或OAuth进行接入或鉴权时,访问此服务器域名下的http://t.edu.cn/main.do、http://t.edu.cn/login.htm都可进行接入或鉴权,而不被拦截。而http://t2.zju.edu.cn下的请求无法接入或鉴权
应用审核通过后,会为应用生成唯一的appkey和appsecret,开发者可使用它们选择合适的方式接入,也可进行接口调用。
根据应用申请时选择的接入方式,查看相应的接入指南,也可下载相应语言的示例代码进行本地调试。

认证返回属性说明

统一身份认证成功后,将携带应用申请时需要返回的属性,供应用端获取。

属性对照表如下:
字段英文 中文名称

全局返回码说明

在正式接入、调试或调用接口时,可能获得正确或错误的返回码,开发者可以根据返回码信息调试接口,排查错误。

全局返回码说明如下:
返回码 说明

CAS Client接入指南(JAVA版本)示例代码下载

客户端配置
                                                    

注意:该代码示例基于session方式,业务系统可根据实际情况自行修改

统一注销过滤器和统一注销监听器必须配置,且统一注销过滤器必须配置在所有过滤器之前

应用接入申请时配置的应用登出地址必须是系统真实存在的,且必须被认统一注销过滤器拦截

认证服务器和应用服务器可以双向访问

CAS Client接入指南(DOTNET版本)示例代码下载

客户端配置
                                                    

获取用户详细信息接口
                                                     

CAS Client接入指南(PHP版本)示例代码下载

客户端配置
                                                    

获取用户详细信息接口
                                                     

正在建设中...

正在建设中...

OAuth接入指南示例代码下载

使用OAuth接入应用,授权码模式授权流程由如下三步完成接入:
第一步通过身份认证,获取code
第二步根据code获取access_token
第三步根据access_token获取用户信息
通过构造授权认证url并请求将跳转至用户身份授权地址,进行身份认证,参考链接如下: https://portal.zfsoft.com/cas/oauth2.0/authorize?response_type=code&client_id=APPKEY&redirect_uri=REDIRECT_URI

注意:该链接请放入浏览器地址栏进行调试,不能简单使用postman等工具调试;跳转回调redirect_uri,应当使用https链接来确保授权code的安全性

https://portal.zfsoft.com/cas/oauth2.0/authorize
https://portal.zfsoft.com/cas为认证服务器的ip地址和端口(或域名:端口)
GET
参数 是否必须 说明
当输入正确的口令认证通过后,页面将跳转至redirect_uri/?code=CODE&state=STATE

注意:为授权安全,code只能使用一次,并且有效期为10秒,未被使用将自动过期

这里注意,用code换取的access_token与RestFul API中获取的token不同。构造获取access_token链接参考如下: https://portal.zfsoft.com/cas/oauth2.0/accessToken?client_id=APPID&client_secret=SECRET&code=CODE&redirect_uri=REDIRECT_URI
https://portal.zfsoft.com/cas/oauth2.0/accessToken
GET
参数 是否必须 说明

正确时返回的JSON数据包如下:

参数 说明

错误时返回的JSON数据包如下,其中errorcode为接口返回码,具体说明请参考全局返回码说明

第三步:通过access_token,构造获取身份信息链接请求,参考链接如下: https://portal.zfsoft.com/cas/oauth2.0/profile?access_token=ACCESS_TOKEN
https://portal.zfsoft.com/cas/oauth2.0/profile
GET
参数 是否必须 说明

正确时返回的JSON数据包如下:

参数 说明

错误时返回的JSON数据包如下,其中errorcode为接口返回码,具体说明请参考全局返回码说明

RestFul API接入指南示例代码下载

使用RestFul AP接入应用,只需调用相应接口即可完成接入。

1、我们提供接口的方式认证用户,此方式不支持单点进入业务系统,需应用方认证成功后进行处理。
2、根据身份认证接口,校验用户身份信息,校验完成后获取用户详细信息,信息获取完成后进行应用方自己的业务处理。

http://portal.zfsoft.com:8080/im/v2/identify.zf
POST
参数说明 参数 是否必须

正确时返回的JSON数据包如下:

参数 是否必须 说明

错误时返回的JSON数据包如下,其中errorcode为接口返回码,具体说明请参考全局返回码说明

http://portal.zfsoft.com:8080/im/v2/session.zf
POST
参数 是否必须 说明

正确时返回的JSON数据包如下:

错误时返回的JSON数据包如下,其中errorcode为接口返回码,具体说明请参考全局返回码说明

SAML2.0接入指南

使用SAML2.0接入应用,需要在应用申请时上传 service provider(SP) XML

identity provider(IDP) Metadata XML请求地址为https://portal.zfsoft.com/cas/idp/shibboleth

第一步:通过如上给出的IDP XML请求地址,下载IDP Metadata配置文件

第二步:配置SP shibboleth2.xml

修改|找回密码

修改|找回密码接口
http://portal.zfsoft.com:8080/im/v2/modifyPwd.zf
POST
参数 是否必须 说明

正确时返回的JSON数据包如下:

错误时返回的JSON数据包如下,其中errorcode为接口返回码,具体说明请参考全局返回码说明

获取用户详细信息接口

获取用户详细信息接口
http://portal.zfsoft.com:8080/im/v2/getUserDetails.zf
POST
参数 是否必须 说明

正确时返回的JSON数据包如下:

参数 是否必须 说明

错误时返回的JSON数据包如下,其中errorcode为接口返回码,具体说明请参考全局返回码说明

统一注销

统一注销可以调用接口,或应用系统直接使用超链接即可
链接地址示例:
https://portal.zfsoft.com/cas/logout?service=redirect_url

service后面带的参数为应用的访问地址,需要使用URLEncoder进行编码,不写service的值,则默认跳转到CAS服务端指定的页面

用户无权限统一跳转页面

第三方系统用户无权限统一展示页面,可以将下图替换第三方应用的跳转页面图片,或重定向链接到本系统的页面
https://portal.zfsoft.com/cas/noAuthority.html