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.

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

Clarify how Keycloak Dev Service can be used to test Keycloak authorization #37977

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
21 changes: 20 additions & 1 deletion docs/src/main/asciidoc/security-keycloak-authorization.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@

include::{includes}/devtools/dev.adoc[]

xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] will launch a Keycloak container and import a `quarkus-realm.json`.
xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] will launch a Keycloak container and import the link:{quickstarts-tree-url}/security-keycloak-authorization-quickstart/config/quarkus-realm.json[realm configuration file].

Check warning on line 236 in docs/src/main/asciidoc/security-keycloak-authorization.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsWarnings] Consider using 'start' or 'open' rather than 'launch' unless updating existing content that uses the term. Raw Output: {"message": "[Quarkus.TermsWarnings] Consider using 'start' or 'open' rather than 'launch' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/security-keycloak-authorization.adoc", "range": {"start": {"line": 236, "column": 64}}}, "severity": "WARNING"}

Open a xref:dev-ui.adoc[Dev UI] available at http://localhost:8080/q/dev-ui[/q/dev-ui] and click on a `Provider: Keycloak` link in an `OpenID Connect` `Dev UI` card.

Expand All @@ -246,9 +246,27 @@
** accessing `/api/admin` will return `200`
** accessing `/api/users/me` will return `200`

If you have started xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] without importing a realm file such as link:{quickstarts-tree-url}/security-keycloak-authorization-quickstart/config/quarkus-realm.json[quarkus-realm.json] which is already configured to support Keycloak Authorization then a default `quarkus` realm without Keycloak authorization policies will be created. In this case you must select the `Keycloak Admin` link in the `OpenId Connect` Dev UI card and configure link:https://www.keycloak.org/docs/latest/authorization_services/index.html[Keycloak Authorization] in the default `quarkus` realm.

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

The `Keycloak Admin` link is easy to find in Dev UI:

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

When logging in the Keycloak admin console, the username is `admin` and the password is `admin`.

If your application configures Keycloak authorization with link:https://www.keycloak.org/docs/latest/authorization_services/index.html#_policy_js[JavaScript policies] that are deployed to Keycloak in a jar file then you can configure `Dev Services for Keycloak` to copy this jar to the Keycloak container, for example:

Check warning on line 257 in docs/src/main/asciidoc/security-keycloak-authorization.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.CaseSensitiveTerms] Use 'JAR file' rather than 'jar file'. Raw Output: {"message": "[Quarkus.CaseSensitiveTerms] Use 'JAR file' rather than 'jar file'.", "location": {"path": "docs/src/main/asciidoc/security-keycloak-authorization.adoc", "range": {"start": {"line": 257, "column": 187}}}, "severity": "INFO"}

[source,properties]
----
quarkus.keycloak.devservices.resource-aliases.policies=/policies.jar <1>
quarkus.keycloak.devservices.resource-mappings.policies=/opt/keycloak/providers/policies.jar <2>
----
<1> `policies` alias is created for the `/policies.jar` classpath resource. Policy jars can also be located in the file system.
<2> The policies jar is mapped to the `/opt/keycloak/providers/policies.jar` container location.

== Running the Application in JVM mode

When you're done playing with the `dev` mode" you can run it as a standard Java application.

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

First compile it:

Expand Down Expand Up @@ -277,7 +295,8 @@
----
./target/security-keycloak-authorization-quickstart-runner
----

Check warning on line 298 in docs/src/main/asciidoc/security-keycloak-authorization.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Testing the Application'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Testing the Application'.", "location": {"path": "docs/src/main/asciidoc/security-keycloak-authorization.adoc", "range": {"start": {"line": 298, "column": 1}}}, "severity": "INFO"}
[[testing]]
== Testing the Application

See <<keycloak-dev-mode,Running the Application in Dev mode>> section above about testing your application in a dev mode.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,12 @@ Please see xref:security-openid-connect-client-reference.adoc#token-propagation[
[[integration-testing]]
=== Testing

[NOTE]
====
If you have to test Quarkus OIDC service endpoints that require xref:security-keycloak-authorization.adoc[Keycloak Authorization] then you must follow the xref:security-keycloak-authorization.adoc#testing[Test Keycloak Authorization] section.
====


Start by adding the following dependencies to your test project:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
Expand Down
10 changes: 10 additions & 0 deletions docs/src/main/asciidoc/security-openid-connect-dev-services.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,17 @@

Sign in to Keycloak as `admin:admin` in order to further customize the realm properties, create or import a new realm, export the realm.

You can also copy classpath and file system resources to the container. For example, if your application configures Keycloak authorization with link:https://www.keycloak.org/docs/latest/authorization_services/index.html#_policy_js[JavaScript policies] that are deployed to Keycloak in a jar file then you can configure `Dev Services for Keycloak` to copy this jar to the Keycloak container as follows:

Check warning on line 275 in docs/src/main/asciidoc/security-openid-connect-dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.CaseSensitiveTerms] Use 'JAR file' rather than 'jar file'. Raw Output: {"message": "[Quarkus.CaseSensitiveTerms] Use 'JAR file' rather than 'jar file'.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-dev-services.adoc", "range": {"start": {"line": 275, "column": 288}}}, "severity": "INFO"}

Check warning on line 275 in docs/src/main/asciidoc/security-openid-connect-dev-services.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-openid-connect-dev-services.adoc", "range": {"start": {"line": 275, "column": 391}}}, "severity": "INFO"}

[source,properties]
----
quarkus.keycloak.devservices.resource-aliases.policies=/policies.jar <1>
quarkus.keycloak.devservices.resource-mappings.policies=/opt/keycloak/providers/policies.jar <2>
----
<1> `policies` alias is created for the classpath `/policies.jar` resource. Policy jars can also be located in the file system.
<2> The policies jar is mapped to the `/opt/keycloak/providers/policies.jar` container location.

== Disable Dev Services for Keycloak

Check warning on line 285 in docs/src/main/asciidoc/security-openid-connect-dev-services.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Disable Dev Services for Keycloak'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Disable Dev Services for Keycloak'.", "location": {"path": "docs/src/main/asciidoc/security-openid-connect-dev-services.adoc", "range": {"start": {"line": 285, "column": 4}}}, "severity": "INFO"}

`Dev Services For Keycloak` will not be activated if either `quarkus.oidc.auth-server-url` is already initialized or the default OIDC tenant is disabled with `quarkus.oidc.tenant.enabled=false`, irrespectively of whether you work with Keycloak or not.

Expand Down