Migration Guide 5.7.1_ja - terasolunaorg/terasoluna-gfw GitHub Wiki

5.7.0から5.7.1への移行ガイド

目次

1. 5.7.1での主な変更点

5.7.1での主な変更点は以下の通りです。

  • 主要なライブラリのバージョンを更新

  • OAuth2をSpring Security OAuthからSpring Securityに移行

  • 共通ライブラリの仕様を一部変更

  • ブランクプロジェクトの変更

1.1. 主要なライブラリのバージョンを更新

  • Spring Boot Dependencies 2.6.2へ更新

    • Spring Framework 5.3.13へ更新

    • Spring Security 5.6.0へ更新

  • MyBatis 3.5.7へ更新

1.2. OAuth2をSpring Security OAuthからSpring Securityに移行

OAuth2について、Spring Security OAuth(org.springframework.security.oauth)からSpring Security(org.springframework.security)の機能を使用するように修正しました。これに伴い、共通ライブラリの依存関係からSpring Security OAuthを削除しました。
ガイドラインのSpring Security OAuthについての記載は、 Appendix に移動しています。

1.3. 共通ライブラリの変更

  • 共通ライブラリのライブラリ及びMavenプラグインのバージョンを変更

    • [#1086] Update the version of maven-plugin

    • [#1121] Apply MyBatis 3.5.7

    • [#1122] Apply jakarta.inject-api 1.0.5

    • [#1123] Apply poi-ooxml 4.1.2

    • [#1124] Apply Google Guava 30.1.1-jre

    • [#1125] Apply Bouncy Castle Provider 1.69

    • [#1126] Apply commons-io 2.11.0

    • [#1134] Apply Dozer 6.5.2

    • [#1141] Apply Spring Boot 2.6.1

    • [#1149] Remove the dependency spring-security-oauth2

    • [#1153] Update commons-compress

1.4. ブランクプロジェクトの変更

  • ブランクプロジェクトのライブラリ及びMavenプラグインのバージョンを変更

  • 脆弱性対応のため、ブランクプロジェクトのログフォーマットを変更

2. 5.7.0から5.7.1への移行手順

移行手順は、以下の通りです。

凡例
Required : 手順の適用は必須
Required by case : 手順の適用は条件付きで必須
Optional : 手順の適用を推奨 (必要に応じて手順の適用を実施)
- : 手順の適用は必要なし

[全般]

ステップ 手順 MavenMultiple Projects MavenSingle Project

1.

依存ライブラリを更新

Required

Required

[共通ライブラリ]

ステップ 手順 MavenMultiple Projects MavenSingle Project

2.

共通ライブラリが管理するMavenプラグインの最新化に伴う対応

Required by case

Required by case

[Blank project]

ステップ 手順 MavenMultiple Projects MavenSingle Project

3.

JDBCドライバーのバージョンの変更

Optional

Optional

4.

ログインジェクションに対応したログフォーマットの修正

Optional

Optional

[Spring Security]

ステップ 手順 MavenMultiple Projects MavenSingle Project

5.

Spring Security OAuth(org.springframework.security.oauth)からSpring Security(org.springframework.security)への移行に伴う対応

Optional

Optional

[Spring Data]

ステップ 手順 MavenMultiple Projects MavenSingle Project

6.

Spring Data 2.5.0から非推奨となったAPIへの対応

Required by case

Required by case

[DBUnit]

ステップ 手順 MavenMultiple Projects MavenSingle Project

7.

DBUnitのバージョンの変更に伴う対応

Required by case

Required by case

2.1. [Step 1] 依存ライブラリを更新

TERASOLUNA Server Framework for Java (5.x)の共通ライブラリと依存ライブラリを更新してください。
以下に、この手順により更新される代表的な依存ライブラリを示します。

ライブラリ名 更新前バージョン 更新後バージョン 備考

TERASOLUNA Server Framework for Java (5.x) Common Library

5.7.0.RELEASE

5.7.1.RELEASE

Spring Framework

5.3.2.RELEASE

5.3.13

Spring Data

2.4.2

2.6.0

Spring Security

5.4.2

5.6.0

Spring Security OAuth2

2.5.0.RELEASE

-

削除しました。
5.7.0までのガイドラインで説明していたSpring Security OAuthの記述に関しては Appendix に移動しています。

MyBatis3

3.5.6

3.5.7

Jakarta Dependency Injection

1.0.3

1.0.5

Apache POI

4.1.1

4.1.2

Google Guava

27.0.1-jre

30.1.1-jre

Bouncy Castle Provider

1.64

1.69

Apache Commons IO

2.6

2.11.0

Dozer

6.5.0

6.5.2

Apache Commons Compress

1.19
※Apache POI 4.1.2 が依存関係に持つバージョン

1.21

CVE-2021-36090 が存在するためバージョンアップしました。Apache Commons CompressはTERASOLUNAが依存しているライブラリではありませんが、Apache POI が依存関係に持つため、独自にバージョンを上げています。

[手順が必要なケース]

この手順の適用は必須です。

2.1.1. [Step 1-1] Maven Multiple Projectsを利用している場合

この更新手順は、 mvn archetype を使用して作成したプロジェクト向けです。
親プロジェクトのPOMファイルのversionを5.7.1.RELEASE に修正してください。

  • ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

<!-- omitted -->
<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>5.7.1.RELEASE</version>                    <!-- ### 修正箇所 ### -->
</parent>
<!-- omitted -->

2.1.2. [Step 1-2] Maven Single Projectを利用している場合

この更新手順は、 mvn archetype を使用して作成したプロジェクト向けです。

プロジェクトのPOMファイルのversionを5.7.1.RELEASEに修正してください。

  • ($YOUR_SINGLE_PROJECT/pom.xml)

<!-- omitted -->
<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>5.7.1.RELEASE</version>                    <!-- ### 修正箇所 ### -->
</parent>
<!-- omitted -->

2.2. [Step 2] 共通ライブラリが管理するMavenプラグインの最新化に伴う対応

共通ライブラリが管理するMavenプラグインの最新化を行いました。
バージョンの更新以外に下記の変更を行いました。

  • プラグインのバージョンを指定するプロパティ名をgroupId.artifactId.pugin.versionに変更しました。

  • cargo-maven2-pluginの名称をcargo-maven3-pluginに変更しました。

  • mvn siteコマンド実行時にWarningが発生するため、reporting要素内にmaven-project-info-reports-pluginを追加しました。

アプリケーションで独自にプラグインのバージョンを指定していない場合、自動的にアップグレードされビルドの挙動に変更が生じる可能性があります。なお、本手順ではApache Mavenのバージョンを3.8.3で使用することを前提としています。

Tip

Apache Maven 3.8.1 以降では、 Release Notes – Maven 3.8.1 で説明されている通り、外部の安全ではないHTTPのURLはブロックされます。

最新化されたプラグインのバージョンについては、以下を参照してください。

[手順が必要なケース]

以下のケースに当てはまる場合、ビルドの挙動を確認して必要に応じて修正を行ってください。

  • アプリケーションで独自にプラグインのバージョンを指定していない

[修正方法]

プラグインごとに対応方法が異なるため、各公式リファレンスを参照して対応してください。

なお、プラグインを5.7.0までのバージョンに戻す場合はterasoluna-gfw-parentのpom.xmlに定義されたプロパティを上書きします。 例えば Maven Dependency Plugin のバージョンを戻す場合は以下のように定義します。

  • pom.xml

<properties>
    <!-- omitted -->
    <org.apache.maven.plugins.maven-dependency-plugin.version>3.1.2</org.apache.maven.plugins.maven-dependency-plugin.version>  <!-- ### 追加箇所 ### -->
</properties>

2.3. [Step 3] JDBCドライバーのバージョンの変更

ブランクプロジェクトのpomファイルで、 PostgreSQL JDBC Driver と Oracle JDBC のバージョン定義を更新しました。
これらのJDBCドライバーは上位互換性が保障されているため、最新バージョンを使用することを推奨します。

[手順が必要なケース]

この手順の適用は任意ですが、修正を行うことを推奨します。

2.3.1. [Step 3-1] PostgreSQLを使用する場合

以下の情報を参照し、適切なバージョンを設定してください。

以降では、 TERASOLUNA Server Framework for Java 5.7.1.RELEASE の動作検証環境に合わせる形での変更方法を示します。

[修正方法]

pomファイルのプロパティを修正してください。

  • pom.xml

<properties>
    <!-- omitted -->
    <postgresql.version>42.3.1</postgresql.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
</properties>

2.3.2. [Step 3-2] Oracle Databaseを使用する場合

以下の情報を参照し、適切なバージョンを設定してください。

以降では、 TERASOLUNA Server Framework for Java 5.7.1.RELEASE の動作検証環境に合わせる形での変更方法を示します。

[修正方法]

プロジェクトのpom.xmlを更新します。利用するJDKのバージョンによってドライバが異なるため、注意してください。

[Step 3-2-1] JDK8の場合

  • pom.xml

<dependencyManagement>
    <dependencies>
    <!-- omitted -->
        <dependency>
            <groupId>com.oracle.jdbc</groupId>
            <artifactId>ojdbc8</artifactId>>
            <version>${ojdbc.version}</version>
        </dependency>
    <!- omitted -->
    </dependencies>
</dependencyManagement>

<properties>
    <!-- omitted -->
    <ojdbc.version>21.3.0.0</ojdbc.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
</properties>
[Step 3-2-2] JDK11の場合

  • pom.xml

<dependencyManagement>
    <dependencies>
    <!-- omitted -->
        <dependency>
            <groupId>com.oracle.jdbc</groupId>
            <artifactId>ojdbc10</artifactId>
            <version>${ojdbc.version}</version>
        </dependency>
    <!- omitted -->
    </dependencies>
</dependencyManagement>

<properties>
    <!-- omitted -->
    <ojdbc.version>19.12.0.0</ojdbc.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
</properties>

2.4. [Step 4] ログインジェクションに対応したログフォーマットの修正

ログフォーマットを変更することで、ログインジェクションへの対策を行ってください。
本手順を行うことで、ユーザの悪意のある入力等によって偽装されたログエントリが挿入された際、インデントを付加することによって 偽装されたログを判別できるようになります（ログエントリの挿入自体を防ぐことができるわけではありません）。

[手順が必要なケース]

この手順の適用は任意ですが、偽装されたログを判別しやすくなるため、本手順の実施を推奨します。

[修正方法]

プロジェクトのsrc/main/resources/logback.xmlを更新します。

logback.xmlの<pattern>に設定されているログフォーマットを以下のように変更します。

  • %msgを%replace(%msg){'(\r\n|\r|\n)','$1  '}に変更

  • 末尾に%replace(%replace(%xEx){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopexを付与
    ※スタックトレースの書式が既に設定されている場合は、%xExの部分を設定済みの書式に読み替え、設定済みの書式と上記のフォーマットを入れ替える

下記の変更は、ブランクプロジェクトと同様、スタックトレースの書式設定がないコンソールログに半角スペース2文字のインデントを挿入する例です。 これを参考に、プロジェクトのログ出力設定に応じて適切なログフォーマットの変更を行ってください。

【変更前】

  • logback.xml

<appender name="consoleLog" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>[%d{yyyy/MM/dd HH:mm:ss}] [%thread] [%-22logger{22}] [%-5level] %msg%n</pattern>
    </encoder>
</appender>

【変更後】

  • logback.xml

<appender name="consoleLog" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
        <pattern>[%d{yyyy/MM/dd HH:mm:ss}] [%thread] [%-22logger{22}] [%-5level] %replace(%msg){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%xEx){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex</pattern>
    </encoder>
</appender>

2.5. [Step 5] Spring Security OAuth(org.springframework.security.oauth)からSpring Security(org.springframework.security)への移行に伴う対応

Spring Security OAuthが 2022年5月28日にEOL となるため、共通ライブラリの依存関係からSpring Security OAuthを削除しました。これにより、5.7.0まで開発ガイドラインで解説していた実装を変更する必要が生じます。

[手順が必要なケース]

この手順の適用は任意ですが、修正を行うことを推奨します。

2.5.1. [Step 5-1] Spring Security へ移行する場合

以下のすべてのケースに当てはまる場合、ガイドラインの実装を参考にSpring Securityへ移行することが出来ます。

  • 開発ガイドラインに準拠して、Spring Security OAuthを使用しクライアントまたはリソースサーバーの実装を行っている

  • 認可コードグラントを実装している

[修正方法]

開発ガイドラインを参考にして、修正を行ってください。

2.5.2. [Step 5-2] Spring Security へ移行しない場合

プロジェクトのpom.xmlにSpring Security OAuthのライブラリを追加してください。また、Spring Security OAuthのバージョンは2.5.0.RELEASEから2.5.1.RELEASEに更新することを推奨します。なお、Spring Security OAuthは2022年5月にEOLとなるため、代替機能の検討を推奨します。

2.6. [Step 5-2-1] Spring Security OAuthの追加

プロジェクトのpom.xmlにSpring Security OAuthのライブラリを追加してください。

  • pom.xml

<dependencies>
    <!-- omitted -->
    <dependency>
        <groupId>org.springframework.security.oauth</groupId>
        <artifactId>spring-security-oauth2</artifactId>
        <version>2.5.1.RELEASE</version>
    </dependency>
    <!-- omitted -->
</dependencies>

2.7. [Step 5-2-2] アクセストークンの有効期限切れのデフォルト値変更に伴う対応

Spring Security OAuth 2.5.1から、アクセストークンの有効期限切れの考慮に 30秒の遅延時間 が設定されました。これにより、Spring Security OAuth 2.5.0に比べ30秒早く有効期限が切れたと判断されるようになります。

[手順が必要なケース]

以下のケースに当てはまる場合、必要に応じて修正を行ってください。

  • 開発ガイドラインのAppendixに準拠して、Spring Security OAuthを使用しクライアント及び認可サーバーの実装を行っている

  • アクセストークンの有効期限が30秒未満または有効期限を厳密に求められる

[修正方法]

access_token_validity及びrefresh_token_validityの設定値を、30秒の遅延時間を考慮して設定してください。
例えば、60秒でアクセストークンの有効期限切れ、90秒でリフレッシュトークンの有効期限切れとしたい場合、認可サーバー側でアクセストークンの有効期限を90秒、リフレッシュトークンの有効期限を120秒に設定する必要があります。

2.8. [Step 6] Spring Data 2.5.0から非推奨となったAPIへの対応

Spring Data 2.5.0からいくつかのAPIが非推奨となりました。本フレームワークで利用するものは以下の通りです。

  • JpaRepository#deleteInBatch(Iterable)メソッド

5.7.0.RELEASEまでの開発ガイドラインでは紹介していませんが、以下のAPIも非推奨となりました。

  • JpaRepository#getOne(ID)メソッド

Spring Data 2.5.3の非推奨APIについては、以下を参照してください。

[手順が必要なケース]

以下のケースに当てはまる場合、必要に応じて修正を行ってください。

  • 上記の非推奨APIを利用している

[修正方法]

Javadocを参考に、非推奨APIを代替APIに置き換えてください。

JpaRepository#getOne(ID)メソッドの代替APIである JpaRepository#getById(ID)メソッドの使用上の注意に関しては Spring Data提供のインタフェースを継承する を参照してください。

2.9. [Step 7] DBUnitのバージョンの変更に伴う対応

5.7.0までの開発ガイドラインにおける 10.1.2.2. 単体テストで利用するOSSライブラリのバージョン のWarningに記載していたApach POIについて、DBUnitのバージョンを2.7.1 以上に更新することで解消されることを確認しました。これにより、共通ライブラリで管理しているApache POIのバージョンを使用することが出来ます。ただし、DBUnit 2.7.1からApach POIの依存関係はoptionalとなったため、Apach POIを使用するためにはプロジェクトのpom.xmlに依存関係を追加する必要があります。

[手順が必要なケース]

以下のケースに当てはまる場合、必要に応じて修正を行ってください。

[修正方法]

pomファイルのプロパティを修正及び依存関係の追加を行ってください。

  • pom.xml

<dependencies>
    <!-- omitted -->
    <!-- ### 追加箇所 開始 ### -->
    <dependency>
      <groupId>org.apache.poi</groupId>
      <artifactId>poi-ooxml</artifactId>
      <scope>test</scope>
    </dependency>
    <!-- ### 追加箇所 終了 ### -->
</dependencies>

<!-- omitted -->

<properties>
    <!-- omitted -->
    <dbunit.version>2.7.2</dbunit.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
    <poi.version>3.17</poi.version> <!-- ### 削除箇所 ### -->
    <!-- omitted -->
</properties>
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️