Skip to content

Commit

Permalink
Apply QE feedback to community docs
Browse files Browse the repository at this point in the history
  • Loading branch information
rolfedh committed Jul 9, 2024
1 parent 890d448 commit 8278214
Show file tree
Hide file tree
Showing 15 changed files with 86 additions and 71 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,10 @@ ifndef::no-webauthn-authentication[]
|WebAuthn |xref:security-webauthn.adoc[WebAuthn]
endif::no-webauthn-authentication[]

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

Check warning on line 52 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": 52, "column": 2}}}, "severity": "WARNING"}
endif::no-quarkus-kerberos[]

|====

For more information, see the following <<table>> table.
Expand Down
4 changes: 2 additions & 2 deletions docs/src/main/asciidoc/security-getting-started-tutorial.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,10 @@ To examine the completed example, download the {quickstarts-archive-url}[archive
[source,bash,subs=attributes+]
----
git clone {quickstarts-clone-url}
git clone {quickstarts-clone-url} -b {github-branch}
----
You can find the solution in the `security-jpa-quickstart` link:{quickstarts-tree-url}/security-jpa-quickstart[directory].
You can find the solution in the `security-jpa-quickstart` link:{quickstarts-tree-url}/security-jpa-quickstart/[directory].
====

:sectnums:
Expand Down
6 changes: 3 additions & 3 deletions docs/src/main/asciidoc/security-jwt.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -825,7 +825,7 @@ Please see the xref:security-openid-connect-client-reference.adoc#token-propagat
[[integration-testing-wiremock]]

Check warning on line 825 in docs/src/main/asciidoc/security-jwt.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 'Wiremock'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Wiremock'?", "location": {"path": "docs/src/main/asciidoc/security-jwt.adoc", "range": {"start": {"line": 825, "column": 22}}}, "severity": "WARNING"}
==== Wiremock

If you configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-oidc-bearer-token-authentication.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] `Wiremock` section but only change the `application.properties` to use MP JWT configuration properties instead:
If you configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-oidc-bearer-token-authentication.adoc#bearer-token-integration-testing[OpenID Connect Bearer Token Integration testing] `Wiremock` section but only change the `application.properties` to use MP JWT configuration properties instead:

Check warning on line 828 in docs/src/main/asciidoc/security-jwt.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer. Raw Output: {"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/security-jwt.adoc", "range": {"start": {"line": 828, "column": 1}}}, "severity": "INFO"}

[source, properties]
----
Expand All @@ -837,7 +837,7 @@ mp.jwt.verify.issuer=${keycloak.url}/realms/quarkus
[[integration-testing-keycloak]]
==== Keycloak

If you work with Keycloak and configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-oidc-bearer-token-authentication.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] Keycloak section but only change the `application.properties` to use MP JWT configuration properties instead:
If you work with Keycloak and configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-oidc-bearer-token-authentication.adoc#bearer-token-integration-testing[OpenID Connect Bearer Token Integration testing] Keycloak section but only change the `application.properties` to use MP JWT configuration properties instead:

Check warning on line 840 in docs/src/main/asciidoc/security-jwt.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer. Raw Output: {"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/security-jwt.adoc", "range": {"start": {"line": 840, "column": 1}}}, "severity": "INFO"}

[source, properties]
----
Expand Down Expand Up @@ -865,7 +865,7 @@ mp.jwt.verify.issuer=${client.quarkus.oidc.auth-server-url}
[[integration-testing-public-key]]
==== Local Public Key

You can use the same approach as described in the xref:security-oidc-bearer-token-authentication.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] `Local Public Key` section but only change the `application.properties` to use MP JWT configuration properties instead:
You can use the same approach as described in the xref:security-oidc-bearer-token-authentication.adoc#bearer-token-integration-testing[OpenID Connect Bearer Token Integration testing] `Local Public Key` section but only change the `application.properties` to use MP JWT configuration properties instead:

Check warning on line 868 in docs/src/main/asciidoc/security-jwt.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-jwt.adoc", "range": {"start": {"line": 868, "column": 31}}}, "severity": "INFO"}

Check warning on line 868 in docs/src/main/asciidoc/security-jwt.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Local Public Key'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Local Public Key'.", "location": {"path": "docs/src/main/asciidoc/security-jwt.adoc", "range": {"start": {"line": 868, "column": 169}}}, "severity": "INFO"}

[source, properties]
----
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ To start a Keycloak server, use the following Docker command:
docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8543:8443 -v "$(pwd)"/config/keycloak-keystore.jks:/etc/keycloak-keystore.jks quay.io/keycloak/keycloak:{keycloak.version} start --hostname-strict=false --https-key-store-file=/etc/keycloak-keystore.jks
----
where `keycloak.version` must be `23.0.0` or later and the `keycloak-keystore.jks` can be found in https://github.com/quarkusio/quarkus-quickstarts/blob/main/security-keycloak-authorization-quickstart/config/keycloak-keystore.jks[quarkus-quickstarts/security-keycloak-authorization-quickstart/config].
where `keycloak.version` must be `24.0.0` or later and the `keycloak-keystore.jks` can be found in https://github.com/quarkusio/quarkus-quickstarts/blob/main/security-keycloak-authorization-quickstart/config/keycloak-keystore.jks[quarkus-quickstarts/security-keycloak-authorization-quickstart/config].
Try to access your Keycloak server at https://localhost:8543[localhost:8543].
Expand Down
2 changes: 1 addition & 1 deletion docs/src/main/asciidoc/security-oidc-auth0-tutorial.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -929,7 +929,7 @@ Press `r` and notice this test failing with `403` which is expected because the

image::auth0-test-failure-403.png[Auth0 test failure 403]

Before fixing the test, let's review the options available for testing Quarkus endpoints secured by OIDC. These options might vary, depending on which flow your application supports and how you prefer to test. Endpoints which use OIDC authorization code flow can be tested using xref:security-oidc-code-flow-authentication#integration-testing[one of these options] and endpoints which use Bearer token authentication can be tested using xref:security-oidc-bearer-token-authentication#integration-testing[one of these options].
Before fixing the test, let's review the options available for testing Quarkus endpoints secured by OIDC. These options might vary, depending on which flow your application supports and how you prefer to test. Endpoints which use OIDC authorization code flow can be tested using xref:security-oidc-code-flow-authentication#code-flow-integration-testing[one of these options] and endpoints which use Bearer token authentication can be tested using xref:security-oidc-bearer-token-authentication#integration-testing[one of these options].

As you can see, testing of the endpoints secured with Auth0 can be done with the help of `Wiremock`, or `@TestSecurity` annotation. Experiment with writing such tests on your own and reach out if you encounter any problems.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ Where:

* `%prod.quarkus.oidc.auth-server-url` sets the base URL of the OpenID Connect (OIDC) server.
The `%prod.` profile prefix ensures that `Dev Services for Keycloak` launches a container when you run the application in development (dev) mode.
For more information, see the <<keycloak-dev-mode>> section.
For more information, see the <<bearer-token-tutorial-keycloak-dev-mode>> section.

* `quarkus.oidc.client-id` sets a client id that identifies the application.
* `quarkus.oidc.credentials.secret` sets the client secret, which is used by the `client_secret_basic` authentication method.
Expand All @@ -206,7 +206,7 @@ You do not need to do this if you have already built a link:{quickstarts-tree-ur
[NOTE]
====
Do not start the Keycloak server when you run the application in dev mode; `Dev Services for Keycloak` will start a container.
For more information, see the <<keycloak-dev-mode>> section.
For more information, see the <<bearer-token-tutorial-keycloak-dev-mode>> section.
====
+
. To start a Keycloak server, you can use Docker to run the following command:
Expand All @@ -217,7 +217,7 @@ For more information, see the <<keycloak-dev-mode>> section.
docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:{keycloak.version} start-dev
----
====
* Where the `keycloak.version` is set to version `23.0.0` or later.
* Where the `keycloak.version` is set to version `24.0.0` or later.
. You can access your Keycloak server at http://localhost:8180[localhost:8180].
. To access the Keycloak Administration console, log in as the `admin` user by using the following login credentials:

Check warning on line 222 in docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.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-oidc-bearer-token-authentication-tutorial.adoc", "range": {"start": {"line": 222, "column": 41}}}, "severity": "INFO"}

Expand All @@ -238,7 +238,7 @@ endif::no-quarkus-keycloak-admin-client[]



[[keycloak-dev-mode]]
[[bearer-token-tutorial-keycloak-dev-mode]]
== Run the application in dev mode

. To run the application in dev mode, run the following commands:
Expand Down Expand Up @@ -301,7 +301,7 @@ include::{includes}/devtools/build-native.adoc[]

== Test the application

For information about testing your application in dev mode, see the preceding <<keycloak-dev-mode>> section.
For information about testing your application in dev mode, see the preceding <<bearer-token-tutorial-keycloak-dev-mode>> section.

You can test the application launched in JVM or native modes with `curl`.

Expand Down Expand Up @@ -352,7 +352,7 @@ export access_token=$(\
)
----

For information about writing integration tests that depend on `Dev Services for Keycloak`, see the xref:security-oidc-bearer-token-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] section of the "OpenID Connect (OIDC) Bearer token authentication" guide.
For information about writing integration tests that depend on `Dev Services for Keycloak`, see the xref:security-oidc-bearer-token-authentication.adoc#bearer-token-integration-testing-keycloak-devservices[Dev Services for Keycloak] section of the "OpenID Connect (OIDC) Bearer token authentication" guide.

//:sectnums!:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -88,20 +88,20 @@ Injection of `JsonWebToken` is supported in `@ApplicationScoped`, `@Singleton`,
However, the use of `@RequestScoped` is required if the individual claims are injected as simple types.
For more information, see the xref:security-jwt.adoc#supported-injection-scopes[Supported injection scopes] section of the Quarkus "Using JWT RBAC" guide.

[[user-info]]
[[bearer-token-user-info]]
=== `UserInfo`

If you must request a UserInfo JSON object from the OIDC `UserInfo` endpoint, set `quarkus.oidc.authentication.user-info-required=true`.
A request is sent to the OIDC provider `UserInfo` endpoint, and an `io.quarkus.oidc.UserInfo` (a simple `javax.json.JsonObject` wrapper) object is created.
`io.quarkus.oidc.UserInfo` can be injected or accessed as a `SecurityIdentity` `userinfo` attribute.

`quarkus.oidc.authentication.user-info-required` is automatically enabled if one of these conditions is met:
`quarkus.oidc.authentication.user-info-required` is automatically enabled if one of these conditions is met:

- if `quarkus.oidc.roles.source` is set to `userinfo` or `quarkus.oidc.token.verify-access-token-with-user-info` is set to `true` or `quarkus.oidc.authentication.id-token-required` is set to `false`, the current OIDC tenant must support a UserInfo endpoint in these cases.

- if `io.quarkus.oidc.UserInfo` injection point is detected but only if the current OIDC tenant supports a UserInfo endpoint.

[[config-metadata]]
[[bearer-token-config-metadata]]
=== Configuration metadata

The current tenant's discovered link:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata[OpenID Connect Configuration Metadata] is represented by `io.quarkus.oidc.OidcConfigurationMetadata` and can be injected or accessed as a `SecurityIdentity` `configuration-metadata` attribute.
Expand Down Expand Up @@ -207,7 +207,7 @@ public class ProtectedResource {

For more information about the `io.quarkus.security.PermissionsAllowed` annotation, see the xref:security-authorize-web-endpoints-reference.adoc#permission-annotation[Permission annotation] section of the "Authorization of web endpoints" guide.

[[token-verification-introspection]]
[[bearer-token-token-verification-introspection]]
=== Token verification and introspection

If the token is a JWT token, then, by default, it is verified with a `JsonWebKey` (JWK) key from a local `JsonWebKeySet`, retrieved from the OIDC provider's JWK endpoint.
Expand Down Expand Up @@ -256,7 +256,7 @@ A disadvantage is that a remote OIDC metadata discovery call is required to disc
The `io.quarkus.oidc.TokenIntrospection`, a simple `jakarta.json.JsonObject` wrapper object, will be created.
It can be injected or accessed as a `SecurityIdentity` `introspection` attribute, providing either the JWT or opaque token has been successfully introspected.

[[token-introspection-userinfo-cache]]
[[bearer-token-token-introspection-userinfo-cache]]
=== Token introspection and `UserInfo` cache

All opaque access tokens must be remotely introspected.
Expand Down Expand Up @@ -305,7 +305,7 @@ Additionally, the cleanup timer, if activated, periodically checks for expired e

You can experiment with the default cache implementation or register a custom one.

[[jwt-claim-verification]]
[[bearer-token-jwt-claim-verification]]
=== JSON Web Token claim verification

After the bearer JWT token's signature has been verified and its `expires at` (`exp`) claim has been checked, the `iss` (`issuer`) claim value is verified next.
Expand Down Expand Up @@ -542,7 +542,7 @@ public class BearerGlobalTokenChainValidator implements TokenCertificateValidato
If introspection of the Bearer token is necessary, then `OidcProviderClient` must authenticate to the OIDC provider.
For more information about supported authentication options, see the xref:security-oidc-code-flow-authentication.adoc#oidc-provider-client-authentication[OIDC provider client authentication] section in the Quarkus "OpenID Connect authorization code flow mechanism for protecting web applications" guide.

[[integration-testing]]
[[bearer-token-integration-testing]]
=== Testing

[NOTE]
Expand Down Expand Up @@ -574,7 +574,8 @@ testImplementation("io.rest-assured:rest-assured")
testImplementation("io.quarkus:quarkus-junit5")
----

[[integration-testing-wiremock]]
ifndef::no-deprecated-test-resource[]
[[bearer-token-integration-testing-wiremock]]
==== WireMock

Add the following dependencies to your test project:
Expand Down Expand Up @@ -694,6 +695,7 @@ public class CustomOidcWireMockStubTest {
}
}
----
endif::no-deprecated-test-resource[]

[[integration-testing-oidc-test-client]]
=== `OidcTestClient`
Expand All @@ -709,7 +711,8 @@ For example, you have the following configuration:
%test.quarkus.oidc.credentials.secret=secret
----

To start, add the same dependency, `quarkus-test-oidc-server`, as described in the <<integration-testing-wiremock>> section.
ifndef::no-deprecated-test-resource[]
To start, add the same dependency, `quarkus-test-oidc-server`, as described in the <<bearer-token-integration-testing-wiremock>> section.

Next, write the test code as follows:

Expand Down Expand Up @@ -760,8 +763,9 @@ This test code acquires a token by using a `password` grant from the test `Auth0
For a test like this to work, the test `Auth0` application must have the `password` grant enabled.
This example code also shows how to pass additional parameters.
For `Auth0`, these are the `audience` and `scope` parameters.
endif::no-deprecated-test-resource[]

[[integration-testing-keycloak-devservices]]
[[bearer-token-integration-testing-keycloak-devservices]]
==== Dev Services for Keycloak

The preferred approach for integration testing against Keycloak is xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak].
Expand Down Expand Up @@ -856,14 +860,14 @@ public class NativeBearerTokenAuthenticationIT extends BearerTokenAuthentication
For more information about initializing and configuring Dev Services for Keycloak, see the xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] guide.

ifndef::no-deprecated-test-resource[]
[[integration-testing-keycloak]]
[[bearer-token-integration-testing-keycloak]]
==== `KeycloakTestResourceLifecycleManager`

You can also use `KeycloakTestResourceLifecycleManager` for integration testing with Keycloak.

[IMPORTANT]
====
Use <<integration-testing-keycloak-devservices,Dev Services for Keycloak>> instead of `KeycloakTestResourceLifecycleManager` for integration testing with Keycloak, unless you have specific requirements for using `KeycloakTestResourceLifecycleManager`.
Use <<bearer-token-integration-testing-keycloak-devservices,Dev Services for Keycloak>> instead of `KeycloakTestResourceLifecycleManager` for integration testing with Keycloak, unless you have specific requirements for using `KeycloakTestResourceLifecycleManager`.
====

First, add the following dependency:
Expand Down Expand Up @@ -973,13 +977,15 @@ quarkus.oidc.public-key=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlivFI8qB4D0y
smallrye.jwt.sign.key.location=/privateKey.pem
----

To generate JWT tokens, copy `privateKey.pem` from the `integration-tests/oidc-tenancy` in the `main` Quarkus repository and use a test code similar to the one in the preceding <<integration-testing-wiremock>> section.
ifndef::no-deprecated-test-resource[]
To generate JWT tokens, copy `privateKey.pem` from the `integration-tests/oidc-tenancy` in the `main` Quarkus repository and use a test code similar to the one in the preceding <<bearer-token-integration-testing-wiremock>> section.
You can use your own test keys, if preferred.

This approach provides limited coverage compared to the WireMock approach.
For example, the remote communication code is not covered.
endif::no-deprecated-test-resource[]

[[integration-testing-security-annotation]]
[[bearer-token-integration-testing-security-annotation]]
==== TestSecurity annotation

You can use `@TestSecurity` and `@OidcSecurity` annotations to test the `service` application endpoint code, which depends on either one, or all three, of the following injections:
Expand Down Expand Up @@ -1339,11 +1345,11 @@ xref:security-openid-connect-multitenancy.adoc#tenant-config-resolver[Dynamic te
Authentication that requires a dynamic tenant will fail.
====

[[oidc-request-filters]]
[[bearer-token-oidc-request-filters]]
== OIDC request filters

You can filter OIDC requests made by Quarkus to the OIDC provider by registering one or more `OidcRequestFilter` implementations, which can update or add new request headers, and log requests.
For more information, see xref:security-oidc-code-flow-authentication#oidc-request-filters[OIDC request filters].
For more information, see xref:security-oidc-code-flow-authentication#code-flow-oidc-request-filters[OIDC request filters].

== References

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ To start a Keycloak server, use Docker and run the following command:
docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:{keycloak.version} start-dev
----

where `keycloak.version` is set to `23.0.0` or later.
where `keycloak.version` is set to `24.0.0` or later.

You can access your Keycloak Server at http://localhost:8180[localhost:8180].

Expand Down Expand Up @@ -266,11 +266,11 @@ After clicking the `Login` button, you are redirected back to the application, a

The session for this demo is valid for a short period of time and, on every page refresh, you will be asked to re-authenticate.
For information about how to increase the session timeouts, see the Keycloak https://www.keycloak.org/docs/latest/server_admin/#_timeouts[session timeout] documentation.
For example, you can access the Keycloak Admin console directly from the dev UI by clicking the `Keycloak Admin` link if you use xref:security-oidc-code-flow-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] in dev mode:
For example, you can access the Keycloak Admin console directly from the dev UI by clicking the `Keycloak Admin` link if you use xref:security-oidc-code-flow-authentication.adoc#code-flow-integration-testing-keycloak-devservices[Dev Services for Keycloak] in dev mode:

image::dev-ui-oidc-keycloak-card.png[alt=Dev UI OpenID Connect Card,role="center"]

For more information about writing the integration tests that depend on `Dev Services for Keycloak`, see the xref:security-oidc-code-flow-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] section.
For more information about writing the integration tests that depend on `Dev Services for Keycloak`, see the xref:security-oidc-code-flow-authentication.adoc#code-flow-integration-testing-keycloak-devservices[Dev Services for Keycloak] section.

:sectnums!:

Expand Down
Loading

0 comments on commit 8278214

Please sign in to comment.