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

[3.8] Conditionalize security content #40887

Merged
merged 1 commit into from
Jun 4, 2024
Merged

[3.8] Conditionalize security content #40887

Show file tree
Hide file tree
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
10 changes: 10 additions & 0 deletions docs/src/main/asciidoc/datasource.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,9 @@

. Add the correct reactive extension for the database of your choice.

ifndef::no-quarkus-reactive-db2-client[]
* `quarkus-reactive-db2-client`
endif::no-quarkus-reactive-db2-client[]
* `quarkus-reactive-mssql-client`
* `quarkus-reactive-mysql-client`
* `quarkus-reactive-oracle-client`
Expand Down Expand Up @@ -300,7 +302,9 @@

. Add the corresponding extension to your application:
+
ifndef::no-quarkus-reactive-db2-client[]
* DB2: `quarkus-reactive-db2-client`
endif::no-quarkus-reactive-db2-client[]
* MariaDB/MySQL: `quarkus-reactive-mysql-client`
* Microsoft SQL Server: `quarkus-reactive-mssql-client`
* Oracle: `quarkus-reactive-oracle-client`
Expand Down Expand Up @@ -589,9 +593,10 @@
* Derby cannot be embedded into the application in native mode.
However, the Quarkus Derby extension allows native compilation of the Derby JDBC *client*, supporting *remote* connections.

* Embedding H2 within your native image is not recommended.

Check warning on line 596 in docs/src/main/asciidoc/datasource.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

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

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/datasource.adoc", "range": {"start": {"line": 596, "column": 59}}}, "severity": "INFO"}
Consider using an alternative approach, for example, using a remote connection to a separate database instead.

ifndef::no-deprecated-test-resource[]
==== Run an integration test

. Add a dependency on the artifacts providing the additional tools that are under the following Maven coordinates:
Expand Down Expand Up @@ -628,6 +633,7 @@
quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:test
----
endif::no-deprecated-test-resource[]

[[datasource-reference]]
== References
Expand Down Expand Up @@ -820,9 +826,11 @@
|`reactive-pg-client`
|`io.vertx.pgclient.spi.PgDriver`

ifndef::no-quarkus-reactive-db2-client[]
|`db2`
|`reactive-db2-client`
|`io.vertx.db2client.spi.DB2Driver`
endif::no-quarkus-reactive-db2-client[]
|===

[TIP]
Expand All @@ -836,9 +844,11 @@

include::{generated-dir}/config/quarkus-reactive-datasource.adoc[opts=optional, leveloffset=+1]

ifndef::no-quarkus-reactive-db2-client[]
==== Reactive DB2 configuration

include::{generated-dir}/config/quarkus-reactive-db2-client.adoc[opts=optional, leveloffset=+1]
endif::no-quarkus-reactive-db2-client[]

==== Reactive MariaDB/MySQL specific configuration

Expand Down
130 changes: 105 additions & 25 deletions docs/src/main/asciidoc/security-authentication-mechanisms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,20 @@

|Username and password |xref:security-basic-authentication.adoc[Basic], <<form-auth>>

|Bearer access token |xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication], xref:security-jwt.adoc[JWT], xref:security-oauth2.adoc[OAuth2]
|Bearer access token |xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication], xref:security-jwt.adoc[JWT]
ifndef::no-quarkus-elytron-security-oauth2[]
, xref:security-oauth2.adoc[OAuth2]
endif::no-quarkus-elytron-security-oauth2[]

|Single sign-on (SSO) |xref:security-oidc-code-flow-authentication.adoc[OIDC Code Flow], <<form-auth>>

|Client certificate |<<mutual-tls>>

ifndef::no-webauthn-authentication[]
|WebAuthn |xref:security-webauthn.adoc[WebAuthn]
endif::no-webauthn-authentication[]

|Kerberos ticket |link:https://quarkiverse.github.io/quarkiverse-docs/quarkus-kerberos/dev/index.html[Kerberos]

Check warning on line 51 in docs/src/main/asciidoc/security-authentication-mechanisms.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 'Kerberos'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Kerberos'?", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 51, "column": 2}}}, "severity": "WARNING"}
|====

For more information, see the following <<table>> table.
Expand Down Expand Up @@ -275,17 +280,23 @@

Quarkus Security also supports the following authentication mechanisms through extensions:

ifndef::no-webauthn-authentication[]
* <<webauthn-authentication>>
endif::no-webauthn-authentication[]
* <<openid-connect-authentication>>
* <<smallrye-jwt-authentication>>
ifndef::no-quarkus-elytron-security-oauth2[]
* <<oauth2-authentication>>
endif::no-quarkus-elytron-security-oauth2[]

ifndef::no-webauthn-authentication[]
[[webauthn-authentication]]
=== WebAuthn authentication

https://webauthn.guide/[WebAuthn] is an authentication mechanism that replaces passwords.
When you write a service for registering new users, or logging them in, instead of asking for a password, you can use WebAuthn, which replaces the password.
For more information, see the xref:security-webauthn.adoc[Secure a Quarkus application by using the WebAuthn authentication mechanism] guide.
endif::no-webauthn-authentication[]

[[openid-connect-authentication]]
=== OpenID Connect authentication
Expand Down Expand Up @@ -320,7 +331,9 @@
|Multiple tenants that can support the Bearer token authentication or Authorization Code Flow mechanisms|xref:security-openid-connect-multitenancy.adoc[Using OpenID Connect (OIDC) multi-tenancy]
|Securing Quarkus with commonly used OpenID Connect providers|xref:security-openid-connect-providers.adoc[Configuring well-known OpenID Connect providers]
|Using Keycloak to centralize authorization |xref:security-keycloak-authorization.adoc[Using OpenID Connect (OIDC) and Keycloak to centralize authorization]
ifndef::no-quarkus-keycloak-admin-client[]
|Configuring Keycloak programmatically |xref:security-keycloak-admin-client.adoc[Using the Keycloak admin client]
endif::no-quarkus-keycloak-admin-client[]
|====

[NOTE]
Expand All @@ -346,15 +359,18 @@

[IMPORTANT]
====
In this scenario, you do not need to protect your Quarkus endpoint by using the Quarkus OpenID Connect adapter.

Check warning on line 362 in docs/src/main/asciidoc/security-authentication-mechanisms.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 'need to'.

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

ifndef::no-quarkus-oidc-token-propagation[]
The `quarkus-oidc-token-propagation` extension requires the `quarkus-oidc` extension.
It provides Jakarta REST `TokenCredentialRequestFilter`, which sets the OpenID Connect Bearer token or Authorization Code Flow access token as the `Bearer` scheme value of the HTTP `Authorization` header.
This filter can be registered with MicroProfile REST client implementations injected into the current Quarkus endpoint, which must be protected by using the Quarkus OIDC adapter.
This filter can propagate the access token to the downstream services.

For more information, see the xref:security-openid-connect-client.adoc[OpenID Connect client and token propagation quickstart] and xref:security-openid-connect-client-reference.adoc[OpenID Connect (OIDC) and OAuth2 client and filters reference] guides.
endif::no-quarkus-oidc-token-propagation[]


[[smallrye-jwt-authentication]]
=== SmallRye JWT authentication
Expand All @@ -367,13 +383,15 @@

For more information, see the xref:security-jwt.adoc[Using JWT RBAC] guide.

ifndef::no-quarkus-elytron-security-oauth2[]
[[oauth2-authentication]]
=== OAuth2 authentication

`quarkus-elytron-security-oauth2` provides an alternative to the Quarkus `quarkus-oidc` Bearer token authentication mechanism extension.
`quarkus-elytron-security-oauth2` is based on `Elytron` and is primarily intended for introspecting opaque tokens remotely.

For more information, see the Quarkus xref:security-oauth2.adoc[Using OAuth2] guide.
endif::no-quarkus-elytron-security-oauth2[]

[[oidc-jwt-oauth2-comparison]]
== Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms
Expand All @@ -385,16 +403,23 @@
* `quarkus-oidc` requires an OpenID Connect provider such as Keycloak, which can verify the bearer tokens or authenticate the end users with the Authorization Code flow.
In both cases, `quarkus-oidc` requires a connection to the specified OpenID Connect provider.

* If the user authentication requires Authorization Code flow, or you need to support multiple tenants, use `quarkus-oidc`.

Check warning on line 406 in docs/src/main/asciidoc/security-authentication-mechanisms.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 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/security-authentication-mechanisms.adoc", "range": {"start": {"line": 406, "column": 71}}}, "severity": "INFO"}
`quarkus-oidc` can also request user information by using both Authorization Code Flow and Bearer access tokens.

* If your bearer tokens must be verified, use `quarkus-oidc`, `quarkus-smallrye-jwt`, or `quarkus-elytron-security-oauth2`.
ifndef::no-quarkus-elytron-security-oauth2[]
* If your bearer tokens must be verified, use `quarkus-oidc`, `quarkus-elytron-security-oauth2`, or `quarkus-smallrye-jwt`.
endif::no-quarkus-elytron-security-oauth2[]
ifdef::no-quarkus-elytron-security-oauth2[]
* If your bearer tokens must be verified, use `quarkus-oidc` or `quarkus-smallrye-jwt`.
endif::no-quarkus-elytron-security-oauth2[]

* If your bearer tokens are in a JSON web token (JWT) format, you can use any extensions in the preceding list.
Both `quarkus-oidc` and `quarkus-smallrye-jwt` support refreshing the `JsonWebKey` (JWK) set when the OpenID Connect provider rotates the keys.
Therefore, if remote token introspection must be avoided or is unsupported by the providers, use `quarkus-oidc` or `quarkus-smallrye-jwt` to verify JWT tokens.

* To introspect the JWT tokens remotely, you can use either `quarkus-oidc` or `quarkus-elytron-security-oauth2` because they support verifying the opaque or binary tokens by using remote introspection.
* To introspect the JWT tokens remotely, you can use `quarkus-oidc`
ifndef::no-quarkus-elytron-security-oauth2[or `quarkus-elytron-security-oauth2`]
for verifying the opaque or binary tokens by using remote introspection.
`quarkus-smallrye-jwt` does not support the remote introspection of both opaque or JWT tokens but instead relies on the locally available keys that are usually retrieved from the OpenID Connect provider.

* `quarkus-oidc` and `quarkus-smallrye-jwt` support the JWT and opaque token injection into the endpoint code.
Expand All @@ -405,9 +430,10 @@
`quarkus-oidc` uses only the JWK-formatted keys that are part of a JWK set, whereas `quarkus-smallrye-jwt` supports PEM keys.

* `quarkus-smallrye-jwt` handles locally signed, inner-signed-and-encrypted, and encrypted tokens.
In contrast, although `quarkus-oidc` and `quarkus-elytron-security-oauth2` can also verify such tokens, they treat them as opaque tokens and verify them through remote introspection.
ifndef::no-quarkus-elytron-security-oauth2[In contrast, although `quarkus-oidc` and `quarkus-elytron-security-oauth2` can also verify such tokens, they treat them as opaque tokens and verify them through remote introspection.]
ifdef::no-quarkus-elytron-security-oauth2[In contrast, although `quarkus-oidc` can also verify such tokens, it treats them as opaque tokens and verifies them through remote introspection.]

* If you need a lightweight library for the remote introspection of opaque or JWT tokens, use `quarkus-elytron-security-oauth2`.
ifndef::no-quarkus-elytron-security-oauth2[* If you need a lightweight library for the remote introspection of opaque or JWT tokens, use `quarkus-elytron-security-oauth2`.]

[NOTE]
====
Expand All @@ -422,26 +448,80 @@
[[table]]
.Token authentication mechanism comparison
|===
^|Feature required 3+^| Authentication mechanism

^| ^s|`quarkus-oidc` ^s|`quarkus-smallrye-jwt` ^s| `quarkus-elytron-security-oauth2`

s|Bearer JWT verification ^|Local verification or introspection ^|Local verification ^|Introspection

s|Bearer opaque token verification ^|Introspection ^|No ^|Introspection
s|Refreshing `JsonWebKey` set to verify JWT tokens ^|Yes ^|Yes ^|No
s|Represent token as `Principal` ^|Yes ^|Yes ^|Yes
s|Inject JWT as MP JWT ^|Yes ^|Yes ^|No

s|Authorization code flow ^| Yes ^|No ^|No
s|Multi-tenancy ^| Yes ^|No ^|No
s|User information support ^| Yes ^|No ^|No
s|PEM key format support ^|No ^|Yes ^|No

s|SecretKey support ^|No ^|In JSON Web Key (JWK) format ^|No
s|Inner-signed and encrypted or encrypted tokens ^|Introspection ^|Local verification ^|Introspection
s|Custom token verification ^|No ^|With injected JWT parser ^|No
s|JWT as a cookie support ^|No ^|Yes ^|Yes
// Display four columns
ifndef::no-quarkus-elytron-security-oauth2[ ^|Feature required 3+^| Authentication mechanism]
// Display three columns and hide the quarkus-elytron-security-oauth2 column.
ifdef::no-quarkus-elytron-security-oauth2[ ^|Feature required 2+^| Authentication mechanism]

^|
^s|`quarkus-oidc`
^s|`quarkus-smallrye-jwt`
ifndef::no-quarkus-elytron-security-oauth2[ ^s|`quarkus-elytron-security-oauth2`]

s|Bearer JWT verification
^|Local verification or introspection
^|Local verification
ifndef::no-quarkus-elytron-security-oauth2[ ^|Introspection]

s|Bearer opaque token verification
^|Introspection
^|No
ifndef::no-quarkus-elytron-security-oauth2[ ^|Introspection]

s|Refreshing `JsonWebKey` set to verify JWT tokens
^|Yes
^|Yes
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|Represent token as `Principal`

Check warning on line 476 in docs/src/main/asciidoc/security-authentication-mechanisms.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-authentication-mechanisms.adoc", "range": {"start": {"line": 476, "column": 19}}}, "severity": "INFO"}
^|Yes
^|Yes
ifndef::no-quarkus-elytron-security-oauth2[ ^|Yes]

s|Inject JWT as MP JWT
^|Yes
^|Yes
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|Authorization code flow
^| Yes
^|No
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|Multi-tenancy
^| Yes
^|No
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|User information support
^| Yes
^|No
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|PEM key format support
^|No
^|Yes
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|SecretKey support
^|No
^|In JSON Web Key (JWK) format
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|Inner-signed and encrypted or encrypted tokens
^|Introspection
^|Local verification
ifndef::no-quarkus-elytron-security-oauth2[ ^|Introspection]

s|Custom token verification
^|No
^|With injected JWT parser
ifndef::no-quarkus-elytron-security-oauth2[ ^|No]

s|JWT as a cookie support
^|No
^|Yes
ifndef::no-quarkus-elytron-security-oauth2[ ^|Yes]
|===


Expand Down
7 changes: 6 additions & 1 deletion docs/src/main/asciidoc/security-basic-authentication-howto.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,12 @@ Enable xref:security-basic-authentication.adoc[Basic authentication] for your Qu
* You have installed at least one extension that provides an `IdentityProvider` based on username and password.
For example:

** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extensions (`security-jpa` or `security-jpa-reactive`)]
ifndef::no-quarkus-security-jpa-reactive[]
** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extensions (`quarkus-security-jpa` or `quarkus-security-jpa-reactive`)]
endif::no-quarkus-security-jpa-reactive[]
ifdef::no-quarkus-security-jpa-reactive[]
** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extension (`quarkus-security-jpa`)]
endif::no-quarkus-security-jpa-reactive[]
** xref:security-properties.adoc[Elytron security properties file extension `(quarkus-elytron-security-properties-file)`]
** xref:security-jdbc.adoc[Elytron security JDBC extension `(quarkus-elytron-security-jdbc)`]

Expand Down
Loading
Loading