From c2f68a15b80dff1547717cf0588ea69938187b42 Mon Sep 17 00:00:00 2001 From: mposolda Date: Mon, 13 Nov 2023 11:47:42 +0100 Subject: [PATCH] Quickstarts - Wildfly upgrade and README cleanup closes #505 Signed-off-by: mposolda --- README.md | 7 ++++++ .../action-token-authenticator/README.md | 6 ++--- .../action-token-required-action/README.md | 4 +-- extension/event-listener-sysout/README.md | 8 +++--- extension/event-store-mem/README.md | 8 +++--- extension/extend-account-console/README.md | 8 +++--- extension/user-storage-jpa/README.md | 8 +++--- extension/user-storage-simple/README.md | 8 +++--- jakarta/jaxrs-resource-server/README.md | 10 ++++---- .../src/main/webapp/WEB-INF/oidc.json | 2 +- .../src/main/webapp/WEB-INF/web.xml | 9 ++++--- .../src/main/webapp/WEB-INF/web.xml | 9 ++++--- .../servlet-saml-service-provider/README.md | 4 +++ js/spa/README.md | 25 ++++++++++++++++--- nodejs/resource-server/README.md | 12 ++++----- pom.xml | 6 ++--- spring/rest-authz-resource-server/README.md | 4 +-- 17 files changed, 84 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index b49996c94..2790e778d 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,13 @@ First clone the Keycloak repository: Each quickstart provides its own documentation with the steps you need to follow in order to build, test, and run the example. Look at the `README.md` file at the root of a quickstart for more details. +### Chrome driver version + +Some automated tests rely on the chrome browser present on your laptop. Also you need to have correct version of chrome driver according +to the version of the chrome browser used. In case of the issues, see [Chrome page](https://googlechromelabs.github.io/chrome-for-testing/) and download +correct chrome driver version for your Chrome browser. Then add system property `webdriver.chrome.driver` when running the tests according to chrome version +and add whole path to the chrome driver. For instance something like `-Dwebdriver.chrome.driver=/somedir/chromedriver-linux64-119.0.6045.105/chromedriver`. + ## Help and Documentation * [Documentation](https://www.keycloak.org/documentation.html) diff --git a/extension/action-token-authenticator/README.md b/extension/action-token-authenticator/README.md index f6141941a..cbf5add9e 100644 --- a/extension/action-token-authenticator/README.md +++ b/extension/action-token-authenticator/README.md @@ -64,8 +64,8 @@ a configuration of a single custom SPI implemented in this example: is used in step 5 to verify that the invocation comes from the correct app. NOTE: In production environment, you don't need to use the "confidential" parameters sent in the server startup command. It might be better -to use configuration properties file for it, or even use the Keycloak Valve capabilities. See the Keycloak documentation for more details about provider -options and for the details about how to use the valve. +to use configuration properties file for it, or even use the Keycloak Vault capabilities. See the Keycloak documentation for more details about provider +options and for the details about how to use the vault. The custom authenticator is configured in admin console within the flow that uses it: @@ -102,7 +102,7 @@ You can download latest Wildfly server. If you run the mvn command as described We also need to deploy simple WAR application to it and start the server. In Linux, the commands to do all of that could be for example like this: ``` -export WILDFY_VERSION=wildfly-28.0.0.Beta1 +export WILDFY_VERSION=wildfly-28.0.1.Final cp -r target/$WILDFY_VERSION /tmp/ cp target/deployments/wildfly_action-token-responder-example_action-token-responder-example.war /tmp/$WILDFY_VERSION/standalone/deployments/action-token-responder-example.war cd /tmp/$WILDFY_VERSION/bin diff --git a/extension/action-token-required-action/README.md b/extension/action-token-required-action/README.md index fd6bda25c..d4126d858 100644 --- a/extension/action-token-required-action/README.md +++ b/extension/action-token-required-action/README.md @@ -72,7 +72,7 @@ a configuration of two custom SPIs implemented in this example: NOTE: In production environment, you don't need to use the "confidential" parameters sent in the server startup command, which in this case applies especially for the `hmac-secret` configuration parameter. It might be better to use configuration properties file for it, or even use -the Keycloak Valve capabilities. See the Keycloak documentation for more details about provider options and for the details about how to use the valve. +the Keycloak Vault capabilities. See the Keycloak documentation for more details about provider options and for the details about how to use the vault. Note that you need to deploy the responder application into WildFly. A sample responder application is part of the tests, so you first need to run the tests in order to have the WAR archive @@ -101,7 +101,7 @@ You can download latest Wildfly server. If you run the mvn command as described We also need to deploy simple WAR application to it and start the server. In Linux, the commands to do all of that could be for example like this: ``` -export WILDFY_VERSION=wildfly-28.0.0.Beta1 +export WILDFY_VERSION=wildfly-28.0.1.Final cp -r target/$WILDFY_VERSION /tmp/ cp target/deployments/wildfly_action-token-responder-example_action-token-responder-example.war /tmp/$WILDFY_VERSION/standalone/deployments/action-token-responder-example.war cd /tmp/$WILDFY_VERSION/bin diff --git a/extension/event-listener-sysout/README.md b/extension/event-listener-sysout/README.md index 4d3ad5e6e..fec2d21bd 100644 --- a/extension/event-listener-sysout/README.md +++ b/extension/event-listener-sysout/README.md @@ -22,7 +22,7 @@ System Requirements You need to have Keycloak running. It is recommended to use Keycloak 22 or later. -All you need to build this project is Java 11 (Java SDK 11) or later and Maven 3.6.3 or later. +All you need to build this project is Java 17 (Java SDK 17) or later and Maven 3.6.3 or later. Build and Deploy the Quickstart ------------------------------- @@ -30,7 +30,7 @@ Build and Deploy the Quickstart To build the provider, run the following maven command: ```` - mvn -Pextension clean install + mvn -Pextension clean install -DskipTests=true ```` To install the provider, copy the target/event-listener-sysout.jar JAR file to the `providers` directory of the server distribution. @@ -57,8 +57,8 @@ Integration test of the Quickstart Your Keycloak should be listening on `http://localhost:8180` and should have excluded events configured (at least `CODE_TO_TOKEN). See in the previous section how the startup command for the server should look like. -2. You need to have Chrome browser installed and updated to the latest version. -3. Run `mvn clean install -Djakarta` +2. You need to have Chrome browser installed and updated to the latest version. See [README](../../README.md#chrome-driver-version) for additional details. +3. Run `mvn clean install -Dextension` Undeploy the quickstart ----------------------- diff --git a/extension/event-store-mem/README.md b/extension/event-store-mem/README.md index 9fc302e5f..a7f2e9954 100644 --- a/extension/event-store-mem/README.md +++ b/extension/event-store-mem/README.md @@ -34,7 +34,7 @@ System Requirements You need to have Keycloak running. It is recommended to use Keycloak 22 or later. -All you need to build this project is Java 11 (Java SDK 11) or later and Maven 3.6.3 or later. +All you need to build this project is Java 17 (Java SDK 17) or later and Maven 3.6.3 or later. Build and Deploy the Quickstart @@ -43,7 +43,7 @@ Build and Deploy the Quickstart To build the provider, run the following maven command: ```` - mvn -Pextension clean install + mvn -Pextension clean install -DskipTests=true ```` To install the provider, copy the target/event-store-mem.jar JAR file to the `providers` directory of the server distribution. @@ -73,8 +73,8 @@ Integration test of the Quickstart Your Keycloak should be listening on `http://localhost:8180` and should have set `in-mem` as the default `eventsStore` provider. See in the previous section how the startup command for the server should look like. -2. You need to have Chrome browser installed and updated to the latest version. -3. Run `mvn clean install -Djakarta` +2. You need to have Chrome browser installed and updated to the latest version. See [README](../../README.md#chrome-driver-version) for additional details. +3. Run `mvn clean install -Dextension` Undeploy the quickstart diff --git a/extension/extend-account-console/README.md b/extension/extend-account-console/README.md index 89e644087..e0e0283b5 100644 --- a/extension/extend-account-console/README.md +++ b/extension/extend-account-console/README.md @@ -25,7 +25,7 @@ System Requirements You need to have Keycloak running. It is recommended to use Keycloak 22 or later. -All you need to build this project is Java 11 (Java SDK 11) or later and Maven 3.6.3 or later. +All you need to build this project is Java 17 (Java SDK 17) or later and Maven 3.6.3 or later. If you want to do the JSX example, you will need to install npm on your system. @@ -38,7 +38,7 @@ Configuration in Keycloak To build the provider, run the following maven command: ```` - mvn -Pextension clean install + mvn -Pextension clean install -DskipTests=true ```` To install the provider, copy the `target/keycloak-man-theme.jar` JAR file to the `providers` directory of the server distribution. @@ -67,5 +67,5 @@ Integration test of the Quickstart ./kc.sh start-dev --http-port=8180 ``` -2. You need to have Chrome browser installed and updated to the latest version. -3. Run `mvn clean install -Djakarta` +2. You need to have Chrome browser installed and updated to the latest version. See [README](../../README.md#chrome-driver-version) for additional details. +3. Run `mvn clean install -Dextension` diff --git a/extension/user-storage-jpa/README.md b/extension/user-storage-jpa/README.md index a77e27036..731b2d3b0 100755 --- a/extension/user-storage-jpa/README.md +++ b/extension/user-storage-jpa/README.md @@ -23,7 +23,7 @@ System Requirements You need to have Keycloak running. It is recommended to use Keycloak 22 or later. -All you need to build this project is Java 11 (Java SDK 11) or later and Maven 3.6.3 or later. +All you need to build this project is Java 17 (Java SDK 17) or later and Maven 3.6.3 or later. Build and Deploy the Quickstart ------------------------------- @@ -36,7 +36,7 @@ you make sure the persistence unit will be using the correct datasource. To build the provider, run the following maven command: ```` - mvn -Pextension clean install + mvn -Pextension clean install -DskipTests=true ```` To install the provider, copy the target/user-storage-jpa-example.jar JAR file to the `providers` directory of the server distribution. @@ -61,8 +61,8 @@ Integration test of the Quickstart ./kc.sh start-dev --http-port=8180 ``` -2. You need to have Chrome browser installed and updated to the latest version. -3. Run `mvn clean install -Djakarta` +2. You need to have Chrome browser installed and updated to the latest version. See [README](../../README.md#chrome-driver-version) for additional details. +3. Run `mvn clean install -Dextension` More Information ---------------- diff --git a/extension/user-storage-simple/README.md b/extension/user-storage-simple/README.md index 8e0a2d51e..0ada43c66 100755 --- a/extension/user-storage-simple/README.md +++ b/extension/user-storage-simple/README.md @@ -33,7 +33,7 @@ System Requirements You need to have Keycloak running. It is recommended to use Keycloak 22 or later. -All you need to build this project is Java 11 (Java SDK 11) or later and Maven 3.6.3 or later. +All you need to build this project is Java 17 (Java SDK 17) or later and Maven 3.6.3 or later. Build and Deploy the Quickstart @@ -42,7 +42,7 @@ Build and Deploy the Quickstart To build the provider, run the following maven command: ```` - mvn -Pextension clean install + mvn -Pextension clean install -DskipTests=true ```` To install the provider, copy the target/user-storage-properties-example.jar JAR file to the `providers` directory of the server distribution. @@ -76,8 +76,8 @@ Integration test of the Quickstart ./kc.sh start-dev --http-port=8180 ``` -2. You need to have Chrome browser installed and updated to the latest version. -3. Run `mvn clean install -Djakarta` +2. You need to have Chrome browser installed and updated to the latest version. See [README](../../README.md#chrome-driver-version) for additional details. +3. Run `mvn clean install -Dextension` More Information ---------------- diff --git a/jakarta/jaxrs-resource-server/README.md b/jakarta/jaxrs-resource-server/README.md index 208c4c121..2502fefe9 100644 --- a/jakarta/jaxrs-resource-server/README.md +++ b/jakarta/jaxrs-resource-server/README.md @@ -71,9 +71,9 @@ Access the Quickstart There are 3 endpoints exposed by the service: -* http://localhost:8080/service/public - requires no authentication -* http://localhost:8080/service/secured - can be invoked by users with the `user` role -* http://localhost:8080/service/admin - can be invoked by users with the `admin` role +* http://localhost:8080/jakarta-jaxrs-resource-server/public - requires no authentication +* http://localhost:8080/jakarta-jaxrs-resource-server/secured - can be invoked by users with the `user` role +* http://localhost:8080/jakarta-jaxrs-resource-server/admin - can be invoked by users with the `admin` role You can open the public endpoint directly in the browser to test the service. The two other endpoints are protected and require invoking them with a bearer token. @@ -89,7 +89,7 @@ You should be able to obtain tokens for any of these users: | alice | alice | user | | admin | admin | admin | -To obtain the bearer token, run the following command: +To obtain the bearer token, run for instance the following command when on Linux (please make sure to have `curl` and `jq` packages available in your linux distribution): ```shell export access_token=$(\ @@ -102,7 +102,7 @@ curl -X POST http://localhost:8180/realms/quickstart/protocol/openid-connect/tok You can use the same command to obtain tokens on behalf of user `admin`, just make sure to change both `username` and `password` request parameters. -After running the command above, you can now access the `http://localhost:8080/service/secured` endpoint +After running the command above, you can now access the `http://localhost:8080/jakarta-jaxrs-resource-server/secured` endpoint because the user `alice` has the `user` role. ```shell diff --git a/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/oidc.json b/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/oidc.json index 74441a4ba..3daa4a0d8 100644 --- a/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/oidc.json +++ b/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/oidc.json @@ -2,6 +2,6 @@ "realm": "quickstart", "auth-server-url": "http://localhost:8180", "ssl-required": "external", - "resource": "service-jaxrs", + "resource": "jakarta-jaxrs-resource-server", "bearer-only": true } \ No newline at end of file diff --git a/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/web.xml b/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/web.xml index a934b203e..232f5e97c 100755 --- a/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/web.xml +++ b/jakarta/jaxrs-resource-server/src/main/webapp/WEB-INF/web.xml @@ -15,10 +15,11 @@ See the License for the specific language governing permissions and limitations under the License. --> - + secured diff --git a/jakarta/servlet-authz-client/src/main/webapp/WEB-INF/web.xml b/jakarta/servlet-authz-client/src/main/webapp/WEB-INF/web.xml index 5d4d4c2de..049af1164 100644 --- a/jakarta/servlet-authz-client/src/main/webapp/WEB-INF/web.xml +++ b/jakarta/servlet-authz-client/src/main/webapp/WEB-INF/web.xml @@ -1,8 +1,9 @@ - + diff --git a/jakarta/servlet-saml-service-provider/README.md b/jakarta/servlet-saml-service-provider/README.md index 2e18c994f..7d866b5f6 100755 --- a/jakarta/servlet-saml-service-provider/README.md +++ b/jakarta/servlet-saml-service-provider/README.md @@ -54,6 +54,10 @@ In order to deploy the example application, you need a Wildfly Server up and run Make sure the server is accessible from `localhost` and listening on port `8080`. +Once you verified that JBoss EAP server works, it is needed to install SAML adapter into it. You can follow the [SAML Adapter documentation](https://www.keycloak.org/docs/latest/securing_apps/index.html#_saml_jboss_adapter) +for the details. Just make sure that you download Jakarta version of the SAML adapter. +It can be downloaded from the following URL (replace $KC_VERSION with requested Keycloak version) https://repo1.maven.org/maven2/org/keycloak/keycloak-saml-wildfly-adapter-jakarta-dist/$KC_VERSION/keycloak-saml-wildfly-adapter-jakarta-dist-$KC_VERSION.zip . + Build and Deploy the Quickstart ------------------------------- diff --git a/js/spa/README.md b/js/spa/README.md index 299bc06cc..931cba18b 100644 --- a/js/spa/README.md +++ b/js/spa/README.md @@ -48,7 +48,7 @@ Log in as the admin user to access the Keycloak Administration Console. Username Import the [realm configuration file](config/realm-import.json) to create a new realm called `quickstart`. For more details, see the Keycloak documentation about how to [create a new realm](https://www.keycloak.org/docs/latest/server_admin/index.html#_create-realm). -Alternatively, you can create the realm using the following command: +Alternatively, you can create the realm using the following command (it might require first to run `npm install`): ```shell npm run create-realm @@ -88,16 +88,33 @@ Once authenticated, you are redirected to the application and you can perform th Running tests -------------------- -Make sure Keycloak is [running](#starting-and-configuring-the-keycloak-server). +Make sure Keycloak is [running](#starting-and-configuring-the-keycloak-server). At the same time, the `npm` should be stopped, so there is nothing listening on http://localhost:8080 . -1. Open a terminal and navigate to the root directory of this quickstart. +1. The test assumes that `quickstart` realm does not yet exists. If you already imported it as mentioned in previous steps, it may be needed to remove it first. + It can be done by login in admin console, then going to URL like http://localhost:8180/admin/master/console/#/quickstart/realm-settings and then click `Delete` at the `Action` menu on the left top corner. + +Alternatively, it can be done by command: +```shell +npm run delete-realm +``` + +2. Open a terminal and navigate to the root directory of this quickstart. -2. Run the following command to build and run tests: +3. Run the following command to build and run tests: ```` npm test ```` +#### Test troubleshooting + +If there is error message like `Executable doesn't exist at /home/yournick/.cache/ms-playwright/chromium-1060/chrome-linux/chrome`, it may be needed to first install playwright with this command: + +```shell +npx playwright install +``` + + References -------------------- diff --git a/nodejs/resource-server/README.md b/nodejs/resource-server/README.md index 189cef56d..ea723ee6a 100644 --- a/nodejs/resource-server/README.md +++ b/nodejs/resource-server/README.md @@ -52,7 +52,7 @@ Log in as the admin user to access the Keycloak Administration Console. Username Import the [realm configuration file](config/realm-import.json) to create a new realm called `quickstart`. For more details, see the Keycloak documentation about how to [create a new realm](https://www.keycloak.org/docs/latest/server_admin/index.html#_create-realm). -Alternatively, you can create the realm using the following command: +Alternatively, you can create the realm using the following command (it might require first to run `npm install`):: ```shell npm run create-realm @@ -75,9 +75,9 @@ Access the Quickstart There are 3 endpoints exposed by the service: -* http://localhost:8080/public - requires no authentication -* http://localhost:8080/secured - can be invoked by users with the `user` role -* http://localhost:8080/admin - can be invoked by users with the `admin` role +* http://localhost:3000/public - requires no authentication +* http://localhost:3000/secured - can be invoked by users with the `user` role +* http://localhost:3000/admin - can be invoked by users with the `admin` role You can open the public endpoint directly in the browser to test the service. The two other endpoints are protected and require invoking them with a bearer token. @@ -93,7 +93,7 @@ You should be able to obtain tokens for any of these users: | alice | alice | user | | admin | admin | admin | -To obtain the bearer token, run the following command: +To obtain the bearer token, run for instance the following command when on Linux (please make sure to have `curl` and `jq` packages available in your linux distribution): ```shell export access_token=$(\ @@ -123,7 +123,7 @@ As a result, you will see the following response from the service: Running tests -------------------- -Make sure Keycloak is [running](#starting-and-configuring-the-keycloak-server). +Make sure Keycloak is [running](#starting-and-configuring-the-keycloak-server). Also make sure that node server is still listening on http://localhost:3000 . 1. Open a terminal and navigate to the root directory of this quickstart. diff --git a/pom.xml b/pom.xml index 0db199a9e..69d44e559 100644 --- a/pom.xml +++ b/pom.xml @@ -57,7 +57,7 @@ 2.3.1 true - 1.2.2.Final + 4.1.1.Final ./jboss-cli.sh 10090 3.11.0 @@ -173,7 +173,7 @@ - 28.0.0.Beta1 + 28.0.1.Final 3.1.0 2.5.4 4.0.0.Alpha6 @@ -370,7 +370,7 @@ - 28.0.0.Beta1 + 28.0.1.Final 3.1.0 2.5.4 1.7.0.Alpha14 diff --git a/spring/rest-authz-resource-server/README.md b/spring/rest-authz-resource-server/README.md index 9e8b3cd8a..f757b0cef 100644 --- a/spring/rest-authz-resource-server/README.md +++ b/spring/rest-authz-resource-server/README.md @@ -83,7 +83,7 @@ You should be able to obtain tokens for any of these users: | jdoe | jdoe | user_premium | | alice | alice | user | -To obtain the bearer token, run the following command: +To obtain the bearer token, run for instance the following command when on Linux (please make sure to have `curl` and `jq` packages available in your linux distribution): ```shell export access_token=$(\ @@ -169,7 +169,7 @@ You don't need Wildfly running because a temporary server is started during test 2. Run the following command to build and run tests: ```` - mvn -Djakarta clean verify + mvn -Dspring clean verify ```` References