バージョン:

Quarkus SecurityとJakarta Persistence

You can configure your application to use Jakarta Persistence to store users' identities.

Quarkus provides a Jakarta Persistence identity provider, similar to the JDBC identity provider. Jakarta Persistence is suitable for use with the Basic and Form-based Quarkus Security mechanisms, which require username and password credentials.

The Jakarta Persistence IdentityProvider creates a SecurityIdentity instance. During user authentication, this instance is used to verify and authorize access requests.

For a practical example, see the Getting started with Security using Basic authentication and Jakarta Persistence tutorial.

Jakarta Persistenceエンティティ仕様

Quarkus security offers a Jakarta Persistence integration to collect usernames, passwords, and roles and store them into Jakarta Persistence database entities.

The following Jakarta Persistence entity specification demonstrates how users' information needs to be stored in a Jakarta Persistence entity and correctly mapped so that Quarkus can retrieve this information from a database.

@UserDefinition アノテーションは、簡略化されたHibernate ORM with Panache が使用されているかどうかに関係なく、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();
    }
}

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

1	The `@UserDefinition` annotation must be present on a single entity, either a regular Hibernate ORM entity or a Hibernate ORM with Panache entity.
2	ユーザー名に使用するフィールドを示します。
3	パスワードに使用するフィールドを示します。デフォルトでは、 `security-jpa` は bcryptでハッシュ化されたパスワードを使用します。代わりにプレーンテキストまたはカスタムパスワードを設定することもできます。
4	ここでは対象のプリンシパル表現属性に追加されたロールのコンマ区切りリストを示します。
5	This method lets you add users while hashing passwords with the proper `bcrypt` hash.

ロールの保存先としての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;
}

This example demonstrates storing and accessing roles. To update an existing user or create a new one, annotate public List<Role> roles with @Cascade(CascadeType.ALL) or choose a specific CascadeType.

パスワードの保存とハッシュ化

When developing applications with Quarkus, you can decide how to manage password storage and hashing. You can keep the default password and hashing settings of Quarkus, or you can hash passwords manually.

With the default option, passwords are stored and hashed with bcrypt under the Modular Crypt Format (MCF). While using MCF, the hashing algorithm, iteration count, and salt are stored as a part of the hashed value. As such, we do not need dedicated columns to keep them.

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

To represent passwords stored in the database that were hashed by different algorithms, create a class that implements org.wildfly.security.password.PasswordProvider as shown in the following example.

The following snippet shows how to set a custom password provider that represents a password that was hashed with the SHA256 hashing algorithm.

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;
}

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);
    }
}

To quickly create a hashed password, use String BcryptUtil.bcryptHash(String password), which defaults to creating a random salt and hashing in ten iterations. This method also allows specifying the number of iterations and salt used.

本番環境で動作するアプリケーションでは、パスワードをプレーンテキストとして保存しないでください。

ただし、テスト環境で運用する場合は、 @Password(PasswordType.CLEAR) のアノテーションでパスワードを平文で保存することが可能です。

The Hibernate Multitenancy is supported, and you can store the user entity in a persistence unit with enabled multitenancy. However, if your io.quarkus.hibernate.orm.runtime.tenant.TenantResolver must access the io.vertx.ext.web.RoutingContext to resolve request details, you must disable proactive authentication. For more information about proactive authentication, see the Quarkus Proactive authentication guide.

ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能

Configuration property	型	デフォルト
`quarkus.security-jpa.persistence-unit-name` Selects the Hibernate ORM persistence unit. Default persistence unit is used when no value is specified. Environment variable: `QUARKUS_SECURITY_JPA_PERSISTENCE_UNIT_NAME` Show more	string	`<default>`

Configuration property

型

デフォルト

quarkus.security-jpa.persistence-unit-name

Selects the Hibernate ORM persistence unit. Default persistence unit is used when no value is specified.

Environment variable: QUARKUS_SECURITY_JPA_PERSISTENCE_UNIT_NAME

string

<default>

参照

Jakarta Persistenceエンティティ仕様
ロールの保存先としてのjakarta Persistenceエンティティ
パスワードの保存とハッシュ化
参照

Quarkus SecurityとJakarta Persistence

Jakarta Persistenceエンティティ仕様

ロールの保存先としてのjakarta Persistenceエンティティ

パスワードの保存とハッシュ化

参照

関連コンテンツ

同一エクステンション

同一トピック