Skip to content

Commit

Permalink
Edit security-jpa.adoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@rolfedh
rolfedh committed Dec 19, 2023
1 parent 4d07a91 commit a57513f
Showing 1 changed file with 16 additions and 16 deletions.
32 changes: 16 additions & 16 deletions docs/src/main/asciidoc/security-jpa.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Check warning on line 21 in docs/src/main/asciidoc/security-jpa.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Jakarta Persistence entity specification'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Jakarta Persistence entity specification'.", "location": {"path": "docs/src/main/asciidoc/security-jpa.adoc", "range": {"start": {"line": 21, "column": 4}}}, "severity": "INFO"}

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.

Check warning on line 25 in docs/src/main/asciidoc/security-jpa.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'needs to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'needs to'.", "location": {"path": "docs/src/main/asciidoc/security-jpa.adoc", "range": {"start": {"line": 25, "column": 92}}}, "severity": "INFO"}


* 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.
Expand Down Expand Up @@ -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>
Expand All @@ -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

Check warning on line 90 in docs/src/main/asciidoc/security-jpa.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/security-jpa.adoc", "range": {"start": {"line": 90, "column": 31}}}, "severity": "INFO"}
Expand Down Expand Up @@ -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).
Expand All @@ -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.

Check warning on line 138 in docs/src/main/asciidoc/security-jpa.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/security-jpa.adoc", "range": {"start": {"line": 138, "column": 56}}}, "severity": "INFO"}
====

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]
----
Expand Down Expand Up @@ -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]
Expand All @@ -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.

Check warning on line 215 in docs/src/main/asciidoc/security-jpa.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'multitenancy'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'multitenancy'?", "location": {"path": "docs/src/main/asciidoc/security-jpa.adoc", "range": {"start": {"line": 215, "column": 29}}}, "severity": "WARNING"}
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]

0 comments on commit a57513f

Please sign in to comment.