接入在线文档

接入指南
- 接入前必读
- 认证返回属性说明
- 接口返回码说明
- CAS Client接入指南
  - JAVA版本
- 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://zjuam.zju.edu.cn/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://zjuam.zju.edu.cn/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>
<!--认证过滤器配置结束-->

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

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

获取用户详细信息接口

                                                     
request.getRemoteUser();   //单纯获取用户名

//如果要获取用户的更多信息，用如下方法：
Assertion assertion = AssertionHolder.getAssertion();

AttributePrincipal ap = assertion.getPrincipal();
//获取AttributePrincipal对象，这是客户端对象

String name = ap.getName();

Map att = ap.getAttributes(); //获取更多用户属性

正在建设中...

OAuth接入指南示例代码下载

使用OAuth接入应用，由如下三步完成接入：

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

第二步根据code获取access_token

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

第一步：通过身份认证，获取code 通过构造授权认证url并请求将跳转至用户身份授权地址，进行身份认证，参考链接如下： https://zjuam.zju.edu.cn/cas/oauth2.0/authorize?response_type=code&client_id=APPKEY&redirect_uri=REDIRECT_URI

注意：跳转回调redirect_uri，应当使用https链接来确保授权code的安全性

接口地址： https://zjuam.zju.edu.cn/cas/oauth2.0/authorize

请求方式： GET

参数说明：

参数	是否必须	说明

下图为用户授权界面：

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

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

第二步：根据code获取access_token 这里注意，用code换取的access_token与RestFul API中获取的token不同。构造获取access_token链接参考如下： https://zjuam.zju.edu.cn/cas/oauth2.0/accessToken?client_id=APPID&client_secret=SECRET&code=CODE&redirect_uri=REDIRECT_URI

接口地址： https://zjuam.zju.edu.cn/cas/oauth2.0/accessToken

请求方式： GET

参数说明：

参数	是否必须	说明

返回说明：

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

参数	说明

错误时返回的JSON数据包如下：

第三步：根据access_token获取用户信息第三步：通过access_token，构造获取身份信息链接请求，参考链接如下： https://zjuam.zju.edu.cn/cas/oauth2.0/profile?access_token=ACCESS_TOKEN

接口地址： https://zjuam.zju.edu.cn/cas/oauth2.0/profile

请求方式： GET

参数说明：

参数	是否必须	说明

返回说明：

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

错误时返回的JSON数据包如下：

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

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

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

调用身份认证接口，进行身份认证

接口地址： http://zuinfo.zju.edu.cn/v2/identify.zf

请求方式： POST

参数说明：

参数说明	参数	是否必须

返回说明：

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

参数	是否必须	说明

错误时返回的JSON数据包如下：

获取用户详细信息接口

接口地址： http://zuinfo.zju.edu.cn/v2/session.zf

请求方式： POST

参数说明：

参数	是否必须	说明

返回说明：

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

错误时返回的JSON数据包如下：

SAML2.0接入指南

使用SAML2.0接入应用，需要在应用申请时上传 service provider（SP） XML

identity provider(IDP) Metadata XML请求地址为https://zjuam.zju.edu.cn/idp/shibboleth

SP使用Shibboleth完成与IDP对接

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

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

修改|找回密码

修改|找回密码接口

接口地址： https://zuinfo.zju.edu.cn/v2/modifyPwd.zf

请求方式： POST

参数说明：

参数	是否必须	说明

返回说明：

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

错误时返回的JSON数据包如下：

获取用户详细信息接口

接口地址： https://zuinfo.zju.edu.cn/v2/getUserDetails.zf

请求方式： POST

参数说明：

参数	是否必须	说明

返回说明：

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

参数	是否必须	说明

错误时返回的JSON数据包如下：

统一注销

统一注销可以调用接口，或应用系统直接使用超链接即可
链接地址示例：
https://zjuam.zju.edu.cn/cas/logout?service=redirect_url

接入指南

辅助接口

接入前必读

认证返回属性说明

属性对照表如下：

全局返回码说明

全局返回码说明如下：

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

正在建设中...

正在建设中...

OAuth接入指南示例代码下载

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

SAML2.0接入指南

修改|找回密码

获取用户详细信息接口

统一注销