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

セキュリティーの使用

Red Hat build of Quarkus 3.8

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 をクリックすると、課題が作成され、適切なドキュメントチームに転送されます。

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、用語の置き換えは、今後の複数のリリースにわたって段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。

第1章 Basic 認証と Jakarta Persistence を使用する Security のスタートガイド
リンクのコピー

組み込みの 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
  • JAV_HOME が適切に設定された状態でインストールされた JDK 17+
  • Apache Maven 3.9.6
  • オプションで使用する場合は Quarkus CLI
  • ネイティブ実行可能ファイル (ネイティブコンテナービルドを使用する場合は Docker) をビルドする必要がある場合は、オプションで Mandrel または GraalVM がインストールされ、適切に設定されている

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.8
Copy to Clipboard Toggle word wrap

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

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

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

注記

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

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

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

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

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

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

  • Quarkus CLI を使用: 

    quarkus create app org.acme:security-jpa-quickstart \
    --extension='security-jpa,jdbc-postgresql,resteasy-reactive,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 io.quarkus.platform:quarkus-maven-plugin:3.8.5:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-jpa-quickstart \
    -Dextensions='security-jpa,jdbc-postgresql,resteasy-reactive,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")。

    • 既存の 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 ソースコードに追加します。 

      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 リソースを追加します。 

      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 ユーザーにアクセスし、そのユーザー名を返します。これらはすべてデータベースから取得されます。 

      package org.acme.security.jpa;

import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Inject;
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 エンティティーにアノテーションを追加することで、セキュリティー情報をモデルに保存する方法を説明できるようになりました。 
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 エンティティーまたは Panache エンティティーを含む Hibernate ORM のいずれかの単一のエンティティーに存在する必要があります。
2
ユーザー名に使用されるフィールドを示します。
3
パスワードに使用されるフィールドを示します。デフォルトでは、bcrypt でハッシュされたパスワードを使用します。プレーンテキストまたはカスタムパスワードを使用するように設定できます。
4
ターゲットプリンシパル表現属性に追加されたロールのコンマ区切りリストを示します。
5
適切な bcrypt ハッシュを使用してパスワードをハッシュ化して、ユーザーを追加できます。
注記

Panache と PostgreSQL JDBC ドライバーの設定を忘れないでください。詳細は Panache を使用した Hibernate ORM の設定 を参照してください。

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 エクステンションがデータベースにアクセスできるように、application.properties ファイルで少なくとも 1 つのデータソースを設定します。以下に例を示します。 

    quarkus.http.auth.basic=true

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

quarkus.hibernate-orm.database.generation=drop-and-create
    Copy to Clipboard Toggle word wrap
  3. ユーザーとロールを使用してデータベースを初期化するには、次のコードスニペットに示すように、Startup クラスを実装します。 
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. PostgreSQL 用 Dev Services を使用したアプリケーションのテスト
リンクのコピー

アプリケーションを実稼働モードで実行する前に、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
  • アプリケーションを dev モードで実行するには、以下を実行します。

  • 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
  • 次のプロパティー設定は、PostgreSQL テストを本番 (prod) モードでのみ実行できるようにする方法を示しています。このシナリオでは、Dev Services for PostgreSQL が PostgreSQL テストコンテナーを起動して設定します。 
%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.username=quarkus
%prod.quarkus.datasource.password=quarkus
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql:elytron_security_jpa

quarkus.hibernate-orm.database.generation=drop-and-create
Copy to Clipboard Toggle word wrap
  • %prod. プロファイル接頭辞を追加すると、データソースプロパティーは Dev Services for PostgreSQL には表示されなくなり、運用モードで実行されているアプリケーションによってのみ監視されます。
  • 統合テストを記述するには、次のコードサンプルを使用します。 
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

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

注記

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

1.7.1. curl またはブラウザーを使用したアプリケーションのテスト
リンクのコピー

  • 次の例を使用して、PostgreSQL サーバーを起動します。 
docker run --rm=true --name security-getting-started -e POSTGRES_USER=quarkus \
           -e POSTGRES_PASSWORD=quarkus -e POSTGRES_DB=elytron_security_jpa \
           -p 5432:5432 postgres:14.1
Copy to Clipboard Toggle word wrap

1.7.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.package.type=native
          Copy to Clipboard Toggle word wrap

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

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

1.7.3. アプリケーションのセキュリティーへのアクセスおよびテスト
リンクのコピー

アプリケーションの実行中に、以下の 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
Content-Length: 14
Content-Type: text/html;charset=UTF-8
WWW-Authenticate: Basic

Not authorized
    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 にアクセスすることもできます。

注記

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

1.7.4. Results
リンクのコピー

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
Content-Length: 34
Content-Type: text/html;charset=UTF-8

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.8. 次回予告
リンクのコピー

安全な Quarkus アプリケーションを作成し、テストする方法を学習しました。これは、Quarkus に組み込まれている Basic 認証 を Jakarta Persistence アイデンティティープロバイダーと統合することによって実現されました。

このチュートリアルを完了すると、Quarkus のより高度なセキュリティーメカニズムを使用することができます。次の情報は、Quarkus エンドポイントへの安全なシングルサインオンアクセスに OpenID Connect を使用する方法を示しています。

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

第2章 Jakarta Persistence を備えた Quarkus Security
リンクのコピー

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

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

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

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

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

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

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

  • Panache を使用した簡略化された Hibernate ORM が使用されているかどうかに関係なく、@UserDefinition アノテーションは Jakarta Persistence エンティティーに存在する必要があります。
  • @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")
@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 エンティティーまたは Panache エンティティーを含む Hibernate ORM のいずれかの単一のエンティティーに存在する必要があります。
2
ユーザー名に使用されるフィールドを示します。
3
パスワードに使用されるフィールドを示します。デフォルトでは、quarkus-security-jpa は bcrypt ハッシュパスワードを使用しますが、代わりにプレーンテキストまたはカスタムパスワードを設定することもできます。
4
これは、ターゲットプリンシパル表現属性に追加されたロールのコンマ区切りリストを示します。
5
この方法を使用すると、適切な 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 プロアクティブ認証 ガイドを参照してください。

lock ビルド時に固定された設定プロパティー: その他の設定プロパティーはすべて実行時にオーバーライド可能

Expand

設定プロパティー

型

デフォルト

lock 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トップに戻る