1. 项目概述为什么是CAS 5.3在分布式系统和微服务架构成为主流的今天身份认证与授权Authentication Authorization是每个开发者绕不开的核心议题。单点登录SSO作为解决多系统间用户身份统一认证的成熟方案其重要性不言而喻。而当我们谈论开源的单点登录解决方案时Apereo CASCentral Authentication Service几乎是绕不开的名字。它历史悠久、功能强大、社区活跃是企业级SSO的标杆之一。我选择CAS 5.3.x这个版本作为切入点是因为它是一个承上启下的关键版本。CAS 5.x系列相较于早期的3.x、4.x在架构上进行了彻底的重构拥抱了Spring Boot使得部署和定制化变得前所未有的简单。而5.3.x版本在5.x系列中已经相当成熟和稳定修复了大量早期5.x版本的Bug同时引入了许多对现代开发友好的特性比如对OAuth 2.0、OpenID Connect更完善的支持以及更灵活的属性管理和服务注册表配置。对于大多数从零开始构建SSO体系或者从老旧版本升级的团队来说5.3.x是一个风险可控、功能完备的绝佳起点。简单来说部署和使用CAS 5.3就是为你的一系列应用无论是Java EE的老系统还是Spring Cloud的新服务建立一个统一、安全、可扩展的“门户保安”。用户只需登录一次即可畅通无阻地访问所有接入的应用极大地提升了用户体验和系统安全性。接下来我将从零开始带你完成一次完整的CAS 5.3部署并深入其核心配置与使用。2. 部署环境准备与构建选择在动手敲命令之前理清部署思路和选择合适的构建方式至关重要。CAS 5.3提供了多种部署形态我们需要根据自身的技术栈和运维习惯做出选择。2.1 核心依赖与环境清单无论选择哪种方式以下基础环境是必须的Java环境CAS 5.3.x官方推荐使用JDK 8或JDK 11。我个人强烈建议使用JDK 11LTS版本它在性能、内存管理和后续兼容性上表现更好。确保JAVA_HOME环境变量正确配置。构建工具CAS官方主推基于Gradle的Overlay构建方式。这也是本文重点介绍的方式。你需要安装Gradle版本兼容即可如6.x, 7.x或者直接使用Gradle Wrapper项目自带。版本控制强烈建议使用Git来管理你的定制化配置。操作系统Linux如CentOS 7/Ubuntu 18.04是生产环境首选。Windows或macOS可用于开发测试。2.2 构建方式选型为什么推荐OverlayCAS项目本身是一个庞大的、高度可配置的Web应用。官方不建议直接修改其庞大的源代码库。取而代之的是“Overlay”模式。你可以把它理解为一个“模板项目”或“基础镜像”。原理你从一个官方的、空白的CAS Overlay模板项目开始。这个模板预定义了所有依赖和基础结构。你的所有定制——无论是修改配置文件、添加第三方依赖如数据库驱动、Redis连接器还是替换UI页面——都只发生在你这个Overlay项目中。好处关注点分离你的代码只包含定制部分与CAS核心代码完全隔离。易于升级升级CAS版本时你只需更新Overlay模板中定义的CAS核心版本号然后重新构建即可。你的定制化配置大部分可以保留。清晰明了项目结构干净所有自定义内容一目了然。因此我们接下来的所有步骤都将基于Gradle Overlay项目展开。注意网络上可能还存在基于Maven或直接下载WAR包的部署教程。对于CAS 5.xOverlay是官方最佳实践能避免大量路径和依赖冲突问题请务必遵循。3. 基于Gradle Overlay的详细部署流程现在我们进入实战环节。假设我们的工作目录是/opt/cas。3.1 获取并初始化Overlay项目首先从CAS官方仓库获取Overlay模板。这里我们使用5.3.x系列的一个具体版本例如5.3.16。# 进入工作目录 cd /opt # 使用官方提供的初始化脚本推荐 # 这会下载对应版本的模板并解压 wget https://github.com/apereo/cas-overlay-template/archive/refs/tags/v5.3.16.zip unzip v5.3.16.zip mv cas-overlay-template-5.3.16 cas cd cas # 或者你也可以直接克隆整个模板仓库然后切换到对应tag # git clone https://github.com/apereo/cas-overlay-template.git cas # cd cas # git checkout 5.3.16执行完毕后你会看到一个标准的Gradle项目目录结构关键文件如下build.gradle项目构建文件定义依赖和插件。src/main/resources/配置文件目录初始可能是空的或有一些示例。src/main/webapp/Web静态资源目录如CSS, JS, 图片。gradlew和gradlew.batGradle包装器脚本用于统一构建环境。3.2 核心配置详解application.yml与cas.propertiesCAS的配置是重中之重。5.x版本支持多种配置格式推荐使用application.yml层次清晰或application.properties。我们以application.yml为例在src/main/resources目录下创建它。一个最小化但可运行的配置需要定义服务器端口、SSLHTTPS以及一个静态的服务注册列表用于测试。# src/main/resources/application.yml server: port: 8443 ssl: enabled: true key-store: file:/etc/cas/thekeystore key-store-password: changeit key-password: changeit cas: server: name: https://cas.example.org:8443 serviceRegistry: initFromJson: true logging: level: org.apereo.cas: INFO配置解析与实操要点SSL配置HTTPSCAS强制要求HTTPS这是安全的基础。你需要一个Keystore文件。生成测试Keystore仅用于开发/测试keytool -genkey -alias cas -keyalg RSA -keysize 2048 -keystore /etc/cas/thekeystore -validity 3650执行命令后会交互式地询问一些信息名字与姓氏最重要应输入你访问CAS的域名或IP如cas.example.org或localhost最后设置密码如changeit。请确保application.yml中的路径和密码与此一致。生产环境必须使用由可信CA如Let‘s Encrypt签发的正式证书。可以将证书导入到Keystore中或直接配置server.ssl.key-store指向你的证书文件。cas.server.name这是CAS服务器对外提供服务的基准URL必须与用户浏览器访问的地址一致且必须是HTTPS。所有重定向和票据生成都基于此URL。服务注册表initFromJson: true告诉CAS从JSON文件加载注册的服务即允许使用CAS登录的应用。我们接下来创建这个文件。3.3 注册第一个应用服务在src/main/resources/services目录下创建一个JSON文件例如MyWebApp-10000001.json。文件名格式有要求通常以-数字ID.json结尾。{ class: org.apereo.cas.services.RegexRegisteredService, serviceId: ^(https|http)://app1.example.org/.*, name: MyWebApp, id: 10000001, description: 这是我的第一个接入CAS的应用, evaluationOrder: 1, logoutType: BACK_CHANNEL, attributeReleasePolicy: { class: org.apereo.cas.services.ReturnAllowedAttributeReleasePolicy, allowedAttributes: [email, displayName] } }配置解析class指定服务注册的实现类RegexRegisteredService表示使用正则表达式匹配服务URL。serviceId一个正则表达式匹配允许使用此CAS服务的应用URL。例如^(https|http)://app1.example.org/.*匹配所有以app1.example.org开头的HTTP/HTTPS请求。这是安全的关键必须精确控制。id服务的唯一数字ID不能重复。evaluationOrder评估顺序数字越小优先级越高。logoutType登出类型BACK_CHANNEL表示CAS服务器会主动向后端服务发送登出请求单点登出。attributeReleasePolicy属性释放策略定义CAS在认证成功后可以传递哪些用户属性如邮箱、显示名给该服务。这实现了基础的授权信息传递。3.4 构建与运行配置完成后就可以构建并运行CAS了。# 在项目根目录 (/opt/cas) 下执行 # 方式一使用Gradle Wrapper进行构建并生成可执行WAR ./gradlew clean build # 构建成功后会在 build/libs/ 目录下生成一个 cas.war 文件。 # 方式二直接使用Gradle BootRun任务运行适合开发调试 ./gradlew bootRun如果使用bootRun控制台会输出日志启动成功后你可以通过https://localhost:8443/cas/login访问CAS的登录页面。默认用户名/密码是casuser/Mellon。第一次登录实操心得启动后访问登录页可能会遇到SSL证书警告因为用的是自签名证书在浏览器中选择“继续前往”或“接受风险”即可。成功登录后你会看到一个简单的CAS欢迎页面上面会显示你的登录状态和一些基本信息。这证明CAS服务器本身已经成功运行。4. 深入核心功能配置与集成一个基础的CAS服务器跑起来了但这远远不够。接下来我们要让它变得有用即与各种存储后端和认证源集成。4.1 认证源集成从静态用户到数据库默认的静态用户casuser/Mellon仅用于测试。生产环境必须连接真实的用户存储。4.1.1 集成JDBCMySQL/PostgreSQL假设我们使用MySQL。首先在build.gradle的dependencies部分添加JDBC和MySQL驱动依赖dependencies { // 其他依赖... implementation org.apereo.cas:cas-server-support-jdbc:${project.cas.version} implementation mysql:mysql-connector-java:8.0.33 }然后在application.yml中添加数据源和查询配置cas: authn: jdbc: query: - driver-class: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/your_auth_db?useUnicodetruecharacterEncodingUTF-8serverTimezoneUTC user: db_user password: db_password field-password: password # 数据库表中密码字段名 field-expired: expired field-disabled: disabled sql: SELECT * FROM users WHERE username ? password-encoder: type: DEFAULT # 或 BCRYPT, SSHA 等需与数据库中存储的密码格式匹配 encoding-algorithm: MD5 # 如果密码是MD5哈希存储 character-encoding: UTF-8关键点解析sql根据用户名查询用户的SQL语句。CAS会使用登录时输入的用户名替换?。password-encoder这是最容易出错的地方必须与数据库中密码的存储方式一致。如果数据库存的是明文则不需要编码器。如果是MD5哈希就配置type: DEFAULT和encoding-algorithm: MD5。现代系统推荐使用BCRYPT。field-expired和field-disabled对应数据库中表示账户是否过期、禁用的字段名可选CAS会据此拒绝登录。4.1.2 集成LDAPActive Directory/OpenLDAP对于使用AD域控的企业集成LDAP是更常见的选择。在build.gradle中添加依赖implementation org.apereo.cas:cas-server-support-ldap:${project.cas.version}在application.yml中配置cas: authn: ldap: - type: AUTHENTICATED # 或 DIRECT, AD 等 ldap-url: ldap://ad.example.org:389 base-dn: dcexample,dcorg search-filter: sAMAccountName{user} bind-dn: cnbinduser,ouServiceAccounts,dcexample,dcorg bind-credential: bindpassword principal-attribute-list: sAMAccountName,mail,displayName配置解析typeAUTHENTICATED表示CAS先用bind-dn凭证绑定LDAP再搜索用户AD是Active Directory的优化类型。search-filter搜索用户的过滤器{user}会被替换为登录用户名。bind-dn和bind-credential一个有权限在LDAP中搜索用户的账户。principal-attribute-list认证成功后从LDAP条目中获取哪些属性这些属性可以释放给服务。4.2 票据存储从内存到Redis集群默认情况下CAS生成的Ticket如TGT-票据授予票据ST-服务票据存储在内存中。这意味着服务器重启后所有登录状态丢失且无法在集群环境下共享。生产环境必须使用外部存储。集成Redis作为Ticket Registry添加依赖implementation org.apereo.cas:cas-server-support-redis-ticket-registry:${project.cas.version}配置application.ymlcas: ticket: registry: redis: host: localhost port: 6379 password: your_redis_password # 如果没有密码则省略 database: 0 timeout: 5000这样所有票据都将持久化到Redis中。即使CAS服务器实例重启或扩容用户的登录状态也不会丢失完美支持集群部署。4.3 管理界面与监控CAS提供了一个内置的管理端点Actuator Endpoints默认不开启。开启后可以查看健康状态、指标、环境配置等。在application.yml中添加management: endpoints: web: exposure: include: health,info,metrics,env endpoint: health: show-details: always然后你可以通过https://cas.example.org:8443/cas/actuator/health来检查服务健康状态。为了安全生产环境应通过Spring Security限制对这些端点的访问。5. 客户端应用集成示例服务端配置好了客户端你的业务应用如何接入这里以两个最常见的场景为例。5.1 Java Web应用集成使用官方CAS Client对于传统的Servlet-based应用如Spring MVC, J2EE可以使用cas-client-core。添加Maven依赖dependency groupIdorg.apereo.cas/groupId artifactIdcas-client-core/artifactId version3.6.4/version !-- 注意选择与CAS服务端兼容的版本 -- /dependency配置web.xml或通过Java Config!-- 认证过滤器 -- filter filter-nameCAS Authentication Filter/filter-name filter-classorg.apereo.cas.client.authentication.AuthenticationFilter/filter-class init-param param-namecasServerLoginUrl/param-name param-valuehttps://cas.example.org:8443/cas/login/param-value /init-param init-param param-nameserverName/param-name param-valuehttps://app1.example.org/param-value /init-param /filter filter-mapping filter-nameCAS Authentication Filter/filter-name url-pattern/*/url-pattern /filter-mapping !-- 票据验证过滤器 -- filter filter-nameCAS Validation Filter/filter-name filter-classorg.apereo.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter/filter-class init-param param-namecasServerUrlPrefix/param-name param-valuehttps://cas.example.org:8443/cas/param-value /init-param init-param param-nameserverName/param-name param-valuehttps://app1.example.org/param-value /init-param /filter filter-mapping filter-nameCAS Validation Filter/filter-name url-pattern/*/url-pattern /filter-mapping获取用户信息验证通过后用户身份会存储在HttpServletRequest的principal中可以通过request.getUserPrincipal().getName()获取用户名。5.2 Spring Boot应用集成使用Spring Security对于现代Spring Boot应用集成更加优雅。Spring Security提供了对CAS的原生支持。添加依赖dependency groupIdorg.springframework.security/groupId artifactIdspring-security-cas/artifactId /dependency配置SecurityConfigConfiguration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Value(${cas.server.url}) private String casServerUrl; Value(${app.server.url}) private String appServerUrl; Override protected void configure(HttpSecurity http) throws Exception { http .authorizeRequests() .anyRequest().authenticated() .and() .csrf().disable() .exceptionHandling() .authenticationEntryPoint(casAuthenticationEntryPoint()) .and() .addFilterBefore(casAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class); } Bean public CasAuthenticationEntryPoint casAuthenticationEntryPoint() { CasAuthenticationEntryPoint entryPoint new CasAuthenticationEntryPoint(); entryPoint.setLoginUrl(casServerUrl /login); entryPoint.setServiceProperties(serviceProperties()); return entryPoint; } Bean public ServiceProperties serviceProperties() { ServiceProperties sp new ServiceProperties(); sp.setService(appServerUrl /login/cas); sp.setSendRenew(false); return sp; } Bean public CasAuthenticationFilter casAuthenticationFilter() throws Exception { CasAuthenticationFilter filter new CasAuthenticationFilter(); filter.setAuthenticationManager(authenticationManager()); filter.setFilterProcessesUrl(/login/cas); return filter; } Bean public CasAuthenticationProvider casAuthenticationProvider() { CasAuthenticationProvider provider new CasAuthenticationProvider(); provider.setAuthenticationUserDetailsService(userDetailsService()); provider.setServiceProperties(serviceProperties()); provider.setTicketValidator(cas20ServiceTicketValidator()); provider.setKey(CAS_PROVIDER_KEY); return provider; } Bean public Cas20ServiceTicketValidator cas20ServiceTicketValidator() { return new Cas20ServiceTicketValidator(casServerUrl); } // 需要实现 UserDetailsService用于根据CAS返回的用户名加载用户权限等信息 Bean public UserDetailsService userDetailsService() { // ... 返回你的UserDetailsService实现 } }这样当用户访问受保护的Spring Boot应用时会被重定向到CAS登录登录成功后返回应用Spring Security会自动完成票据验证和会话建立。6. 部署上线、运维与问题排查将开发调试好的CAS部署到生产环境还需要考虑一些运维层面的问题。6.1 打包与部署使用./gradlew clean build生成的cas.war是一个可执行的Fat Jar内嵌了Tomcat。部署方式非常灵活直接运行java -jar cas.war或java -Xmx1024m -jar cas.war。你可以使用nohup或systemd来守护进程。部署到外部容器虽然可以但不推荐。因为Overlay项目默认打包的是可执行Jar若要部署到独立的Tomcat需要修改打包配置apply plugin: ‘war’并处理内嵌容器冲突复杂度较高。直接运行Jar是官方推荐方式。6.2 日志与监控日志配置CAS使用Spring Boot的Logback。你可以在src/main/resources/logback.xml中自定义日志格式、输出级别和文件滚动策略。生产环境建议将org.apereo.cas的日志级别设为WARN或ERROR避免日志量过大。健康检查如前所述利用Actuator的/health端点可以方便地集成到Kubernetes的Liveness/Readiness Probe或各类监控系统中。6.3 常见问题与排查技巧实录在部署和使用过程中你几乎一定会遇到下面这些问题。这里我记录下最典型的几个及其解决思路。问题1登录成功但重定向回应用时出现“无效票据Invalid Ticket”错误。排查思路这是最常见的问题根本原因是CAS服务器生成的ST服务票据与应用验证时的不匹配或已过期。检查时钟同步确保CAS服务器和客户端应用服务器的系统时间完全同步使用NTP。票据的有效性严重依赖于时间戳。检查服务注册确认客户端应用的URLservice参数是否精确匹配在CAS服务端services/目录下JSON文件中定义的serviceId正则表达式。多一个斜杠或少一个端口号都可能不匹配。检查网络连通性确保客户端应用能通过网络访问CAS服务器的https://cas.example.org:8443/cas地址特别是/validate或/p3/serviceValidate端点。查看CAS服务器日志日志中会记录票据的生成和验证过程。搜索票据ID看是否有验证失败的记录错误信息通常很明确。问题2集成LDAP/AD认证失败提示“用户名密码错误”或“无法找到用户”。排查思路测试LDAP连接先用ldapsearch或Apache Directory Studio等工具使用配置中的bind-dn和bind-credential手动执行search-filter对应的查询看能否返回用户条目。这是验证LDAP配置是否正确的最直接方法。检查过滤器语法确保search-filter中的属性名如sAMAccountName,uid在你的LDAP架构中存在且正确。检查Base DNbase-dn是否设置得过大或过小确保目标用户在这个Base DN之下。查看CAS DEBUG日志将org.apereo.cas日志级别临时调整为DEBUG可以看到详细的LDAP绑定和搜索过程有助于定位问题。问题3CAS管理界面Actuator端点或服务注册JSON文件修改后不生效。排查思路服务注册缓存CAS默认会缓存服务注册信息以提高性能。修改JSON文件后需要触发重新加载。可以发送一个POST请求到https://cas.example.org:8443/cas/actuator/serviceRegistry或者直接重启CAS服务。配置热加载对于application.ymlSpring Boot支持部分属性的热加载但并非全部。最可靠的方式还是重启应用。对于生产环境建议将配置外部化如使用Spring Cloud Config以实现真正的动态刷新。问题4性能问题登录或验证响应慢。排查思路票据存储如果使用默认的内存存储在用户量或票据量大时清理过期票据的线程可能会造成停顿。务必切换到外部存储如Redis。认证源如果LDAP或数据库查询慢会直接影响登录速度。检查认证源的网络延迟和查询性能考虑增加连接池、优化查询语句或索引。日志级别生产环境务必把日志级别从DEBUG/INFO调高到WARN大量日志IO会消耗性能。JVM参数确保为JVM分配了足够且合理的堆内存-Xms和-Xmx并启用GC日志进行监控。部署CAS 5.3就像搭建一个核心枢纽初期配置会有些繁琐但一旦打通对于整合企业内部纷杂的系统、提升安全性和用户体验的价值是巨大的。我的建议是先在测试环境按照本文的步骤从静态用户开始逐步集成数据库、LDAP和Redis把整个流程跑通理解每个配置项的含义。然后再规划生产环境的部署架构考虑高可用、负载均衡和监控告警。记住仔细阅读官方文档和日志它们是你解决问题的最佳伙伴。