JAVA网站对接文档

简介

国双SSO Cas Java版SDK采用Cas官方提供的Java Apereo CAS Client。它的原理是使用Servlet过滤器实现，所以适用于大多数的Java开发的Web应用。它也会通过Api对与SSO进行请求、验证。

所有的依赖项都已经可以通过Maven管理，下面进行具体的说明。

构建工程

您可以通过克隆github上的项目自己构建工程打包。

git clone git@github.com:Jasig/java-cas-client.git
cd java-cas-client
mvn clean package

依赖项说明

依赖项: 核心功能，包括认证和验证过滤器。

<dependency>
    <groupId>org.jasig.cas.client</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>${java.cas.client.version}</version>
</dependency>

依赖项: SAML协议。（国双SSO Cas使用Cas2.0协议，可以不使用本项）

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-support-saml</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

依赖项: Atlassian集成。

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-integration-atlassian</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

依赖项: JBoss集成。

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-integration-jboss</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

依赖项: Tomcat 6集成。

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-integration-tomcat-v6</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

依赖项: Tomcat 7集成。

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-integration-tomcat-v7</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

依赖项: 分布式Ehcache缓存代理凭据。（非代理模式不必要）

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-support-distributed-ehcache</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

依赖项: 分布式Memcached缓存代理凭据。（非代理模式不必要）

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-client-support-distributed-memcached</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

配置说明

策略

SDK为开发者提供了多种配置方法

• JNDI (JNDI)
• Properties File (PROPERTY_FILE)。这种方式通过提供额外的properties文件来配置 (默认值为/etc/java-cas-client.properties)。示例：

<context-param>
  <param-name>configFileLocation</param-name>
  <param-value>/etc/config/file.properties</param-value>
</context-param>

• System Properties (SYSTEM_PROPERTIES)
• Web Context (WEB_XML)
• Default (DEFAULT)

策略名称需要在项目中指定：

<context-param>
    <param-name>configurationStrategy</param-name>
    <param-value>DEFAULT</param-value>
</context-param>

如果没有定义configurationStrategy会使用默认值WEB_XML和JNDI。

使用 web.xml 配置

可以通过web.xml中的context-param和过滤器的init-param来配置SDK。每个过滤器都有必需和可选属性。过滤器读取配置遵循以下配置：

• 检查过滤器配置的init-param匹配必需属性的属性名。
• 检查context-param匹配必需属性的属性名。
• 如果以上两种方法同时检测到某一属性，优先使用init-param。

这里是官方提供了一个示例。

org.jasig.cas.client.authentication.AuthenticationFilter

过滤器AuthenticationFilter

<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://sso-cas.gridsumdissector.com/login</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>http://xd.gridsumdissector.com</param-value>
  </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Authentication Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

属性说明:(未包含全部说明，其它可选配置，请参考官方说明)

casServerLoginUrl 必选

• 单点登陆表单位置URL。
• 使用https://sso-cas.gridsumdissector.com/login。

serverName 必选

• 当前网站的主机名。 这里的serverName的作用是生成在单点登陆系统登陆成功后会跳转到的URL，serverName必须是单点登陆系统可以解析的主机名。
• 如果网站应用使用负载均衡、SSL Offloader、或其它类型的设备来代替应用接收请求，则需要提供公共的主机。
• 协议前缀(http:// 或 https://)是可选的，建议添加相关协议。
• 如果使用的是非常规端口，如(XD.gridsumdissector.com:8888)，则必须包含在配置中。
• 请不要在末尾包含反斜杠。

renew 可选

• 强制用户在访问应用时，重新从单点登陆系统进行认证。
• 由于大部分不会有这样的需求，建议不使用。默认值为false。

gateway 可选

• 启用单点登陆系统网关功能。
• 功能尚未测试，建议不使用。默认值为false。

encodeServiceUrl 可选

• 是否对Url进行编码。
• 建议开启。默认值为true。

ignorePattern 可选

• 定义拦截认证请求时，忽略的url模式。

ignoreUrlPatternType 可选

• 指定忽略url的模式类型。
• 默认为REGEX，还支持CONTAINS/ EXACT。

org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter

使用CAS 2.0协议验证凭据。由于国双SSO Cas版采用CAS 2.0协议认证，所以没有提供其它协议（如SAML 1.1、CAS 1.0、CAS 3.0等）的配置方法 。如果在配置中提供了acceptAnyProxy和allowedProxyChains两个参数，Cas20ProxyTicketValidator会被创建（当网站做为代理模式时的验证器）；否则会创建Cas20ServiceTicketValidator。由于目前国双网站没有代理模式的需求，所以建议不要配置此两项参数。

<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://sso-internal.gridsumdissector.com</param-value>
    </init-param>
    <init-param>
        <param-name>serverName</param-name>
        <param-value>https://sso-cas.gridsumdissector.com/settings</param-value>
        <!--<param-value>http://xd.gridsumdissector.com</param-value>-->
    </init-param>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Validation Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

属性说明:(未包含全部说明，其它可选配置，请参考官方说明)

casServerUrlPrefix 必选

• 单点登陆系统URL前缀。
• 使用内网域名https://sso-internal.gridsumdissector.com/。
• 有关内网域名的使用，请参见内网域名的使用。

serverName 必选

• 当前网站的主机名。 这里的serverName的作用是生成在单点登陆系统登陆成功后会跳转到的URL，serverName必须是单点登陆系统可以解析的主机名。
• 如果网站应用使用负载均衡、SSL Offloader、或其它类型的设备来代替应用接收请求，则需要提供公共的主机。
• 协议前缀(http:// 或 https://)是可选的，建议添加相关协议。
• 如果使用的是非常规端口，如(XD.gridsumdissector.com:8888)，则必须包含在配置中。
• 请不要在末尾包含反斜杠。

encoding 可选

• 指定客户端接收SSO消息时的编码类型。
• 建议手动配置为utf-8，以免接收中文用户名出现乱码。

renew 可选

• 强制用户在访问应用时，重新从单点登陆系统进行认证。
• 由于大部分不会有这样的需求，建议不使用。默认值为false。

redirectAfterValidation 可选

• 在凭据认证过后，是否去掉ticket参数重定向到同一Url。
• 建议开启，不要将不必要的参数暴露在Url中。默认为true。

useSession 可选

• 是否将Assertion存储在Session中。
• 若不开启，每次请求都会验证凭据，请根据实际情况选择。默认为true。

exceptionOnValidationFailure 可选

• 在凭据认证失败时是否抛出一个异常。
• 默认为true。

org.jasig.cas.client.util.HttpServletRequestWrapperFilter

装饰HttpServletRequest，在使用方法getRemoteUser和getPrincipal时，可以得到SSO Cas返回的用户信息。

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

org.jasig.cas.client.util.AssertionThreadLocalFilter

将Assertion放进ThreadLocal中，以便在程序中某些情况使用。如在应用中某个处于”前置位”的过滤器想要获取用户信息，但无法访问到HttpServletRequest时，使用会更加方便。

<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 Assertion Thread Local Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

org.jasig.cas.client.util.ErrorRedirectFilter

在出现异常时重定向的配置。

<filter>
  <filter-name>CAS Error Redirect Filter</filter-name>
  <filter-class>org.jasig.cas.client.util.ErrorRedirectFilter</filter-class>
  <init-param>
    <param-name>java.lang.Exception</param-name>
    <param-value>/error.jsp</param-value>
  </init-param>
  <init-param>
    <param-name>defaultErrorRedirectPage</param-name>
    <param-value>/defaulterror.jsp</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>CAS Error Redirect Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

简单说明：

defaultErrorRedirectPage 必选

• 默认的重定向Url。

java.lang.Exception 可选

• 异常合法名全称。值也为重定向的Url。

使用 Spring 配置

在使用Spring中的网站配置SDK，需要依赖DelegatingFilterProxy类。每个过滤器在web.xml中都要有对应的DelegatingFilterProxy配置。

建议HttpServletRequestWrapperFilter和AssertionThreadLocalFilter这样无需配置参数的过滤器就直接配置在web.xml中吧。

<filter>
    <filter-name>CAS Authentication Filter</filter-name>
    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
    <init-param>
        <param-name>targetBeanName</param-name>
        <param-value>authenticationFilter</param-value>
    </init-param>
  </filter>
<filter-mapping>
    <filter-name>CAS Authentication Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

下面是Bean的一个示例配置。

AuthenticationFilter

<bean
    name="authenticationFilter"
    class="org.jasig.cas.client.authentication.AuthenticationFilter"
    p:casServerLoginUrl="https://sso-cas.gridsumdissector.com/login"
    p:renew="false"
    p:gateway="false"
    p:service="http://xd.gridsumdissector.com" />

Cas20ProxyReceivingTicketValidationFilter

<bean
    name="ticketValidationFilter"
    class="org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter"
    p:service="http://xd.gridsumdissector.com">
    <property name="ticketValidator">
        <bean class="org.jasig.cas.client.validation.Cas20ServiceTicketValidator">
            <constructor-arg index="0" value="https://sso-internal.gridsumdissector.com" />
            <property name="encoding" value="utf-8" />
        </bean>
    </property>
</bean>

使用 JNDI 配置

使用JNDI配置与使用web.xml配置本质上相同的，只是JNDI没有写在web.xml中。

按照惯例：

• JNDI会首先查找java:comp/env/cas/{SHORT FILTER NAME}/{PROPERTY NAME}(i.e. java:comp/env/cas/AuthenticationFilter/serverName)
• JNDI最后会查找java:comp/env/cas/{PROPERTY NAME}(i.e. java:comp/env/cas/serverName)

示例

<?xml version="1.0" encoding="UTF-8"?>
<Context antiResourceLocking="false" privileged="true">

<Environment description="Server Name" name="cas/serverName" override="false"
type="java.lang.String" value="http://xd.gridsumdissector.com"/>

<Environment description="CAS Login Url" name="cas/AuthenticationFilter/casServerLoginUrl" override="false"
type="java.lang.String" value="https://sso-cas.gridsumdissector.com/login"/>

<Environment description="CAS Url Prefix" name="cas/Cas20ProxyReceivingTicketValidationFilter/casServerUrlPrefix" override="false"
type="java.lang.String" value="https://sso-cas.gridsumdissector.com"/>
</Context>

配置单点登出

单点登出通过配置一个SingleSignOutFilter过滤器和一个ContextListener监听器实现。请确保单点登出的过滤器配置在其它过滤器之前。

<filter>
    <filter-name>CAS Single Sign Out Filter</filter-name>
    <filter-class>org.jasig.cas.client.session.SingleSignOutFilter</filter-class>
    <init-param>
        <param-name>casServerUrlPrefix</param-name>
        <param-value>https://sso-cas.gridsumdissector.com</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Single Sign Out Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
<listener>
    <listener-class>org.jasig.cas.client.session.SingleSignOutHttpSessionListener</listener-class>
</listener>

推荐的登出方式

在SDK中没有提供代码来帮助客户端登出，所以我们建议使用session.invalidate()的方式，通过注销session来使得当前会话失效，再通过重定向到https://sso-cas.gridsumdissector.com/logout?service={YOUR_SERVER}。

当然这只是建议，您可以根据自己网站的实际情况来选择登出方式。

其它配置方式

以上我们介绍了较为常用的配置方式，还有其它的方式：

• 使用JAAS配置
• 使用JBoss集成
• 使用Tomcat 6/7集成
• 使用Atlassian集成
• 使用Spring Security集成

这些方式在GitHub/java-cas-client都有说明，但由于我们没有一一配置测试过，所以这里不再提供说明，如有需要，请参阅官方文档。