Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edit security-jpa.adoc #37844

Merged
merged 1 commit into from
Dec 20, 2023
Merged

Edit security-jpa.adoc #37844

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions docs/src/main/asciidoc/security-jpa.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,18 @@
: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 @@
/**
* 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,10 +84,10 @@
<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"}

Use the following example to store roles inside another Jakarta Persistence entity:

Expand Down Expand Up @@ -121,12 +121,12 @@

[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 @@ -135,12 +135,12 @@

[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.

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 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 @@

[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]