-
Notifications
You must be signed in to change notification settings - Fork 2.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Enhancements for the JPA-related content
Signed-off-by: Michal Maléř <[email protected]> Adding additional content Signed-off-by: Michal Maléř <[email protected]> Adding references Signed-off-by: Michal Maléř <[email protected]> Fixes Signed-off-by: Michal Maléř <[email protected]> Apply suggestions from code review Co-authored-by: Michelle Purcell <[email protected]> Fixes Signed-off-by: Michal Maléř <[email protected]>
- Loading branch information
1 parent
176030c
commit 1ae524c
Showing
8 changed files
with
204 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, it uses bcrypt-hashed passwords, and you can configure it to use plain text or custom passwords. | ||
| <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 | ||
|
|
||
| Regarding password storage and hashing management from a developer perspective, you can decide if you want to keep the settings as it is and use the Quarkus default or 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] | ||
| ==== | ||
| Never store passwords as a plain text for applications already running in production. | ||
| 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.