SAML Java Toolkit 技术文档

1. 安装指南

1.1 通过 GitHub 安装

你可以从 GitHub 下载最新版本的 SAML Java Toolkit：

• 最新发布版本：GitHub Releases
• 主仓库：GitHub Master

1.2 通过 Maven 安装

SAML Java Toolkit 托管在 Sonatype OSSRH，并同步到中央仓库。你可以通过 Maven 依赖来安装：

<dependency>
    <groupId>com.onelogin</groupId>
    <artifactId>java-saml</artifactId>
    <version>2.9.0</version>
</dependency>

1.3 依赖项

SAML Java Toolkit 依赖以下库：

• 核心依赖：
  • org.apache.santuario:xmlsec
  • joda-time:joda-time
  • org.apache.commons:commons-lang3
  • commons-codec:commons-codec
• 测试依赖：
  • org.hamcrest:hamcrest-core 和 org.hamcrest:hamcrest-library
  • junit:junit
  • org.mockito:mockito-core
• 日志依赖：
  • org.slf4j:slf4j-api
  • ch.qos.logback:logback-classic
• CI 依赖：
  • org.jacoco:jacoco-maven-plugin

此外，还需要安装 Java Cryptography Extension (JCE)。如果你使用的是 JDK 8，请下载并安装 jce-8。

2. 项目的使用说明

2.1 项目概述

SAML Java Toolkit 允许你将 Java 应用程序转换为支持 SAML 的 SP（服务提供者），并连接到 IdP（身份提供者）。它支持以下功能：

• SSO 和 SLO（SP 发起和 IdP 发起）
• 断言和名称 ID 加密
• 断言签名
• 消息签名：AuthNRequest、LogoutRequest、LogoutResponse
• 启用断言消费者服务端点
• 启用单点注销服务端点
• 发布 SP 元数据（可以签名）

2.2 主要特性

• saml2int：实现 SAML 2.0 Web 浏览器 SSO 配置文件
• 无会话：避免 SP 和最终应用程序之间的常见冲突
• 易于使用：提供高级别和低级别的编程接口
• 经过测试：经过彻底测试

3. 项目 API 使用文档

3.1 核心 API

核心 API 包含处理 AuthNRequest、SAMLResponse、LogoutRequest、LogoutResponse 和 Metadata 的类和方法。

3.2 工具包 API

工具包 API 提供了更高级别的接口，简化了 SAML 操作。

3.3 示例 API

示例 API 展示了如何在实际应用中使用 SAML Java Toolkit。

4. 项目安装方式

4.1 通过 GitHub 安装

从 GitHub 下载最新版本的 SAML Java Toolkit，并将其导入到你的项目中。

4.2 通过 Maven 安装

在 Maven 项目的 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>com.onelogin</groupId>
    <artifactId>java-saml</artifactId>
    <version>2.9.0</version>
</dependency>

4.3 依赖项安装

确保你已经安装了所有必要的依赖项，特别是 Java Cryptography Extension (JCE)。

5. 使用示例

5.1 导入项目

1. 打开 Eclipse 并设置工作区。
2. 导入 core 和 toolkit 项目：
   • 选择 File > Import > Maven : Existing Maven Projects，然后选择 core 和 toolkit 目录。
3. 导入 java-saml-tookit-jspsample 项目：
   • 选择 File > Import > Maven : Existing Maven Projects，然后选择 samples/java-saml-tookit-jspsample 目录。

5.2 部署示例项目

1. 在包资源管理器中选择 jsp-sample 项目。
2. 右键点击并选择 Run As > Run Server。
3. 选择一个 Tomcat 服务器来部署项目。

6. 安全警告

在生产环境中，必须将 onelogin.saml2.strict 设置参数设置为 true，否则环境将不安全，容易受到攻击。建议在设置中注册 IdP 证书，而不是使用指纹方法。