接入在线文档

接入指南
- 接入前必读
- 认证返回属性说明
- 接口返回码说明
- CAS Client接入指南
  - JAVA版本
  - DOTNET版本
  - PHP版本
- Oauth接入指南
- RestFul API接入指南
- SAML接入指南
辅助接口

接入前必读

当要开始将应用接入统一身份认证时，请确认申请的应用是否已通过管理员审核通过
在应用申请填写应用基本信息时，填写的应用应用访问地址和端口，这里填写的是域名或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版本）示例代码下载

客户端配置

第一步：下载示例代码程序包，并将“lib”文件夹下所要依赖的包放置在WEB应用的“WEB-INF/lib”目录下。

第二步：修改web应用的web.xml，添加如下配置：

                                                    
<listener>
  <listener-class>
    org.jasig.cas.client.session.SingleSignOutHttpSessionListener
  </listener-class>
</listener>
<!--统一注销过滤器，最好配置在系统过滤器前面-->
<filter>
  <filter-name>CAS Single Sign Out Filter</filter-name>
  <filter-class>org.jasig.cas.client.session.SingleSignOutFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>CAS Single Sign Out Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
<!--认证过滤器配置开始-->
<filter>
  <filter-name>CAS Authentication Filter</filter-name>
  <filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>
  <!--修改正式的认证服务端地址-->
  <init-param>
    <param-name>casServerLoginUrl</param-name>
    <!--此处配置为认证真实地址-->
    <param-value>https://portal.zfsoft.com/cas/login</param-value>
  </init-param>
  <!--修改客户端ip和端口-->
  <init-param>
    <param-name>serverName</param-name>
    <!--此处修改为应用服务器地址,http://ip:端口即可-->
    <param-value>http://ip:端口</param-value>
  </init-param>
  <init-param>
    <param-name>acceptAnyProxy</param-name>
    <param-value>true</param-value>
  </init-param>
</filter>


<filter>
  <filter-name>CAS Validation Filter</filter-name>
  <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class>
  <!--配置正式的认证服务端地址-->
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>https://portal.zfsoft.com/cas</param-value>
  </init-param>
  <!--修改客户端ip和端口-->
  <init-param>
    <param-name>serverName</param-name>
    <!--此处修改为应用服务器地址,http://ip:端口即可-->
    <param-value>http://ip:端口</param-value>
  </init-param>
</filter>

<filter>
  <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
  <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class>
</filter>

<filter>
  <filter-name>CAS Assertion Thread Local Filter</filter-name>
  <filter-class>org.jasig.cas.client.util.AssertionThreadLocalFilter</filter-class>
</filter>

<filter-mapping>
  <filter-name>CAS Validation Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
  <filter-name>CAS Authentication Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
  <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<filter-mapping>
  <filter-name>CAS Assertion Thread Local Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<session-config>
　　<tracking-mode>COOKIE</tracking-mode>
</session-config>
<!--认证过滤器配置结束-->

第三步：将配置中标识“修改”的部分，按照说明修改正确。

第四步：登录操作:如当前应用已审核通过，可通过浏览器请求应用地址进行访问。如获取的用户属性出现中文乱码,可使用如下方法进行转码:String xm = new String(attributes.get("XM").toString().getBytes("ISO-8859-1"),"utf-8");


//登录测试接口
@RequestMapping("/login")
@ResponseBody
public String testLogin(HttpServletRequest request, HttpServletResponse response){
	request.getRemoteUser();   //单纯获取用户名

	// 如果要获取用户的更多信息，用如下方法：
	Assertion assertion = AssertionHolder.getAssertion();
	AttributePrincipal ap = assertion.getPrincipal();//获取AttributePrincipal对象，这是客户端对象
	String name = ap.getName();//获取登录用户名
	//获取Cas服务端返回的自定义用户数据
	Map<String,Object> attributes = ap.getAttributes();
	//获取Cas服务端返回的自定义数据
	String CODE = (String)attributes.get("CODE");
	String XM = (String)attributes.get("XM");
	String YHLX = (String)attributes.get("YHLX");
	String DWH = (String)attributes.get("DWH");
	String DWMC = (String)attributes.get("DWMC");
	String TENANTID = (String)attributes.get("TENANTID");
	String SIGNDATAID = (String)attributes.get("SIGNDATAID");
	String MSSPID = (String)attributes.get("MSSPID");
	StringBuilder builder = new StringBuilder();
	builder.append("用户名:").append(CODE)
			.append("姓名:").append(XM)
			.append("用户类型:").append(YHLX)
			.append("单位号:").append(DWH)
			.append("单位名称:").append(DWMC)
			.append("学校ID:").append(TENANTID);
			.append("CA证书SIGNDATAID:").append(SIGNDATAID);
			.append("CA证书MSSPID:").append(MSSPID);
	System.out.println(builder.toString());
	return builder.toString();
}

第五步: 登出操作:可采用超链接方式登出或接口调用方式,超链接方式只需将登出按钮配置超链接即可,可参考统一注销页面;接口调用方式参考示例代码如下:


//登出测试接口
@RequestMapping("/logout")
@ResponseBody
public void testLogout(HttpServletRequest request, HttpServletResponse response)throws IOException{
    HttpSession session = request.getSession();
    session.invalidate();
    //cas服务的退出地址，https://portal.zfsoft.com/cas为认证真实地址,cas为上下文，logout为固定值
    String casLogoutURL = "https://portal.zfsoft.com/cas/logout";
    //重定向到CAS服务端，退出成功之后CAS服务端重定向到service后面的地址，
    //service后面带的参数为应用的访问地址，需要使用URLEncoder进行编码,不写service的值，则默认跳转到CAS服务端指定的页面
    String redirectURL=casLogoutURL+"?service="+URLEncoder.encode("http://ip:port/login");
    response.sendRedirect(redirectURL);
}

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

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

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

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

CAS Client接入指南（DOTNET版本）示例代码下载

客户端配置

第一步：下载示例代码程序包，修改认证真实地址。

                                                    
using System;
using System.Collections.Generic;
using System.Net;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;
using System.IO;
using System.Xml;
using System.Text;

namespace SsoDemo
{
    public partial class login : System.Web.UI.Page
    {

        #region 此处配置为认证真实地址
        private readonly string casserver = "https://portal.zfsoft.com/cas";
        #endregion

        protected void Page_Load(object sender, EventArgs e)
        {
            string redirectUrl = Request.QueryString["redirectUrl"] ?? "/";
            if (Session["uid"] != null)
            {
                Response.Redirect(redirectUrl);
                return;
            }
            #region ticket较检
            string ticket = Request.QueryString["ticket"];
            //如果有tiket不存在，跳转到认证登陆页完成认证
            if (string.IsNullOrEmpty(ticket))
            {
                string service = Server.UrlEncode(Request.Url.ToString());
                Response.Redirect(casserver + "/login?service=" + service);
                return;
            }
            #endregion
            string validateService = Request.Url.ToString().Replace("?ticket=" + ticket, "");
            string validateUrl = casserver + "/serviceValidate?ticket=" + ticket + "&service=" + validateService;
            HttpWebRequest request = null;
            //如果是发送HTTPS请求  
            if (validateUrl.StartsWith("https", StringComparison.OrdinalIgnoreCase))
            {
                ServicePointManager.ServerCertificateValidationCallback = new RemoteCertificateValidationCallback(ignoreSSL);
                request = WebRequest.Create(validateUrl) as HttpWebRequest;
                request.ProtocolVersion = HttpVersion.Version10;
            }
            else
            {
                request = WebRequest.Create(validateUrl) as HttpWebRequest;
            }
            StreamReader reader = new StreamReader(request.GetResponse().GetResponseStream());
            string xml = reader.ReadToEnd();
            XmlDocument xd = new XmlDocument();
            xd.LoadXml(xml);
            XmlNamespaceManager xmlnsManager = new XmlNamespaceManager(xd.NameTable);
            xmlnsManager.AddNamespace("cas", xd.DocumentElement.GetNamespaceOfPrefix("cas"));
            #region 认证失败处理
            //如果出现authenticationFailure 则表示认证失败
            XmlNode failuerNode = xd.SelectSingleNode("//cas:authenticationFailure", xmlnsManager);

            if (failuerNode != null)
            {
                string errorMsg = failuerNode.InnerText;
                Response.Write(errorMsg); return;
            }
            #endregion
            #region 认证成功
            //认证成功
            XmlNode successNode = xd.SelectSingleNode("//cas:authenticationSuccess", xmlnsManager);
            //必然成功或失败，所以下面判断一般不会为真，
            if (successNode == null)
            {
                string errorMsg = "认证失败：验证出错";
                Response.Write(errorMsg); return;
            }
            XmlNode userNode = successNode.SelectSingleNode("//cas:user", xmlnsManager);

            //获取uid
            string uid = userNode.InnerText;
            XmlNode attributeNode = successNode.SelectSingleNode("//cas:attributes", xmlnsManager);

            //获得所有传递过来的用户属性
            Dictionary<string, string> userAttrs = new Dictionary<string, string>();
            foreach (XmlNode attr in attributeNode.ChildNodes)
            {
                userAttrs.Add(attr.LocalName, ConvertISO88591ToUTF8(attr.InnerText));
            }
            #endregion

            Session["uid"] = uid;
            Session["userAttr"] = userAttrs;
            Response.Redirect(redirectUrl);

        }
        private static bool ignoreSSL(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors errors)
        {
            return true;
        }

        private static string ConvertISO88591ToUTF8(string srcString)
        {
            Encoding iso = Encoding.GetEncoding("ISO-8859-1");
            Encoding utf8 = Encoding.UTF8;
            byte[] isoBytes = iso.GetBytes(srcString);
            byte[] utfBytes = Encoding.Convert(iso, utf8, isoBytes);
            string sResult = utf8.GetString(isoBytes);
            return sResult;
        }
    }
}

第二步：如当前应用已审核通过，可通过浏览器请求应用地址进行访问。

获取用户详细信息接口

                                                     

using System;
using System.Collections.Generic; 
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace SsoDemo
{
    public partial class _Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            if (Session["uid"] == null)
            {
                Response.Redirect("login.aspx?redirectUrl="+Request.RawUrl);
                return;
            }
            //获取用户名
            user.Text = Session["uid"].ToString();
            //获取用户的更多信息
            attr.DataSource = Session["userAttr"];
            attr.DataBind();
        }
    }
}

CAS Client接入指南（PHP版本）示例代码下载

客户端配置

第一步：下载示例代码程序包，并将“phpCAS”文件夹放置在应用目录下。

第二步：修改应用的配置文件config.php，添加如下配置，并按照说明修改正确：

                                                    
<?php

# 1 CAS Server 主机域名
# 此配置是你搭建的CAS SSO SERVER服务的域名
$cas_host = 'https//portal.zfsoft.com';

# 2 CAS Server 路径
# 此配置是你搭建的CAS SSO SERVER服务的路径
$cas_context = '/cas';

// 3 CAS server 端口
# 此配置是你搭建的CAS SSO SERVER服务的端口
$cas_port = 443;

// 4 CAS server 证书
# 此配置是你搭建的CAS SSO SERVER服务的证书文件
$cas_server_ca_cert_path = './ssoserver.cer';

第三步：如当前应用已审核通过，可通过浏览器请求应用地址进行访问。

获取用户详细信息接口

                                                     

<?php

# 1 引入配置文件 | CAS.PHP文件
require_once 'config.php';
require_once 'phpCas/CAS.php';

# 2 开启phpCAS debug
phpCAS::setDebug();

# 3 初始化phpCAS,参数说明：
# a) CAS协议版本号
# b) cas server的域名
# c) cas server的端口号
# d) cas server的项目访问路径
phpCAS::client(CAS_VERSION_2_0, $cas_host, $cas_port, $cas_context);

# 4 开启设置证书验证。如果是开发环境可将此注释，如果是生产环境为了安全性建议将此开启
// phpCAS::setCasServerCACert($cas_server_ca_cert_path);

# 5 不为CAS服务器设置SSL验证
# 为了快速测试，您可以禁用CAS服务器的SSL验证。此建议不建议用于生产环境。验证CAS服务器对CAS协议的安全性至关重要！
phpCAS::setNoCasServerValidation();

# 6 这里会检测服务器端的退出的通知，就能实现php和其他语言平台间同步登出了
# 处理登出请求。cas服务端会发送请求通知客户端。如果没有同步登出，可能是服务端跟客户端无法通信（比如我的客户端是localhost, 服务端在云上）
phpCAS::handleLogoutRequests();

# 7 进行CAS服务验证，这个方法确保用户是否验证过，如果没有验证则跳转到验证界面
# 这个是强制认证模式，查看 CAS.php 可以找到几种不同的方式：
# a) forceAuthentication - phpCAS::forceAuthentication();
# b) checkAuthentication - phpCAS::checkAuthentication();
# c) renewAuthentication - phpCAS::renewAuthentication();
# 根据自己需要调用即可。
$auth = phpCAS::forceAuthentication();
if ($auth) {
	# 8 验证通过，或者说已经登陆系统，可进行已经登陆之后的逻辑处理...
	# 获得登陆CAS用户的名称
	$user_name = phpCAS::getUser();
	echo $user_name . '已经成功登陆...<br>';
	
	# 9 你还可打印保存的phpCAS session信息
	print_r($_SESSION);
	
	# 10 还可获取有关已验证用户的属性,例如：$uid = phpCAS::getAttribute('id');
	$attr = phpCAS::getAttributes();
	print_r($attr);
	
	# 11 进行退出的相关操作
	# 在你的PHP项目中处理完相应的退出逻辑之后，还需执行phpCAS::logout()进行CAS系统的退出
	# 当我们访问cas服务端的logout的时候，cas服务器会发送post请求到各个已经登录的客户端
	//phpCAS::logout();
	
	# 登出方法一：登出成功后跳转的地址
	//phpCAS::setServerLoginUrl("https://portal.zfsoft.com/cas/logout?service=http://cas.wzh.com");
	//phpCAS::logout();
	# 登出方法二：退出登录后返回地址
	//$param = array("service" => "http://cas.wzh.com");
	//phpCAS::logout($param);
	
} else {
	# 12 验证未通过，说明未进行登陆
	# 将会跳转回你配置的CAS SSO SERVER服务的域名；
	# 例如：https://portal.zfsoft.com/cas/login?service=http%3A%2F%2Fcas.wzh.com%2F
	# 在你输入正确的用户名和密码之后CAS会自动跳转回service=http%3A%2F%2Fcas.wzh.com%2F此地址
	# 在此你可以处理验证未通过的各种逻辑
	echo '还未登陆，跳转到CAS进行登陆...<br>';
}

正在建设中...

OAuth接入指南示例代码下载

使用OAuth接入应用，授权码模式授权流程由如下三步完成接入：

第一步通过身份认证，获取code

第二步根据code获取access_token

第三步根据access_token获取用户信息

第一步：通过身份认证，获取code 通过构造授权认证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

参数说明：

参数	是否必须	说明

当出现如下页面,则表示参数client_id或redirect_uri有误,请确认后重新访问：

下图为用户授权界面：

当输入正确的口令认证通过后，页面将跳转至redirect_uri/?code=CODE&state=STATE

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

第二步：根据code获取access_token 这里注意，用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获取用户信息第三步：通过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

SP使用Shibboleth完成与IDP对接

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

第二步:配置SP shibboleth2.xml 在配置文件中，添加如下配置,重启SP服务即可<MetadataProvider type="XML" file="IDP.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

接入指南

辅助接口

接入前必读

认证返回属性说明

属性对照表如下：

全局返回码说明

全局返回码说明如下：

CAS Client接入指南（JAVA版本）示例代码下载

CAS Client接入指南（DOTNET版本）示例代码下载

CAS Client接入指南（PHP版本）示例代码下载

正在建设中...

正在建设中...

OAuth接入指南示例代码下载

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

SAML2.0接入指南

修改|找回密码

获取用户详细信息接口

统一注销

用户无权限统一跳转页面