Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

セキュリティーのスタートガイド

Red Hat build of Quarkus 3.20

Red Hat Customer Content Services

概要

このガイドでは、前提条件、アプリケーションのセットアップ、テストを説明しつつ、Basic 認証と Jakarta Persistence を使用して Quarkus アプリケーションを保護する方法を説明します。Maven プロジェクトの作成、依存関係の検証、アプリケーションエンドポイントの記述、ユーザーエンティティーの定義、および Basic 認証の設定を説明します。これには、Dev Services for PostgreSQL を使用したアプリケーションのテスト、curl またはブラウザーを使用したアプリケーションセキュリティーのコンパイル、実行、検証が含まれます。このガイドを読むことで、ロールベースのアクセス制御を実装する方法を理解し、OIDC などのより高度なメカニズムに対応できるようになります。エンティティー仕様、ロールの保存、パスワードのハッシュ化など、セキュリティーのために Jakarta Persistence を使用する方法を詳しく説明します。

Red Hat build of Quarkus ドキュメントへのフィードバックの提供
リンクのコピー

エラーを報告したり、ドキュメントを改善したりするには、Red Hat Jira アカウントにログインし、課題を送信してください。Red Hat Jira アカウントをお持ちでない場合は、アカウントを作成するように求められます。

手順

  1. 次のリンクをクリックして チケットを作成します。
  2. Summary に課題の簡単な説明を入力します。
  3. Description に課題や機能拡張の詳細な説明を入力します。問題があるドキュメントのセクションへの URL も記載してください。
  4. Submit をクリックすると、課題が作成され、適切なドキュメントチームに転送されます。

第1章 Basic 認証と Jakarta Persistence を使用したセキュリティーのスタートガイド
リンクのコピー

組み込みの Quarkus Basic 認証 と Jakarta Persistence アイデンティティープロバイダーを使用して Quarkus アプリケーションエンドポイントを保護し、ロールベースのアクセス制御を有効にすることで、Quarkus Security の使用を開始します。

Jakarta Persistence IdentityProvider は、Basic 認証 のユーザー名とパスワードのペアを検証して、アクセス要求の許可に使用される SecurityIdentity インスタンスに変換します。これにより、Quarkus アプリケーションがセキュアになります。

Jakarta Persistence の詳細は、Jakarta Persistence を使用した Quarkus Security を参照してください。

このチュートリアルでは、OpenID Connect (OIDC) 認証メカニズムの使用方法など、Quarkus でより高度なセキュリティーメカニズムを実装するための準備を行います。

1.1. 前提条件
リンクのコピー

このガイドを完了するには、以下が必要です。

  • 約 15 分
  • IDE
  • JAVA_HOME が適切に設定された状態でインストールされた JDK 17 以降
  • Apache Maven 3.8.6 以降
  • オプション: Quarkus CLI (使用する場合)
  • オプション: ネイティブ実行可能ファイルをビルドする場合は、インストールおよび 適切に設定された Mandrel または GraalVM (ネイティブコンテナービルドを使用する場合は Docker)。

1.2. アプリケーションのビルド
リンクのコピー

このチュートリアルでは、さまざまな認可ポリシーを示すエンドポイントを使用してアプリケーションを作成する詳細な手順を示します。

Expand
Endpoint (エンドポイント)説明

/api/public

このエンドポイントは認証なしでアクセス可能で、匿名アクセスを使用できます。

/api/admin

ロールベースのアクセス制御 (RBAC) で保護されたこのエンドポイントには、admin ロールを持つユーザーのみがアクセスできます。アクセスは、@RolesAllowed アノテーションを使用して宣言的に制御されます。

/api/users/me

このエンドポイントも RBAC によって保護されており、user ロールを持つユーザーのみがアクセスできます。呼び出し元のユーザー名を文字列として返します。

ヒント

完成例を確認するには、アーカイブ をダウンロードするか、Git リポジトリーのクローンを作成します。 

git clone https://github.com/quarkusio/quarkus-quickstarts.git -b 3.20
Copy to Clipboard Toggle word wrap

ソリューションは、security-jpa-quickstart ディレクトリー にあります。

1.3. Maven プロジェクトの作成および検証
リンクのコピー

Quarkus Security がセキュリティーソースを Jakarta Persistence エンティティーにマップできるようにするには、このチュートリアルの Maven プロジェクトに quarkus-security-jpa エクステンションが含まれていることを確認してください。

注記

ユーザー ID の保存には、Hibernate ORM with Panache が使用されます。ただし、Hibernate ORM と quarkus-security-jpa エクステンションを使用することもできます。

任意のデータベースコネクターライブラリーも追加する必要があります。このサンプルチュートリアルの手順では、アイデンティティーストアに PostgreSQL データベースを使用します。

1.3.1. Maven プロジェクトの作成
リンクのコピー

Security Jakarta Persistence エクステンションを使用して新しい Maven プロジェクトを作成したり、既存の Maven プロジェクトに拡張機能を追加したりできます。Hibernate ORM または Hibernate Reactive のいずれかを使用できます。

1.3.1.1. 新しい Maven プロジェクトの作成
リンクのコピー

  • Jakarta Persistence エクステンションで新しい Maven プロジェクトを作成するには、以下のいずれかの手順を実行します。

    • Hibernate ORM を使用して Maven プロジェクトを作成するには、次のコマンドを使用します。

  • Quarkus CLI を使用する場合: 

    quarkus create app org.acme:security-jpa-quickstart \
    --extension='security-jpa,jdbc-postgresql,rest,hibernate-orm-panache' \
    --no-code
cd security-jpa-quickstart
    Copy to Clipboard Toggle word wrap

    Gradle プロジェクトを作成するには、--gradle オプションまたは --gradle-kotlin-dsl オプションを追加します。

    Quarkus CLI のインストール方法と使用方法の詳細は、Quarkus CLI ガイドを参照してください。

  • Maven を使用する場合: 

    mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.20.1:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-jpa-quickstart \
    -Dextensions='security-jpa,jdbc-postgresql,rest,hibernate-orm-panache' \
    -DnoCode
cd security-jpa-quickstart
    Copy to Clipboard Toggle word wrap

    Gradle プロジェクトを作成するには、-DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windows ユーザーの場合:

  • cmd を使用する場合は、バックスラッシュ \ を使用せず、すべてを同じ行に記述してください。
  • Powershell を使用する場合は、-D パラメーターを二重引用符で囲みます (例: "-DprojectArtifactId=security-jpa-quickstart")。
1.3.1.2. 既存のプロジェクトに Jakarta Persistence 拡張機能を追加する
リンクのコピー

  • 既存の Maven プロジェクトに Jakarta Persistence エクステンションを追加するには、次のいずれかの手順を実行します。

    • Hibernate ORM を使用して既存の Maven プロジェクトに Security Jakarta Persistence エクステンションを追加するには、プロジェクトベースディレクトリーから次のコマンドを実行します。

      • Quarkus CLI を使用する場合: 

        quarkus extension add security-jpa
        Copy to Clipboard Toggle word wrap

      • Maven を使用する場合: 

        ./mvnw quarkus:add-extension -Dextensions='security-jpa'
        Copy to Clipboard Toggle word wrap

      • Gradle を使用する場合: 

        ./gradlew addExtension --extensions='security-jpa'
        Copy to Clipboard Toggle word wrap

1.3.2. quarkus-security-jpa 依存関係の確認
リンクのコピー

上記のいずれかのコマンドを実行して Maven プロジェクトを作成した後、quarkus-security-jpa 依存関係がプロジェクトビルド XML ファイルに追加されたことを確認します。

  • quarkus-security-jpa エクステンションを確認するには、以下の設定を確認します。

    • Maven を使用する場合: 

      <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-security-jpa</artifactId>
</dependency>
      Copy to Clipboard Toggle word wrap

    • Gradle を使用する場合: 

      implementation("io.quarkus:quarkus-security-jpa")
      Copy to Clipboard Toggle word wrap

1.4. アプリケーションの作成
リンクのコピー

  • 次のいずれかの方法を使用して、API エンドポイントを保護し、アプリケーションにアクセスできるユーザーを決定します。

    • すべてのユーザーがアプリケーションにアクセスできるように、/api/public エンドポイントを実装します。次のコードスニペットに示すように、通常の Jakarta REST リソースを Java ソースコードに追加します。

      src/main/java/org/acme/security/jpa/PublicResource.java

      package org.acme.security.jpa;

import jakarta.annotation.security.PermitAll;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/api/public")
public class PublicResource {

    @GET
    @PermitAll
    @Produces(MediaType.TEXT_PLAIN)
    public String publicResource() {
        return "public";
   }
}
      Copy to Clipboard Toggle word wrap

    • 管理者ロールを持つユーザーのみがアクセスできる /api/admin エンドポイントを実装します。/api/admin エンドポイントのソースコードも同様ですが、代わりに @RolesAllowed アノテーションを使用して、admin ロールが付与されたユーザーのみがエンドポイントにアクセスできるようにします。以下の @RolesAllowed アノテーションを使用して Jakarta REST リソースを追加します。

      src/main/java/org/acme/security/jpa/AdminResource.java

      package org.acme.security.jpa;

import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/api/admin")
public class AdminResource {

    @GET
    @RolesAllowed("admin")
    @Produces(MediaType.TEXT_PLAIN)
    public String adminResource() {
         return "admin";
    }
}
      Copy to Clipboard Toggle word wrap

    • user ロールを持つユーザーのみがアクセスできる /api/users/me エンドポイントを実装します。SecurityContext を使用して、現在認証されている Principal ユーザーにアクセスし、そのユーザー名を返します。これらはすべてデータベースから取得されます。

      src/main/java/org/acme/security/jpa/UserResource.java

      package org.acme.security.jpa;

import jakarta.annotation.security.RolesAllowed;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.Context;
import jakarta.ws.rs.core.SecurityContext;

@Path("/api/users")
public class UserResource {

    @GET
    @RolesAllowed("user")
    @Path("/me")
    public String me(@Context SecurityContext securityContext) {
        return securityContext.getUserPrincipal().getName();
    }
}
      Copy to Clipboard Toggle word wrap

1.5. ユーザーエンティティーの定義
リンクのコピー

次のアノテーションを user エンティティーに追加して、セキュリティー情報をモデルに保存する方法を指定します。

src/main/java/org/acme/security/jpa/User.java

package org.acme.security.jpa;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

import io.quarkus.hibernate.orm.panache.PanacheEntity;
import io.quarkus.elytron.security.common.BcryptUtil;
import io.quarkus.security.jpa.Password;
import io.quarkus.security.jpa.Roles;
import io.quarkus.security.jpa.UserDefinition;
import io.quarkus.security.jpa.Username;

@Entity
@Table(name = "test_user")
@UserDefinition
1 

public class User extends PanacheEntity {
    @Username
2 

    public String username;
    @Password
3 

    public String password;
    @Roles
4 

    public String role;

    /**
     * Adds a new user to the database
     * @param username the username
     * @param password the unencrypted password (it is encrypted with bcrypt)
     * @param role the comma-separated roles
     */
    public static void add(String username, String password, String role) {
5 

        User user = new User();
        user.username = username;
        user.password = BcryptUtil.bcryptHash(password);
        user.role = role;
        user.persist();
    }
}
Copy to Clipboard Toggle word wrap

quarkus-security-jpa エクステンションは、単一のエンティティーに @UserDefinition アノテーションが付けられている場合にのみ初期化されます。

1
@UserDefinition アノテーションは、単一のエンティティー (通常の Hibernate ORM エンティティーまたは Hibernate ORM with Panache エンティティー) に存在する必要があります。
2
ユーザー名に使用されるフィールドを示します。
3
パスワードに使用されるフィールドを示します。デフォルトでは、bcrypt でハッシュされたパスワードを使用します。プレーンテキストまたはカスタムパスワードを使用するように設定できます。
4
ターゲットプリンシパル表現属性に追加されたロールのコンマ区切りリストを示します。
5
適切な bcrypt ハッシュを使用してパスワードをハッシュ化して、ユーザーを追加できます。
注記

必ず Panache と PostgreSQL JDBC ドライバーをセットアップしてください。詳細は Setting up and configuring Hibernate ORM with Panache を参照してください。

1.6. アプリケーションの設定
リンクのコピー

  1. quarkus.http.auth.basic プロパティーを true に設定して、組み込みの Quarkus Basic 認証 メカニズムを有効にします。

    quarkus.http.auth.basic=true

    注記

    アクセスをセキュアにする必要があり、他の認証メカニズムが有効になっていない場合は、Quarkus に組み込まれている Basic 認証 がフォールバック認証メカニズムになります。したがって、このチュートリアルでは、プロパティー quarkus.http.auth.basic を true に設定する必要はありません。

  2. quarkus-security-jpa エクステンションがデータベースにアクセスできるように、src/main/resources/application.properties ファイルで少なくとも 1 つのデータソースを設定します。以下に例を示します。

    src/main/resources/application.properties

    quarkus.http.auth.basic=true

%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.username=quarkus
%prod.quarkus.datasource.password=quarkus
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql:quarkus

quarkus.hibernate-orm.database.generation=drop-and-create
    Copy to Clipboard Toggle word wrap

    プロファイル接頭辞の %prod. を追加することで、本番モードで実行されているアプリケーションによってのみデータソースプロパティーが監視されるようになります。

  3. ユーザーとロールを使用してデータベースを初期化するには、次のコードスニペットに示すように、Startup クラスを実装します。

src/main/java/org/acme/security/jpa/Startup.java

package org.acme.security.jpa;

import jakarta.enterprise.event.Observes;
import jakarta.inject.Singleton;
import jakarta.transaction.Transactional;

import io.quarkus.runtime.StartupEvent;


@Singleton
public class Startup {
    @Transactional
    public void loadUsers(@Observes StartupEvent evt) {
        // reset and load all test users
        User.deleteAll();
        User.add("admin", "admin", "admin");
        User.add("user", "user", "user");
    }
}
Copy to Clipboard Toggle word wrap

上記の例は、指定されたデータベースによってアプリケーションがどのように保護されて ID が提供されるかを示しています。

重要

実稼働環境では、プレーンテキストのパスワードを保存しないでください。そのため、quarkus-security-jpa はデフォルトで bcrypt でハッシュされたパスワードを使用します。

1.7. Dev Services for PostgreSQL を使用した開発モードでのアプリケーションのテスト
リンクのコピー

アプリケーションを本番モードで実行する前に、Dev Services for PostgreSQL を使用して、JVM モードとネイティブモードでアプリケーションの結合テストを完了します。

まず、テストプロジェクトに次の依存関係を追加します。

  • Maven を使用する場合: 

    <dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>rest-assured</artifactId>
    <scope>test</scope>
</dependency>
    Copy to Clipboard Toggle word wrap

  • Gradle を使用する場合: 

    testImplementation("io.rest-assured:rest-assured")
    Copy to Clipboard Toggle word wrap

アプリケーションを開発モードで実行するには、以下を実行します。

  • Quarkus CLI を使用する場合: 

    quarkus dev
    Copy to Clipboard Toggle word wrap

  • Maven を使用する場合: 

    ./mvnw quarkus:dev
    Copy to Clipboard Toggle word wrap

  • Gradle を使用する場合: 

    ./gradlew --console=plain quarkusDev
    Copy to Clipboard Toggle word wrap

このシナリオでは、Dev Services for PostgreSQL が PostgreSQL テストコンテナーを起動して設定します。Podman または Docker のいずれかがコンピューターにインストールされていることを確認してください。

結合テストを記述するには、次のコードサンプルを使用します。

src/test/java/org/acme/security/jpa/JpaSecurityRealmTest.java

package org.acme.security.jpa;

import static io.restassured.RestAssured.get;
import static io.restassured.RestAssured.given;
import static org.hamcrest.core.Is.is;

import org.apache.http.HttpStatus;
import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
public class JpaSecurityRealmTest {

    @Test
    void shouldAccessPublicWhenAnonymous() {
        get("/api/public")
                .then()
                .statusCode(HttpStatus.SC_OK);

    }

    @Test
    void shouldNotAccessAdminWhenAnonymous() {
        get("/api/admin")
                .then()
                .statusCode(HttpStatus.SC_UNAUTHORIZED);

    }

    @Test
    void shouldAccessAdminWhenAdminAuthenticated() {
        given()
                .auth().preemptive().basic("admin", "admin")
                .when()
                .get("/api/admin")
                .then()
                .statusCode(HttpStatus.SC_OK);

    }

    @Test
    void shouldNotAccessUserWhenAdminAuthenticated() {
        given()
                .auth().preemptive().basic("admin", "admin")
                .when()
                .get("/api/users/me")
                .then()
                .statusCode(HttpStatus.SC_FORBIDDEN);
    }

    @Test
    void shouldAccessUserAndGetIdentityWhenUserAuthenticated() {
        given()
                .auth().preemptive().basic("user", "user")
                .when()
                .get("/api/users/me")
                .then()
                .statusCode(HttpStatus.SC_OK)
                .body(is("user"));
    }
}
Copy to Clipboard Toggle word wrap

このコードサンプルからわかるように、テストコードからテストコンテナーを起動する必要はありません。

これらのテストを実行するには、開発モードでアプリケーションを起動した後、コンソールに表示される Press [r] to resume testing オプションを選択します。

注記

開発モードでアプリケーションを起動すると、Dev Services for PostgreSQL は PostgreSQL 開発モードコンテナーを起動して、アプリケーションの開発を開始できるようにします。アプリケーションの開発中に、継続的テスト 機能を使用してテストを個別に追加および実行できます。Dev Services for PostgreSQL は、開発モードコンテナーと競合しない別の PostgreSQL テストコンテナーを提供することで、開発中のテストをサポートします。

または、Maven を使用してこれらのテストを実行することもできます。 

./mvnw test
Copy to Clipboard Toggle word wrap

1.8. Curl またはブラウザーを使用した本番モードでのアプリケーションのテスト
リンクのコピー

Curl またはブラウザーを使用してアプリケーションをテストするには、まず PostgreSQL サーバーを起動します。次に、JVM モードまたはネイティブモードのいずれかでアプリケーションをコンパイルして実行します。

1.8.1. PostgreSQL サーバーの起動
リンクのコピー

docker run --rm=true --name security-getting-started -e POSTGRES_USER=quarkus \
           -e POSTGRES_PASSWORD=quarkus -e POSTGRES_DB=quarkus \
           -p 5432:5432 postgres:17
Copy to Clipboard Toggle word wrap

1.8.2. アプリケーションのコンパイルおよび実行
リンクのコピー

  • 以下の方法のいずれかを使用して、Quarkus アプリケーションをコンパイルして実行します。

    • JVM モード

      1. アプリケーションをコンパイルします。

        • Quarkus CLI を使用する場合: 

          quarkus build
          Copy to Clipboard Toggle word wrap

        • Maven を使用する場合: 

          ./mvnw install
          Copy to Clipboard Toggle word wrap

        • Gradle を使用する場合: 

          ./gradlew build
          Copy to Clipboard Toggle word wrap

      2. アプリケーションを実行します。 

        java -jar target/quarkus-app/quarkus-run.jar
        Copy to Clipboard Toggle word wrap

    • ネイティブモード

      1. アプリケーションをコンパイルします。

        • Quarkus CLI を使用する場合: 

          quarkus build --native
          Copy to Clipboard Toggle word wrap

        • Maven を使用する場合: 

          ./mvnw install -Dnative
          Copy to Clipboard Toggle word wrap

        • Gradle を使用する場合: 

          ./gradlew build -Dquarkus.native.enabled=true
          Copy to Clipboard Toggle word wrap

      2. アプリケーションを実行します。 

        ./target/security-jpa-quickstart-1.0.0-SNAPSHOT-runner
        Copy to Clipboard Toggle word wrap

1.8.3. Curl を使用してアプリケーションのセキュリティーにアクセスしてテストする
リンクのコピー

アプリケーションの実行中に、以下の Curl コマンドのいずれかを使用してエンドポイントにアクセスできます。

  • 保護されたエンドポイントに匿名で接続します。 

    $ curl -i -X GET http://localhost:8080/api/public

HTTP/1.1 200 OK
Content-Length: 6
Content-Type: text/plain;charset=UTF-8

public
    Copy to Clipboard Toggle word wrap

  • 保護されたエンドポイントに匿名で接続します。 

    $ curl -i -X GET http://localhost:8080/api/admin

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic
    Copy to Clipboard Toggle word wrap

  • 承認されたユーザーとして保護されたエンドポイントに接続します。 

    $ curl -i -X GET -u admin:admin http://localhost:8080/api/admin

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: text/plain;charset=UTF-8

admin
    Copy to Clipboard Toggle word wrap

ブラウザーを使用して同じエンドポイント URL にアクセスすることもできます。

1.8.4. ブラウザーでアプリケーションのセキュリティーにアクセスしてテストする
リンクのコピー

ブラウザーを使用して保護されたリソースに匿名で接続する場合は、Basic 認証フォームが表示され、認証情報の入力を求められます。

1.8.5. 結果
リンクのコピー

admin:admin などの承認済みユーザーの認証情報を提供すると、Jakarta Persistence セキュリティーエクステンションによりユーザーのロールが認証され、読み込まれます。admin ユーザーには、保護されたリソースにアクセスする権限が与えられます。

リソースが @RolesAllowed ("user") で保護されている場合は、次の例に示すように、admin ユーザーは、"user" ロールに割り当てられていないため、リソースにアクセスする権限がありません。 

$ curl -i -X GET -u admin:admin http://localhost:8080/api/users/me

HTTP/1.1 403 Forbidden
Copy to Clipboard Toggle word wrap

最後に、user という名前のユーザーが承認され、セキュリティーコンテキストにはユーザー名などのプリンシパルの詳細が含まれます。 

$ curl -i -X GET -u user:user http://localhost:8080/api/users/me

HTTP/1.1 200 OK
Content-Length: 4
Content-Type: text/plain;charset=UTF-8

user
Copy to Clipboard Toggle word wrap

1.9. 次のステップ
リンクのコピー

このガイドでは、セキュアな Quarkus アプリケーションを作成してテストする方法を説明しました。これを実現するために、Quarkus に組み込まれている Basic 認証 を Jakarta Persistence アイデンティティープロバイダーと統合しました。

このチュートリアルを完了したら、Quarkus のより高度なセキュリティーメカニズムを調べることを推奨します。次の資料では、OpenID Connect を使用して Quarkus エンドポイントへのシングルサインオンアクセスをセキュアに実行する方法を示しています。

1.10. 参考資料
リンクのコピー

第2章 Jakarta Persistence を使用した Quarkus Security
リンクのコピー

Jakarta Persistence を使用してユーザーの ID を保存するようにアプリケーションを設定できます。

Quarkus は、JDBC アイデンティティープロバイダー に似た Jakarta Persistence アイデンティティープロバイダーを提供します。Jakarta Persistence は、ユーザー名とパスワードの認証情報を必要とする Basic および フォームベース の Quarkus Security メカニズムでの使用に適しています。

Jakarta Persistence IdentityProvider は SecurityIdentity インスタンスを作成します。ユーザー認証中、このインスタンスはアクセス要求の検証と承認に使用されます。

実際の例は、Basic 認証と Jakarta Persistence を使用したセキュリティーのスタートガイド のチュートリアルを参照してください。

2.1. Jakarta Persistence エンティティー仕様
リンクのコピー

Quarkus セキュリティーは、ユーザー名、パスワード、ロールを収集し、それらを Jakarta Persistence データベースエンティティーに保存するために Jakarta Persistence を統合します。

次の Jakarta Persistence エンティティー仕様は、Quarkus がデータベースからこの情報を取得できるように、ユーザーの情報を Jakarta Persistence エンティティーに保存し、正しくマッピングする方法を示しています。

  • Jakarta Persistence エンティティーには、@UserDefinition アノテーションが存在する必要があります。Panache による Hibernate ORM の簡略化 が使用されているかどうかは関係ありません。
  • @Username および @Password フィールドタイプは常に String です。
  • @Roles フィールドは、String、Collection<String>、または Collection<X> のいずれかである必要があります。ここで、X は、@RolesValue としてアノテーションが付けられた単一の String フィールドを持つエンティティークラスです。
  • 各 String ロール要素タイプは、コンマで区切られたロールのリストとして解析されます。

次の例は、user エンティティーにアノテーションを追加してセキュリティー情報を保存する方法を示しています。 

package org.acme.security.jpa;

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

import io.quarkus.hibernate.orm.panache.PanacheEntity;
import io.quarkus.elytron.security.common.BcryptUtil;
import io.quarkus.security.jpa.Password;
import io.quarkus.security.jpa.Roles;
import io.quarkus.security.jpa.UserDefinition;
import io.quarkus.security.jpa.Username;

@Entity
@Table(name = "test_user")
1 

@UserDefinition
2 

public class User extends PanacheEntity {
    @Username
3 

    public String username;
    @Password
4 

    public String password;
    @Roles
5 

    public String role;

    /**
     * Adds a new user to the database
     * @param username the username
     * @param password the unencrypted password (it is encrypted with bcrypt)
     * @param role the comma-separated roles
     */
    public static void add(String username, String password, String role) {
6 

        User user = new User();
        user.username = username;
        user.password = BcryptUtil.bcryptHash(password);
        user.role = role;
        user.persist();
    }
}
Copy to Clipboard Toggle word wrap

quarkus-security-jpa エクステンションは、単一のエンティティーに @UserDefinition アノテーションが付けられている場合にのみ初期化されます。

1
テーブル名。user として定義しないでください。これは、ほとんどのデータベースで制限されているキーワードです。
2
@UserDefinition アノテーションは、単一のエンティティー (通常の Hibernate ORM エンティティーまたは Hibernate ORM with Panache エンティティー) に存在する必要があります。
3
ユーザー名に使用されるフィールドを示します。
4
パスワードに使用されるフィールドを示します。デフォルトでは、quarkus-security-jpa は bcrypt ハッシュパスワードを使用しますが、代わりにプレーンテキストまたはカスタムパスワードを設定することもできます。
5
これは、ターゲットプリンシパル表現属性に追加されたロールのコンマ区切りリストを示します。
6
この方法を使用すると、適切な bcrypt ハッシュを使用してパスワードをハッシュ化し、ユーザーを追加できます。

2.2. ロールのストレージとしての Jakarta Persistence エンティティー
リンクのコピー

次の例を使用して、別の Jakarta Persistence エンティティー内にロールを保存します。 

@UserDefinition
@Table(name = "test_user")
@Entity
public class User extends PanacheEntity {
    @Username
    public String name;

    @Password
    public String pass;

    @ManyToMany
    @Roles
    public List<Role> roles = new ArrayList<>();
}

@Entity
public class Role extends PanacheEntity {

    @ManyToMany(mappedBy = "roles")
    public List<User> users;

    @RolesValue
    public String role;
}
Copy to Clipboard Toggle word wrap
注記

この例では、ロールの保存とアクセスを示します。既存のユーザーを更新したり、新しいユーザーを作成したりするには、public List<Role> roles に @Cascade(CascadeType.ALL) をアノテーションするか、特定の CascadeType を選択します。

2.3. パスワードストレージおよびハッシュ
リンクのコピー

Quarkus を使用してアプリケーションを開発する場合は、パスワードの保存とハッシュの管理方法を決定できます。Quarkus のデフォルトのパスワードとハッシュ設定をそのまま使用することも、手動でパスワードをハッシュすることもできます。

デフォルトオプションでは、パスワードは Modular Crypt Format (MCF) に基づいて bcrypt で保存およびハッシュされます。MCF を使用する場合は、ハッシュアルゴリズム、反復回数、および salt はハッシュ値の一部として保存されます。そのため、それらを保存するための専用の列は必要ありません。

注記

暗号化において、salt とは、データ、パスワード、またはパスフレーズをハッシュする一方向関数への追加入力として使用されるランダムデータの名前です。

異なるアルゴリズムによってハッシュされ、データベースに保存されているパスワードを表すには、次の例に示すように、org.wildfly.security.password.PasswordProvider を実装するクラスを作成します。

次のスニペットは、SHA256 ハッシュアルゴリズムでハッシュされたパスワードを表すカスタムパスワードプロバイダーを設定する方法を示しています。 

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

import io.quarkus.security.jpa.Password;
import io.quarkus.security.jpa.PasswordType;
import io.quarkus.security.jpa.Roles;
import io.quarkus.security.jpa.UserDefinition;
import io.quarkus.security.jpa.Username;

@UserDefinition
@Table(name = "test_user")
@Entity
public class CustomPasswordUserEntity {
    @Id
    @GeneratedValue
    public Long id;

    @Column(name = "username")
    @Username
    public String name;

    @Column(name = "password")
    @Password(value = PasswordType.CUSTOM, provider = CustomPasswordProvider.class)
    public String pass;

    @Roles
    public String role;
}
Copy to Clipboard Toggle word wrap 
import jakarta.xml.bind.DatatypeConverter;

import org.wildfly.security.password.Password;
import org.wildfly.security.password.interfaces.SimpleDigestPassword;

import io.quarkus.security.jpa.PasswordProvider;

public class CustomPasswordProvider implements PasswordProvider {
    @Override
    public Password getPassword(String passwordInDatabase) {
        byte[] digest = DatatypeConverter.parseHexBinary(passwordInDatabase);

        // Let the security runtime know that this passwordInDatabase is hashed by using the SHA256 hashing algorithm
        return SimpleDigestPassword.createRaw(SimpleDigestPassword.ALGORITHM_SIMPLE_DIGEST_SHA_256, digest);
    }
}
Copy to Clipboard Toggle word wrap
ヒント

ハッシュ化されたパスワードをすばやく作成するには、String BcryptUtil.bcryptHash (String password) を使用します。デフォルトでは、ランダムな salt が作成され、反復 10 回分、ハッシュ化されます。このメソッドでは、使用される反復回数と salt の数を指定することもできます。

警告

実稼働環境で実行されるアプリケーションの場合は、パスワードをプレーンテキストとして保存しないでください。

ただし、テスト環境で操作する場合は、@Password (PasswordType.CLEAR) アノテーションを使用してパスワードをプレーンテキストとして保存できます。

ヒント

Hibernate マルチテナンシー がサポートされており、マルチテナンシーが有効な永続ユニットにユーザーエンティティーを保存できます。ただし、io.quarkus.hibernate.orm.runtime.tenant.TenantResolver が io.vertx.ext.web.RoutingContext にアクセスしてリクエストの詳細を解決する必要がある場合は、プロアクティブ認証を無効にする必要があります。プロアクティブ認証の詳細は、Quarkus の プロアクティブ認証 ガイドを参照してください。

🔒 ビルド時に固定: 設定プロパティーはビルド時に固定されます。他のすべての設定プロパティーは実行時にオーバーライドできます。

Expand

設定プロパティー

型

デフォルト

🔒 ビルド時に修正 quarkus.security-jpa.persistence-unit-name

Hibernate ORM 永続ユニットを選択します。値の指定がない場合はデフォルトの永続ユニットが使用されます。

環境変数: QUARKUS_SECURITY_JPA_PERSISTENCE_UNIT_NAME

string

<default>

2.4. 参考資料
リンクのコピー

法律上の通知
リンクのコピー

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る