This page was saved using WebZIP 7.1.2.1052 offline browser on 04/26/18 10:45:53.
Address: https://apereo.github.io/cas/5.2.x/installation/Maven-Overlay-Installation.html
Title: CAS - Overlay Installation  •  Size: 24926  •  Last Modified: Mon, 23 Apr 2018 19:41:07 GMT

Enterprise Single Sign-On for All

WAR Overlay 安装

CAS的安装是基于源码的基础上构建出来的,我们建议你使用WAR overlay的方式来安装,可自动自定义安装,比如自行对组件的配置,和UI的设计;构建出来的是cas.war文件,该文件可以直接部署到servlet容器中,比如 Apache Tomcat

安装要求

请参阅本指南了解更多信息。

War Overlay是什么?

Overlays是一种避免重复代码或重复资源的打包策略,它可以让你自行下载CAS预编译的应用后,自定义增加或者替换相应的配置和特性。在构建的时候,Maven/Gradle首先会自动下载更新安装,然后找到你的配置文件和设置,自动合并到你自动下载的目录结构中,来构建出一个完整的项目 (比如 cas.war)。重写或覆盖的文件包括资源文件、Java的classes文件、图像文件、CSS和JS文件。
为了合并过程的成功执行,本地重写或覆盖的文件的位置和名称,必须与之前下载的存档中的项目所提供的位置和名称完全一样。

虽然前面的方法可能稍微复杂,但这种方法有显著的优势:

  1. 不需要从源站下载源码编译。
  2. 在大多数情况下,通过简单地调整生成脚本,来下载更新的CAS版本,升级非常容易。
  3. 与部署整个软件源代码不同的是,作为部署器,您只保留自己的本地定制,这使得更改跟踪变得更加容易。
  4. 源代码修改的管理和跟踪非常轻量级,配置更改只要管理修改的部分(而不是整个软件),非常的简单。

管理 Overlays

CAS的各个部分都可以通过在Overlay中新增、删除和修改文件来控制;也可以通过增加第三方组件来自定义CAS的行为。

使用覆盖的过程,无论是Maven还是Gradle,都可以概括为以下步骤:

  • 以构建/部署包为基础,开始构建
  • 从生成的版本中识别需要更改的工件。这些工件通常是由Maven或Gradle中的目标或生成目录生成的。
  • 将已识别的文件从复制到src目录。
    1. 创建src目录和所有的子目录,如果它们不存在的话。
    2. 复制的路径和文件名必须与它们的构建对应物完全匹配,否则更改不会生效。请参阅下表,了解如何将文件夹和文件从生成映射到src
  • 更改之后,尽可能多次重建并重复该过程。
  • 请仔细检查内置二进制文件的更改,以确保覆盖过程正常工作。
确切地说

不要复制编制出来的所有文件,尽量在满足你的需求的前提下,对项目尽量小的修改和自定义调整;确保您的部署环境是干净准确的,否则日后的升级工作会很困难。

CAS WAR Overlays

CAS WAR overlay项目供参考和学习。

Review Branch!

下面的代码仓库指向是master主分支,你需要确认你想要配置的部署的CAS版本。 master主分支通过是CAS服务端最新的文档版本。确认构建的配置,如果不合理,使用git branch -a命令来看可用的分支版本,然后使用git checkout [branch-name]命令切换到所需要的版本。

Project Build Directory Source Directory
CAS Maven WAR Overlay target/cas.war!WEB-INF/classes/ src/main/resources
CAS Gradle WAR Overlay cas/build/libs/cas.war!WEB-INF/classes/ src/main/resources

要构造overlays的项目,需要在生成目录中把自定义的目录和文件复制到源目录。

在重新编辑文件之前,overlay的gradle工具可以提供额外任务,来生成二进制的项目;您可能需要手动完成这一步骤,以了解需要复制哪些文件/目录到源目录。

注意: 不要在上面提到的构建目录中做任何更改。每次构建时,更改将被除并设置为默认值。在源目录和/或其他指示的位置内放置重叠的组件以避免意外。

CAS Configuration Server Overlay

有关更多细节,请参阅Maven WAR overlay

若要了解配置服务器的更多信息,请查看此指南

Docker化部署

更多信息请参阅本指南

Servlet容器

CAS可以部署到多个servlet容器中。更多信息请参阅本指南

定制和第三方源

这是常见的定制或开发java组件,实现CAS API或包括由Maven依赖引用第三方源扩展CAS的功能。简单地在覆盖pom.xmlbuild.gradle文件。为自定义的java源码,Overlay项目应包括src/main/java目录。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
├── src
│   ├── main
│   │   ├── java
│   │   │   └── edu
│   │   │       └── sso
│   │   │           └── middleware
│   │   │               └── cas
│   │   │                   ├── audit
│   │   │                   │   ├── CompactSlf4jAuditTrailManager.java
│   │   │                   ├── authentication
│   │   │                   │   └── principal
│   │   │                   │       └── UsernamePasswordCredentialsToPrincipalResolver.java
│   │   │                   ├── services
│   │   │                   │   └── JsonServiceRegistryDao.java
│   │   │                   ├── util
│   │   │                   │   └── X509Helper.java
│   │   │                   └── web
│   │   │                       ├── HelpController.java
│   │   │                       ├── flow
│   │   │                       │   ├── AbstractForgottenCredentialAction.java
│   │   │                       └── util
│   │   │                           ├── ProtocolParameterAuthority.java

Maven 警告

另外,请注意,任何自定义的java组件编译要包含在最终的cas.war文件,Overlay项目中的Maven pom.xml必须包含Maven的java编译器,这样可以编译的java类。

以下是Maven构建配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
...

<build>
    <plugins>
...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.1</version>
            <configuration>
                <source>${java.source.version}</source>
                <target>${java.target.version}</target>
            </configuration>
        </plugin>
...
    </plugins>
    <finalName>cas</finalName>
</build>

依赖管理

CAS的每个版本都提供了它支持的依赖列表。在实践中,您不需要为构建配置中的任何依赖项提供一个版本,因为CAS发行版正在为您管理这些版本。当升级CAS本身时,这些依赖性也将以一致的方式升级。

这个依赖列表包含第三方库的组件。这个列表可以作为标准物料清单(BOM)。

若要将项目配置为从BOM继承,只需设置父级:

Maven

1
2
3
4
5
<parent>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-bom</artifactId>
    <version>${cas.version}</version>
</parent>

并不是每个人都喜欢从BOM继承。您可能需要使用自己的企业标准父级,或者可能更喜欢显式声明所有Maven配置。

如果不想使用cas-server-support-bom,仍然可以通过使用scope=import,得到依赖组件管理的好处(不是插件管理):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<dependencyManagement>
     <dependencies>

        <!-- Override a dependency by including it BEFORE the BOM -->
        <dependency>
            <groupId>org.group</groupId>
            <artifactId>artifact-name</artifactId>
            <version>X.Y.Z</version>
        </dependency>

        <dependency>
            <groupId>org.apereo.cas</groupId>
            <artifactId>cas-server-support-bom</artifactId>
            <version>${cas.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle

使用Gradle来使用CAS BOM,请使用此指南,并相应配置Gradle构建。

(1) WAR Overlays