forked from quarkusio/quarkus
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request quarkusio#31297 from MichalMaler/QDOCS-99-Revampin…
…g-the-JPA-section Enhancements for the JPA-related content
- Loading branch information
Showing
8 changed files
with
205 additions
and
109 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| [id="security-jpa-concept"] | ||
| = Quarkus Security with JPA | ||
| include::_attributes.adoc[] | ||
| :categories: security | ||
|
|
||
| JPA is an identity provider, similar to xref:security-jdbc.adoc[JDBC], suitable for use with the xref:security-basic-authentication-concept.adoc[Basic] and xref:security-authentication-mechanisms-concept.adoc#form-auth[Form-based] Quarkus Security mechanisms, which require a combination of username and password credentials. | ||
|
|
||
| The JPA `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure. | ||
|
|
||
| For an example of practical use of Basic authentication and JPA, see the xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication and JPA] tutorial. | ||
|
|
||
|
|
||
| == JPA entity specification | ||
|
|
||
| Quarkus security offers a JPA integration to collect usernames, passwords, and roles, and store them into JPA database entities. | ||
|
|
||
| The following JPA entity specification demonstrates how users' information needs to be stored in a JPA entity and properly mapped so that Quarkus can retrieve this information from a database. | ||
|
|
||
|
|
||
| * The `@UserDefinition` annotation must be present on a JPA entity, regardless of whether link:https://quarkus.io/guides/hibernate-orm-panache[simplified Hibernate ORM with Panache] is used or not. | ||
|
|
||
| * The `@Username` and `@Password` field types are always `String`. | ||
|
|
||
| * The `@Roles` field must either be `String`, `Collection<String>`, or a `Collection<X>`, where `X` is an entity class with a single `String` field annotated as `@RolesValue`. | ||
|
|
||
| * Each `String` role element type is parsed as a comma-separated list of roles. | ||
|
|
||
| The following example demonstrates storing security information by adding annotations to the `user` entity: | ||
|
|
||
| [source,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 will be 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(); | ||
| } | ||
| } | ||
| ---- | ||
|
|
||
| The `security-jpa` extension initializes only if a single entity is annotated with `@UserDefinition`. | ||
|
|
||
| <1> The `@UserDefinition` annotation must be present on a single entity, either a regular Hibernate ORM entity or a Hibernate ORM with a Panache entity. | ||
| <2> Indicates the field used for the username. | ||
| <3> Indicates the field used for the password. | ||
| By default, `security-jpa` uses bcrypt-hashed passwords, or you can configure plain text or custom passwords instead. | ||
| <4> This indicates the comma-separated list of roles added to the target principal representation attributes. | ||
| <5> This method allows you to add users while hashing passwords with the proper `bcrypt` hash. | ||
|
|
||
|
|
||
| == JPA entity as storage of roles | ||
|
|
||
| Use the following example to store roles inside another JPA entity: | ||
|
|
||
| [source,java] | ||
| ---- | ||
| @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<ExternalRolesUserEntity> users; | ||
| @RolesValue | ||
| public String role; | ||
| } | ||
| ---- | ||
|
|
||
| == Password storage and hashing | ||
|
|
||
| When developing applications with Quarkus, you can decide how to manage password storage and hashing. You can choose to 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 https://en.wikipedia.org/wiki/Bcrypt[bcrypt] under the | ||
| https://en.wikipedia.org/wiki/Crypt_(C)[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. | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| In cryptography, a salt is a name for random data used as an additional input to a one-way function that hashes data, a password, or a passphrase. | ||
| ==== | ||
|
|
||
| For manual password hashing, create a class that implements the `CustomPasswordProvider`as shown in the example below. | ||
|
|
||
| The following snippet shows how to set a custom password provider that uses the SHA256 hashing algorithm. | ||
|
|
||
| [source,java] | ||
| ---- | ||
| @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; | ||
| } | ||
| public class CustomPasswordProvider implements PasswordProvider { | ||
| @Override | ||
| public Password getPassword(String pass) { | ||
| byte[] digest = DatatypeConverter.parseHexBinary(pass); | ||
| return SimpleDigestPassword.createRaw(SimpleDigestPassword.ALGORITHM_SIMPLE_DIGEST_SHA_256, digest); | ||
| } | ||
| } | ||
| ---- | ||
|
|
||
| [TIP] | ||
| ==== | ||
| For quick creation of 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 desired amount of iterations and the salt used. | ||
| ==== | ||
|
|
||
| [WARNING] | ||
| ==== | ||
| For applications running in a production environment, do not store passwords as plain text. | ||
| However, it is possible to store passwords as plain text with the `@Password(PasswordType.CLEAR)` annotation when operating in a test environment. | ||
| ==== | ||
|
|
||
| == References | ||
|
|
||
| * xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication and JPA] | ||
| * xref:security-identity-providers-concept.adoc[Identity providers] | ||
| * xref:security-overview-concept.adoc[Quarkus Security overview] |
Oops, something went wrong.