java-saml完整指南：3步为Java应用添加企业级SAML单点登录（SSO）支持

java-saml完整指南3步为Java应用添加企业级SAML单点登录SSO支持【免费下载链接】java-samlJava SAML toolkit项目地址: https://gitcode.com/gh_mirrors/jav/java-samljava-saml 是广泛使用的开源 Java SAML 工具包Java SAML toolkit只需 3 步即可为任意 Java 应用添加企业级 SAML 单点登录SSO支持引入 Maven 依赖、编写 SAML 配置文件、接入 Auth 类。它让你的应用成为 SAML 服务提供方SP与企业身份提供方IdP无缝对接用户一次登录、处处通行。为什么选择 java-saml 实现 SAML 单点登录SAML 是 OASIS 标准的 XML 单点登录协议被全球大型企业的认证体系广泛采用。用 java-saml 接入 SSO你的应用可以立即获得免密单点登录— 用户通过门户一键进入无需在每个系统重复输密码️强安全— 基于数字签名的断言验证防伪造、防篡改、防钓鱼⚡快— 一次浏览器重定向即可完成安全登录无会话设计— 工具包不绑定框架会话交由你的应用自己管理避免 SP 与应用之间的会话冲突核心能力说明SSO / SLO支持 SP 发起与 IdP 发起的单点登录和单点登出签名与加密支持断言Assertion与 NameID 加密、消息签名内置端点提供断言消费服务ACS与单点登出服务SLS的处理逻辑SP Metadata可发布可选签名SP 元数据方便 IdP 对接java-saml 项目结构速览core、toolkit 与 samples理解三个模块的关系后面 3 步操作就会非常清晰模块职责关键源码core/底层 API构造/校验 SAML 消息、加载配置、框架无关的 HTTP 请求抽象core/src/main/java/com/onelogin/saml2/authn/AuthnRequest.java、core/src/main/java/com/onelogin/saml2/authn/SamlResponse.java、core/src/main/java/com/onelogin/saml2/settings/Saml2Settings.javatoolkit/高层 API面向 Servlet 的一站式入口类 Auth 与 ServletUtilstoolkit/src/main/java/com/onelogin/saml2/Auth.java、toolkit/src/main/java/com/onelogin/saml2/servlet/ServletUtils.javasamples/JSP 演示应用可直接部署运行学习完整 SSO 流程samples/java-saml-tookit-jspsample/src/main/webapp/第一步Maven 一行依赖最快安装方法在项目的pom.xml中加入依赖即可完成安装dependency groupIdcom.onelogin/groupId artifactIdjava-saml/artifactId version2.9.0/version /dependency 注意事项版本 2.5.0 及以上兼容 Java 8 / Java 9不再支持 Java 7详细依赖关系可查看core/pom.xml与toolkit/pom.xml如需研究源码或运行示例可克隆仓库git clone https://gitcode.com/gh_mirrors/jav/java-saml第二步编写 onelogin.saml.properties 完成 SAML SSO 配置Auth 类默认会加载onelogin.saml.properties文件。所有 SP 信息、IdP 信息和安全策略都集中在这一个文件里完整字段说明见README.md的 Settings 章节最小可用的核心配置如下# 生产环境必须为 true否则环境不安全 onelogin.saml2.strict true ## 服务提供方SP即你的应用信息 ## onelogin.saml2.sp.entityid https://yourapp.example.com/metadata.jsp # IdP 将 SAML 响应回传的断言消费服务ACS地址 onelogin.saml2.sp.assertion_consumer_service.url https://yourapp.example.com/acs.jsp # 单点登出服务SLS地址 onelogin.saml2.sp.single_logout_service.url https://yourapp.example.com/sls.jsp onelogin.saml2.sp.x509cert SP公钥证书 onelogin.saml2.sp.privatekey SP私钥PKCS#8格式 ## 身份提供方IdP即企业身份系统信息 ## onelogin.saml2.idp.entityid IdP实体ID onelogin.saml2.idp.single_sign_on_service.url IdP SSO地址 onelogin.saml2.idp.x509cert IdP公钥证书关键字段速查配置项作用onelogin.saml2.strict严格模式生产环境必须开启sp.entityid你的应用在 SAML 世界中的唯一标识URIsp.assertion_consumer_service.urlIdP 登录成功后把 SAML 响应 POST 回你的地址idp.single_sign_on_service.url登录时把用户重定向过去的 IdP 地址idp.x509cert用于验证 IdP 返回消息签名的公钥证书security.want_assertions_signed是否要求收到的断言必须带签名 两个进阶用法KeyStore 方式SP 证书/私钥可从 JKS 密钥库读取见core/src/main/java/com/onelogin/saml2/model/KeyStoreSettings.java动态配置用SettingsBuilder的fromValues(Map)从数据库等来源动态构建配置见core/src/main/java/com/onelogin/saml2/settings/SettingsBuilder.java第三步用 Auth 类接入 SSO 登录与 SLO 登出端点整个 SSO 流程只需理解这 6 步用户点击登录你的应用调用auth.login()工具包生成 AuthnRequest浏览器重定向到 IdP用户在 IdP 完成认证输密码/扫码等IdP 把签名的 SAML 响应 POST 回你的 ACS 地址你的 ACS 端点调用auth.processResponse()验证签名并提取用户信息验证通过写入 Session用户登录成功 ✅登录入口如 dologin 端点Auth auth new Auth(request, response); auth.login(); // 生成 AuthnRequest 并重定向到 IdP断言消费服务 ACS如 acs 端点Auth auth new Auth(request, response); auth.processResponse(); if (auth.isAuthenticated()) { String nameId auth.getNameId(); // 用户唯一标识 MapString, ListString attributes auth.getAttributes(); // IdP 下发的用户属性 session.setAttribute(nameId, nameId); }单点登出Auth auth new Auth(request, response); auth.logout(); // 发起 SP 侧 SLO向 IdP 发送 LogoutRequestSLS 端点则调用auth.processSLO()统一处理 LogoutRequest 与 LogoutResponse。你的应用需要实现 4 个端点对照演示应用的 JSP 文件一一对应端点职责参考实现登录入口触发 SSO 重定向samples/java-saml-tookit-jspsample/src/main/webapp/dologin.jspACS接收并验证 IdP 的 SAML 响应samples/java-saml-tookit-jspsample/src/main/webapp/acs.jspSLS处理单点登出请求/响应samples/java-saml-tookit-jspsample/src/main/webapp/sls.jspMetadata发布 SP 元数据给 IdPsamples/java-saml-tookit-jspsample/src/main/webapp/metadata.jsp生产环境 SAML 安全配置清单⚠️ 上线前请逐项核对onelogin.saml2.strict必须设为true否则环境会暴露于攻击风险注册 IdP 完整证书而非指纹fingerprint 是哈希值存在碰撞风险官方已不推荐生产使用开启security.want_assertions_signed与security.want_xml_validation要求断言签名并校验 XML防重放攻击用auth.getLastMessageId()记录已处理消息的 ID短期内拒绝重复消息负载均衡 SSL 卸载场景下需为 Tomcat Connector 配置 proxyName / proxyPort / scheme / secure否则请求地址与 Destination 校验可能失败运行 samples 演示应用5 分钟验证 SSO 流程官方内置了一个完整的 JSP 演示应用部署后访问首页index.jsp即可体验在 IDE 中导入samples/java-saml-tookit-jspsample的 Maven 工程修改工程内onelogin.saml.properties填入你的 SP 与 IdP 信息部署到 Tomcat浏览器打开首页选择「登录并留在本页」或「登录后跳转到属性页」体验 SP 发起的 SLO点击 logout观察 LogoutRequest → IdP → LogoutResponse 的完整链路演示应用中还提供了attrs.jsp展示 IdP 下发的用户属性和metadata.jsp展示 SP 元数据是排查 SAML 对接问题的好帮手。java-saml 常见问题 FAQQAuth 实例可以全局复用吗A不可以。Auth 是有状态且非线程安全的类每个请求都应新建一个实例new Auth(request, response)。QIdP 在证书轮换期发布了多张证书怎么办A在配置中追加onelogin.saml2.idp.x509certMulti参数可登记多张证书用于验签。Q如何定制 SAML 消息的生成/校验逻辑A所有消息类AuthnRequest、SamlResponse、LogoutRequest、LogoutResponse均可继承扩展并通过SamlMessageFactory见toolkit/src/main/java/com/onelogin/saml2/factory/SamlMessageFactory.java注入自定义实现。按照「依赖 → 配置 → Auth 接入」这 3 步走你的 Java 应用就已经具备了企业级 SAML SSO 能力。建议先跑通 samples 演示应用再对照上表接入自己的端点对接过程会顺畅很多。【免费下载链接】java-samlJava SAML toolkit项目地址: https://gitcode.com/gh_mirrors/jav/java-saml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考