Skip to content

Commit 138f4b2

Browse files
sberyozkinsberyozkin
committed
Show the OIDC testing with devservice section first
1 parent 0f88242 commit 138f4b2

File tree

2 files changed

+139
-130
lines changed

2 files changed

+139
-130
lines changed

‎docs/src/main/asciidoc/security-oidc-bearer-token-authentication.adoc

Lines changed: 96 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -575,6 +575,101 @@ testImplementation("io.rest-assured:rest-assured")
575575
testImplementation("io.quarkus:quarkus-junit5")
576576
----
577577

578+
[[bearer-token-integration-testing-keycloak-devservices]]
579+
==== Dev Services for Keycloak
580+
581+
The preferred approach for integration testing against Keycloak is xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak].
582+
`Dev Services for Keycloak` will start and initialize a test container.
583+
Then, it will create a `quarkus` realm and a `quarkus-app` client (`secret` secret) and add `alice` (`admin` and `user` roles) and `bob` (`user` role) users, where all of these properties can be customized.
584+
585+
First, add the following dependency, which provides a utility class `io.quarkus.test.keycloak.client.KeycloakTestClient` that you can use in tests for acquiring the access tokens:
586+
587+
[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
588+
.pom.xml
589+
----
590+
<dependency>
591+
<groupId>io.quarkus</groupId>
592+
<artifactId>quarkus-test-keycloak-server</artifactId>
593+
<scope>test</scope>
594+
</dependency>
595+
----
596+
597+
[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
598+
.build.gradle
599+
----
600+
testImplementation("io.quarkus:quarkus-test-keycloak-server")
601+
----
602+
603+
Next, prepare your `application.properties` configuration file.
604+
You can start with an empty `application.properties` file because `Dev Services for Keycloak` registers `quarkus.oidc.auth-server-url` and points it to the running test container, `quarkus.oidc.client-id=quarkus-app`, and `quarkus.oidc.credentials.secret=secret`.
605+
606+
However, if you have already configured the required `quarkus-oidc` properties, then you only need to associate `quarkus.oidc.auth-server-url` with the `prod` profile for `Dev Services for Keycloak`to start a container, as shown in the following example:
607+
608+
[source,properties]
609+
----
610+
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
611+
----
612+
613+
If a custom realm file has to be imported into Keycloak before running the tests, configure `Dev Services for Keycloak` as follows:
614+
615+
[source,properties]
616+
----
617+
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
618+
quarkus.keycloak.devservices.realm-path=quarkus-realm.json
619+
----
620+
621+
Finally, write your test, which will be executed in JVM mode, as shown in the following examples:
622+
623+
.Example of a test executed in JVM mode:
624+
625+
[source,java]
626+
----
627+
package org.acme.security.openid.connect;
628+
629+
import io.quarkus.test.junit.QuarkusTest;
630+
import io.quarkus.test.keycloak.client.KeycloakTestClient;
631+
import io.restassured.RestAssured;
632+
import org.junit.jupiter.api.Test;
633+
634+
@QuarkusTest
635+
public class BearerTokenAuthenticationTest {
636+
637+
KeycloakTestClient keycloakClient = new KeycloakTestClient();
638+
639+
@Test
640+
public void testAdminAccess() {
641+
RestAssured.given().auth().oauth2(getAccessToken("alice"))
642+
.when().get("/api/admin")
643+
.then()
644+
.statusCode(200);
645+
RestAssured.given().auth().oauth2(getAccessToken("bob"))
646+
.when().get("/api/admin")
647+
.then()
648+
.statusCode(403);
649+
}
650+
651+
protected String getAccessToken(String userName) {
652+
return keycloakClient.getAccessToken(userName);
653+
}
654+
}
655+
----
656+
657+
.Example of a test executed in native mode:
658+
659+
[source,java]
660+
----
661+
package org.acme.security.openid.connect;
662+
663+
import io.quarkus.test.junit.QuarkusIntegrationTest;
664+
665+
@QuarkusIntegrationTest
666+
public class NativeBearerTokenAuthenticationIT extends BearerTokenAuthenticationTest {
667+
}
668+
----
669+
670+
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.
671+
672+
578673
[[bearer-token-integration-testing-wiremock]]
579674
==== WireMock
580675

@@ -697,7 +792,7 @@ public class CustomOidcWireMockStubTest {
697792
----
698793

699794
[[integration-testing-oidc-test-client]]
700-
=== `OidcTestClient`
795+
==== `OidcTestClient`
701796

702797
If you use SaaS OIDC providers, such as `Auth0`, and want to run tests against the test (development) domain or to run tests against a remote Keycloak test realm, if you already have `quarkus.oidc.auth-server-url` configured, you can use `OidcTestClient`.
703798

@@ -762,100 +857,6 @@ For a test like this to work, the test `Auth0` application must have the `passwo
762857
This example code also shows how to pass additional parameters.
763858
For `Auth0`, these are the `audience` and `scope` parameters.
764859

765-
[[bearer-token-integration-testing-keycloak-devservices]]
766-
==== Dev Services for Keycloak
767-
768-
The preferred approach for integration testing against Keycloak is xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak].
769-
`Dev Services for Keycloak` will start and initialize a test container.
770-
Then, it will create a `quarkus` realm and a `quarkus-app` client (`secret` secret) and add `alice` (`admin` and `user` roles) and `bob` (`user` role) users, where all of these properties can be customized.
771-
772-
First, add the following dependency, which provides a utility class `io.quarkus.test.keycloak.client.KeycloakTestClient` that you can use in tests for acquiring the access tokens:
773-
774-
[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
775-
.pom.xml
776-
----
777-
<dependency>
778-
<groupId>io.quarkus</groupId>
779-
<artifactId>quarkus-test-keycloak-server</artifactId>
780-
<scope>test</scope>
781-
</dependency>
782-
----
783-
784-
[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
785-
.build.gradle
786-
----
787-
testImplementation("io.quarkus:quarkus-test-keycloak-server")
788-
----
789-
790-
Next, prepare your `application.properties` configuration file.
791-
You can start with an empty `application.properties` file because `Dev Services for Keycloak` registers `quarkus.oidc.auth-server-url` and points it to the running test container, `quarkus.oidc.client-id=quarkus-app`, and `quarkus.oidc.credentials.secret=secret`.
792-
793-
However, if you have already configured the required `quarkus-oidc` properties, then you only need to associate `quarkus.oidc.auth-server-url` with the `prod` profile for `Dev Services for Keycloak`to start a container, as shown in the following example:
794-
795-
[source,properties]
796-
----
797-
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
798-
----
799-
800-
If a custom realm file has to be imported into Keycloak before running the tests, configure `Dev Services for Keycloak` as follows:
801-
802-
[source,properties]
803-
----
804-
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
805-
quarkus.keycloak.devservices.realm-path=quarkus-realm.json
806-
----
807-
808-
Finally, write your test, which will be executed in JVM mode, as shown in the following examples:
809-
810-
.Example of a test executed in JVM mode:
811-
812-
[source,java]
813-
----
814-
package org.acme.security.openid.connect;
815-
816-
import io.quarkus.test.junit.QuarkusTest;
817-
import io.quarkus.test.keycloak.client.KeycloakTestClient;
818-
import io.restassured.RestAssured;
819-
import org.junit.jupiter.api.Test;
820-
821-
@QuarkusTest
822-
public class BearerTokenAuthenticationTest {
823-
824-
KeycloakTestClient keycloakClient = new KeycloakTestClient();
825-
826-
@Test
827-
public void testAdminAccess() {
828-
RestAssured.given().auth().oauth2(getAccessToken("alice"))
829-
.when().get("/api/admin")
830-
.then()
831-
.statusCode(200);
832-
RestAssured.given().auth().oauth2(getAccessToken("bob"))
833-
.when().get("/api/admin")
834-
.then()
835-
.statusCode(403);
836-
}
837-
838-
protected String getAccessToken(String userName) {
839-
return keycloakClient.getAccessToken(userName);
840-
}
841-
}
842-
----
843-
844-
.Example of a test executed in native mode:
845-
846-
[source,java]
847-
----
848-
package org.acme.security.openid.connect;
849-
850-
import io.quarkus.test.junit.QuarkusIntegrationTest;
851-
852-
@QuarkusIntegrationTest
853-
public class NativeBearerTokenAuthenticationIT extends BearerTokenAuthenticationTest {
854-
}
855-
----
856-
857-
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.
858-
859860
ifndef::no-deprecated-test-resource[]
860861
[[bearer-token-integration-testing-keycloak]]
861862
==== `KeycloakTestResourceLifecycleManager`

‎docs/src/main/asciidoc/security-oidc-code-flow-authentication.adoc

Lines changed: 43 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1810,6 +1810,49 @@ testImplementation("org.htmlunit:htmlunit")
18101810
testImplementation("io.quarkus:quarkus-junit5")
18111811
----
18121812

1813+
[[code-flow-integration-testing-keycloak-devservices]]
1814+
=== Dev Services for Keycloak
1815+
1816+
For integration testing against Keycloak, use xref:security-openid-connect-dev-services.adoc[Dev services for Keycloak].
1817+
This service initializes a test container, creates a `quarkus` realm, and configures a `quarkus-app` client with the secret `secret`.
1818+
It also sets up two users: `alice` with `admin` and `user` roles, and `bob` with the `user` role.
1819+
All these properties are customizable. For details, see xref:security-openid-connect-dev-services.adoc#keycloak-initialization[Keycloak Initialization].
1820+
1821+
First, prepare the `application.properties` file.
1822+
1823+
If starting from an empty `application.properties` file, `Dev Services for Keycloak` automatically registers the following properties:
1824+
1825+
- `quarkus.oidc.auth-server-url`, which points to the running test container.
1826+
- `quarkus.oidc.client-id=quarkus-app`.
1827+
- `quarkus.oidc.credentials.secret=secret`.
1828+
1829+
If you already have the required `quarkus-oidc` properties configured, associate `quarkus.oidc.auth-server-url` with the `prod` profile.
1830+
This ensures that `Dev Services for Keycloak` starts the container as expected.
1831+
For example:
1832+
1833+
[source,properties]
1834+
----
1835+
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
1836+
----
1837+
1838+
To import a custom realm file into Keycloak before running the tests, configure `Dev services for Keycloak` as shown:
1839+
1840+
[source,properties]
1841+
----
1842+
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
1843+
quarkus.keycloak.devservices.realm-path=quarkus-realm.json
1844+
----
1845+
1846+
Finally, write the test code as described in the <<code-flow-integration-testing-wiremock,Wiremock>> section.
1847+
The only difference is that `@QuarkusTestResource` is no longer required:
1848+
1849+
[source, java]
1850+
----
1851+
@QuarkusTest
1852+
public class CodeFlowAuthorizationTest {
1853+
}
1854+
----
1855+
18131856
[[code-flow-integration-testing-wiremock]]
18141857
=== Wiremock
18151858

@@ -1897,41 +1940,6 @@ Additionally, `OidcWiremockTestResource` sets the token issuer and audience to `
18971940

18981941
`OidcWiremockTestResource` can be used to emulate all OIDC providers.
18991942

1900-
[[code-flow-integration-testing-keycloak-devservices]]
1901-
=== Dev Services for Keycloak
1902-
1903-
Using xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] is recommended for integration testing against Keycloak.
1904-
`Dev Services for Keycloak` will start and initialize a test container: it will create a `quarkus` realm, a `quarkus-app` client (`secret` secret), and add `alice` (`admin` and `user` roles) and `bob` (`user` role) users, where all of these properties can be customized.
1905-
1906-
First, prepare `application.properties`.
1907-
You can start with a completely empty `application.properties` file as `Dev Services for Keycloak` will register `quarkus.oidc.auth-server-url` pointing to the running test container as well as `quarkus.oidc.client-id=quarkus-app` and `quarkus.oidc.credentials.secret=secret`.
1908-
1909-
However, if you already have all the required `quarkus-oidc` properties configured, then you only need to associate `quarkus.oidc.auth-server-url` with the `prod` profile for `Dev Services for Keycloak` to start a container.
1910-
For example:
1911-
1912-
[source,properties]
1913-
----
1914-
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
1915-
----
1916-
1917-
If a custom realm file has to be imported into Keycloak before running the tests, then you can configure `Dev Services for Keycloak` as follows:
1918-
1919-
[source,properties]
1920-
----
1921-
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
1922-
quarkus.keycloak.devservices.realm-path=quarkus-realm.json
1923-
----
1924-
1925-
Finally, write a test code the same way as it is described in the <<code-flow-integration-testing-wiremock,Wiremock>> section.
1926-
The only difference is that `@QuarkusTestResource` is no longer needed:
1927-
1928-
[source, java]
1929-
----
1930-
@QuarkusTest
1931-
public class CodeFlowAuthorizationTest {
1932-
}
1933-
----
1934-
19351943
ifndef::no-deprecated-test-resource[]
19361944
[[code-flow-integration-testing-keycloak]]
19371945
=== Using KeycloakTestResourceLifecycleManager

0 commit comments

Comments
 (0)