From c7db7bd528fb02f68521eb7289a25ca3dc239a47 Mon Sep 17 00:00:00 2001 From: zak905 Date: Fri, 12 Jan 2024 09:59:32 +0100 Subject: [PATCH] Update custom rest endpoint documentation and example Add a mention about beans.xml and @Provider in the extending server documentation Add beans.xml in the rest provider example Add a mention about @Provider in the upgrading guides Closes #25882 Signed-off-by: zak905 Address suggested change for docs/documentation/server_development/topics/extensions.adoc Co-authored-by: Pedro Igor Address suggested change for docs/documentation/server_development/topics/extensions.adoc Co-authored-by: Pedro Igor Signed-off-by: zak905 Address suggested change for docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc Co-authored-by: Pedro Igor Signed-off-by: zak905 --- .../server_development/topics/extensions.adoc | 3 +++ .../upgrading/topics/keycloak/changes-22_0_0.adoc | 2 ++ examples/providers/rest/README.md | 13 ++----------- .../rest/src/main/resources/META-INF/beans.xml | 0 4 files changed, 7 insertions(+), 11 deletions(-) create mode 100644 examples/providers/rest/src/main/resources/META-INF/beans.xml diff --git a/docs/documentation/server_development/topics/extensions.adoc b/docs/documentation/server_development/topics/extensions.adoc index 2e88d7018fe..d636daf6342 100644 --- a/docs/documentation/server_development/topics/extensions.adoc +++ b/docs/documentation/server_development/topics/extensions.adoc @@ -25,6 +25,9 @@ Object getResource(); ---- Use this method to return an object, which acts as a https://github.com/jax-rs[JAX-RS Resource]. For more details, see the Javadoc and our examples. +Your JAX-RS resource is only recognized by the server and registered as a valid endpoint if it includes the following configuration: +- adding an empty file named `beans.xml` under `META-INF` +- annotating the JAX-RS class with the annotation `jakarta.ws.rs.ext.Provider`. There is a very simple example in the example distribution in `providers/rest` and there is a more advanced example in `providers/domain-extension`, which shows how to add an authenticated REST endpoint and other functionalities like <<_extensions_spi, Adding your own SPI>> or <<_extensions_jpa,Extending the datamodel with custom JPA entities>>. diff --git a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc b/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc index e42b054c089..af729b4b410 100644 --- a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc +++ b/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc @@ -334,6 +334,8 @@ If you are extending the server's REST APIs through the following SPIs: You need to add an empty `META-INF/beans.xml` to the JAR file where your custom providers are packaged. Otherwise, they are not recognized by the server at runtime. +If you are using `RealmResourceSPI` or `AdminRealmResourceSpi`, another alternative to adding an empty `beans.xml` under `META-INF` is annotating the JAX-RS resource classes with the annotation `jakarta.ws.rs.ext.Provider`. + You should also make sure your JAX-RS methods are declaring the expected media types for input and output by marking them with the `@Consumes` and `@Produces` annotations, respectively. = Deprecated methods from data providers and models diff --git a/examples/providers/rest/README.md b/examples/providers/rest/README.md index 0367098be65..2c2fabb0262 100644 --- a/examples/providers/rest/README.md +++ b/examples/providers/rest/README.md @@ -1,16 +1,7 @@ Example Realm REST Resource provider ==================================== -You can deploy as a module by running: +You can deploy the provider by running: `mvn package` and dropping the jar under `$KEYCLOAK_HOME/providers` - $KEYCLOAK_HOME/bin/jboss-cli.sh --command="module add --name=org.keycloak.examples.hello-rest-example --resources=target/hello-rest-example.jar --dependencies=org.keycloak.keycloak-core,org.keycloak.keycloak-server-spi,org.keycloak.keycloak-server-spi-private,javax.ws.rs.api" - -Then registering the provider by editing `standalone/configuration/standalone.xml` and adding the module to the providers element: - - - ... - module:org.keycloak.examples.hello-rest-example - - -Then start (or restart) the server. Once started open http://localhost:8080/auth/realms/master/hello and you should see the message _Hello master_. +Once started open http://localhost:8080/auth/realms/master/hello and you should see the message _Hello master_. You can also invoke the endpoint for other realms by replacing `master` with the realm name in the above url. diff --git a/examples/providers/rest/src/main/resources/META-INF/beans.xml b/examples/providers/rest/src/main/resources/META-INF/beans.xml new file mode 100644 index 00000000000..e69de29bb2d