Merge pull request quarkusio#37844 from rolfedh/QDOCS-566

Edit security-jpa.adoc

docs/src/main/asciidoc/security-jpa.adoc

@@ -11,18 +11,18 @@ include::_attributes.adoc[]
 :topics: security,identity-providers,sql,database,jpa,jdbc
 :extensions: io.quarkus:quarkus-security-jpa-reactive
 
-Quarkus provides a Jakarta Persistence (formerly known as JPA) identity provider, similar to the xref:security-jdbc.adoc[JDBC identity provider], suitable for use with the xref:security-basic-authentication.adoc[Basic] and xref:security-authentication-mechanisms.adoc#form-auth[Form-based] Quarkus Security mechanisms, which require a combination of username and password credentials.
+Quarkus provides a Jakarta Persistence identity provider, similar to the xref:security-jdbc.adoc[JDBC identity provider]. Jakarta Persistence is suitable for use with the xref:security-basic-authentication.adoc[Basic] and xref:security-authentication-mechanisms.adoc#form-auth[Form-based] Quarkus Security mechanisms, which require a combination of username and password credentials.
 
-The Jakarta Persistence `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure.
+The Jakarta Persistence `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 Jakarta Persistence, see the xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] tutorial.
 
 
 == Jakarta Persistence entity specification
 
-Quarkus security offers a Jakarta Persistence integration to collect usernames, passwords, and roles, and store them into Jakarta Persistence database entities.
+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 properly mapped so that Quarkus can retrieve this information from a database.
+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.
 
 
 * The `@UserDefinition` annotation must be present on a Jakarta Persistence entity, regardless of whether xref:hibernate-orm-panache.adoc[simplified Hibernate ORM with Panache] is used or not.
@@ -63,7 +63,7 @@ public class User extends PanacheEntity {
     /**
      * Adds a new user to the database
      * @param username the username
-     * @param password the unencrypted password (it will be encrypted with bcrypt)
+     * @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>
@@ -84,7 +84,7 @@ The `security-jpa` extension initializes only if a single entity is annotated wi
 <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.
+<5> This method lets you add users while hashing passwords with the proper `bcrypt` hash.
 
 
 == Jakarta Persistence entity as storage of roles
@@ -121,12 +121,12 @@ public class Role extends PanacheEntity {
 
 [NOTE]
 ====
-The example shows how to store and access the roles, but if there's a need to update the existing user or create a new user. There will be a need to annotate `public List<Role> roles` with `@Cascade(CascadeType.ALL)` or select the specific type of `CascadeType`.
+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`.
 ====
 
 == 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.
+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 https://en.wikipedia.org/wiki/Bcrypt[bcrypt] under the
 https://en.wikipedia.org/wiki/Crypt_\(C)[Modular Crypt Format] (MCF).
@@ -138,9 +138,9 @@ As such, we do not need dedicated columns to keep them.
 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.
 ====
 
-To represent passwords stored in the database which were hashed using different hashing algorithms, create a class that implements `io.quarkus.security.jpa.PasswordProvider` as shown in the example below.
+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 which was hashed with the SHA256 hashing algorithm.
+The following snippet shows how to set a custom password provider that represents a password that was hashed with the SHA256 hashing algorithm.
 
 [source,java]
 ----
@@ -191,16 +191,16 @@ public class CustomPasswordProvider implements PasswordProvider {
     public Password getPassword(String passwordInDatabase) {
         byte[] digest = DatatypeConverter.parseHexBinary(passwordInDatabase);
 
-        // Let the security runtime know that this passwordInDatabase is hashed using the SHA256 hashing algorithm
+        // 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);
     }
 }
 ----
 
 [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.
+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.
 ====
 
 [WARNING]
@@ -212,15 +212,15 @@ However, it is possible to store passwords as plain text with the `@Password(Pas
 
 [TIP]
 ====
-The xref:hibernate-orm.adoc#multitenancy[Hibernate Multitenancy] is supported and you can store the user entity in a persistence unit with enabled multitenancy.
+The xref:hibernate-orm.adoc#multitenancy[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, please see the Quarkus xref:security-proactive-authentication.adoc[Proactive authentication] guide.
+For more information about proactive authentication, see the Quarkus xref:security-proactive-authentication.adoc[Proactive authentication] guide.
 ====
 
 include::{generated-dir}/config/quarkus-security-jpa.adoc[opts=optional, leveloffset=+2]
 
 == References
 
-* xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence]
+* xref:security-getting-started-tutorial.adoc[Getting Started with Security by using Basic authentication and Jakarta Persistence]
 * xref:security-identity-providers.adoc[Identity providers]
 * xref:security-overview.adoc[Quarkus Security overview]