diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml index e6cd95333a..eff56c2610 100755 --- a/docbook/reference/en/en-US/master.xml +++ b/docbook/reference/en/en-US/master.xml @@ -14,6 +14,7 @@ + @@ -91,6 +92,7 @@ This one is short &TomcatAdapter; &Jetty9Adapter; &Jetty8Adapter; + &FuseAdapter; &JavascriptAdapter; &InstalledApplications; &Logout; diff --git a/docbook/reference/en/en-US/modules/fuse-adapter.xml b/docbook/reference/en/en-US/modules/fuse-adapter.xml new file mode 100644 index 0000000000..22224c1f2b --- /dev/null +++ b/docbook/reference/en/en-US/modules/fuse-adapter.xml @@ -0,0 +1,41 @@ +
+ JBoss Fuse and Apache Karaf Adapter + + Currently Keycloak supports securing your web applications running inside JBoss Fuse + or Apache Karaf . It leverages Jetty 8 adapter as both JBoss Fuse 6.1 + and Apache Karaf 3 are bundled with Jetty 8.1 server under the covers and Jetty is used for running various kinds of web applications. + + + What is supported for Fuse/Karaf is: + + + + Security for classic WAR applications deployed on Fuse/Karaf with Pax Web War Extender. + + + + + Security for servlets deployed on Fuse/Karaf as OSGI services with Pax Web Whiteboard Extender. + + + + + Security for Apache Camel Jetty endpoints running with + Camel Jetty component. + + + + + Security for Apache CXF endpoints running on their own separate + Jetty engine. + + + + + Security for Apache CXF endpoints running on default engine provided by CXF servlet. + + + + + The best place to start is look at Fuse demo bundled as part of Keycloak examples in directory examples/fuse . +
\ No newline at end of file diff --git a/examples/README.md b/examples/README.md index fd88529392..f801ce6298 100755 --- a/examples/README.md +++ b/examples/README.md @@ -58,3 +58,13 @@ Multi tenancy ------------- A complete application, showing how to achieve multi tenancy of web applications by using one realm per account. For more information look at `multi-tenant/README.md` + +Basic authentication +-------------------- + +Example REST application configured to support both basic authentication with username/password as well as authentication with bearer token. For more information look at `basic-auth/README.md` + +Fuse +---- + +This is set of demo applications, showing how to secure your own web applications running inside OSGI environment in JBoss Fuse or Apache Karaf. Fore more information look at `fuse/README.md` diff --git a/examples/fuse/README.md b/examples/fuse/README.md index 20593e26d5..f91821135a 100644 --- a/examples/fuse/README.md +++ b/examples/fuse/README.md @@ -1,17 +1,80 @@ -1) First step is to run Keycloak server on localhost:8080 and import realm "demo" from the file testrealm.json in this directory (Directory "fuse"). +Keycloak Fuse demo +================== -Running example on Karaf 3.0.2 ------------------------------- +Currently Keycloak supports securing your web applications running inside [JBoss Fuse](http://www.jboss.org/products/fuse/overview/) or [Apache Karaf](http://karaf.apache.org/). It leverages Jetty8 adapter +as both JBoss Fuse 6.1 and Apache Karaf 3 are bundled with [Jetty8](http://eclipse.org/jetty/) server under the covers and Jetty is used for running various kinds of web applications. +The Fuse example is slightly modified version of Keycloak base demo applications. The main difference among base demo is that for Fuse demo +are applications running on separate Fuse/Karaf server. Keycloak server is supposed to run separately on Wildfly 8 or JBoss EAP 6.3. + +What is supported for Fuse/Karaf is: +* Security for classic WAR applications deployed on Fuse/Karaf with [pax-war extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War). +* Security for servlets deployed on Fuse/Karaf as OSGI services with [pax-whiteboard extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard). +* Security for [Apache Camel](http://camel.apache.org/) Jetty endpoints running with [camel-jetty](http://camel.apache.org/jetty.html) component. +* Security for [Apache CXF](http://cxf.apache.org/) endpoints running on their own separate [Jetty engine](http://cxf.apache.org/docs/jetty-configuration.html). +Supports both securing JAX-RS and JAX-WS endpoints. +* Security for [Apache CXF](http://cxf.apache.org/) endpoints running on default engine provided by CXF servlet on [http://localhost:8181/cxf](http://localhost:8181/cxf) + +Fuse demo contains those basic applications: +* **customer-app-fuse** A WAR application that is deployed with [pax-war extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War) +* **product-app-fuse** A servlet application deployed with [pax-whiteboard extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard) +* **cxf-jaxws** [Apache CXF](http://cxf.apache.org/) JAX-WS endpoint running on separate Jetty engine on [http://localhost:8282/PersonServiceCF](http://localhost:8282/PersonServiceCF). +The product-app-fuse invokes the endpoint to get data. +* **camel** [Apache Camel](http://camel.apache.org/) endpoint running on separate Jetty engine on [http://localhost:8383/admin-camel-endpoint](http://localhost:8383/admin-camel-endpoint). +The customer-app-fuse invokes the endpoint to get data. +* **cxf-jaxrs** [Apache CXF](http://cxf.apache.org/) JAX-RS endpoint running on default Jetty on [http://localhost:8181/cxf/customerservice](http://localhost:8181/cxf/customerservice). +The customer-app-fuse invokes the endpoint to get data + +Running of demo consists of 2 steps. First you need to run separate Keycloak server and then Fuse/Karaf server with the applications + +Base steps +---------- + +* Run external instance of Keycloak server on WildFly 8 or JBoss EAP 6.3 . Fuse demo suppose that server is running on [http://localhost:8080/auth](http://localhost:8080/auth) +* Import realm `demo` from the file testrealm.json on `examples/fuse/testrealm.json` . +* Then build examples, which is needed so the feature repository is added to your local maven repo: + +``` +cd examples/fuse +mvn clean install +``` + +Run demo applications on Apache Karaf 3.0.2 +------------------------------------------- + +Demo is using Apache camel and Apache CXF, which are not in standalone Karaf by default. So you will need to install feature repositories for both of them. +Next step is to add feature repository for main set of Keycloak karaf features and for the demo. Once all feature URLs are added, you just need to install `keycloak-fuse-example` feature, +which automatically installs all other needed stuff. + +Once you run Apache Karaf, you need to run these commands from Karaf console (Make sure to replace keycloak versions in the example with actual Keycloak version): + +``` feature:repo-add mvn:org.apache.camel.karaf/apache-camel/2.12.5/xml/features feature:repo-add mvn:org.apache.cxf.karaf/apache-cxf/2.7.14/xml/features feature:repo-add mvn:org.keycloak/keycloak-osgi-features/1.1.0.Final/xml/features feature:repo-add mvn:org.keycloak.example.demo/keycloak-fuse-example-features/1.1.0.Final/xml/features feature:install keycloak-fuse-example +``` + +After that you can test running on [http://localhost:8080/customer-portal](http://localhost:8080/customer-portal) and login as "bburke@redhat.com" with password "password". Customer-portal is able to +receive the response from the endpoints provided by `cxf-jaxrs` and `camel` applications. Note that camel endpoint is available just for users with role `admin` +in this demo, so "bburke@redhat.com" can't access it. You may login as "admin" with password "password" in order to invoke camel endpoint. + +From [http://localhost:8080/product-portal](http://localhost:8080/product-portal) you will see servlet endpoint, which invokes JAX-WS provided by `cxf-jaxws` application. + +Note that this demo also secures whole default CXF endpoint on [http://localhost:8181/cxf](http://localhost:8181/cxf) hence every application running under it is secured too. Running example on JBoss Fuse 6.1.0.redhat-379 ---------------------------------------------- +Securing your applications on JBoss Fuse 6.1 is a bit more tricky. There is bug [https://ops4j1.jira.com/browse/PAXWEB-666](https://ops4j1.jira.com/browse/PAXWEB-666) +, which doesn't easily allow to secure default Jetty engine on [http://localhost:8181](http://localhost:8181) as it's not possible to inject +custom Jetty authenticator provided by Keycloak Jetty adapter into underlying Jetty server. Hence first step is to upgrade pax-web +version from default 3.0.6 to newer 3.1.2 . Then you need to "refresh" cxf feature too. Final step is to install "keycloak-fuse-example" feature. + +All the steps could be performed with these commands in Fuse console (Replace Keycloak versions with the current version number again): + +``` features:uninstall pax-war features:uninstall pax-http-whiteboard features:uninstall pax-http @@ -30,4 +93,40 @@ features:uninstall cxf features:install cxf features:install keycloak-fuse-example +``` +Now you can test example applications similarly like described for "Karaf" section. + +How to secure your own applications +----------------------------------- +Most of the steps should be understandable from testing and understanding the demo. Basically all mentioned applications require to + inject Keycloak Jetty authenticator into underlying Jetty server . The steps are bit different according to application type. + +**Classic WAR application** - Take a look at `customer-portal-app` for inspiration. The needed steps are: +* Declare needed constraints in `/WEB-INF/web.xml` +* Add `jetty-web.xml` file with the authenticator to `/WEB-INF/jetty-web.xml` and add `/WEB-INF/keycloak.json` with your Keycloak configuration +* Make sure your WAR imports `org.keycloak.adapters.jetty` and maybe some more packages in MANIFEST.MF file in header `Import-Package`. It's +recommended to use maven-bundle-plugin similarly like Fuse examples are doing, but note that "*" resolution for package doesn't import `org.keycloak.adapters.jetty` package +as it's not used by application or Blueprint or Spring descriptor, but it's used just in jetty-web.xml file. + +**Servlet web application deployed by pax-whiteboard-extender** - Take a look at `product-portal-app` for inspiration. The needed steps are: +* Keycloak provides PaxWebIntegrationService, which allows to inject jetty-authenticator.xml and configure security constraints for your application. +Example `product-portal-app` declares this in `OSGI-INF/blueprint/blueprint.xml` . Note that your servlet needs to depend on it. +* Steps 2,3 are same like for classic WAR + +**Apache camel application** - You can secure your Apache camel endpoint using [camel-jetty](http://camel.apache.org/jetty.html) endpoint by adding securityHandler with KeycloakJettyAuthenticator and +proper security constraints injected. Take a look at `OSGI-INF/blueprint/blueprint.xml` configuration in `camel` application on example of how it can be done. + +**Apache CXF endpoint** - It's recommended to run your CXF endpoints secured by Keycloak on separate Jetty engine. Application `cxf-ws` is using separate endpoint on +[http://localhost:8282](http://localhost:8282) . All the important configuration is declared in cxf-jaxws app in `META-INF/spring/beans.xml` . + +**Builtin web applications** - Some services automatically come with deployed servlets on startup. One of such examples is CXF servlet running on +[http://localhost:8181/cxf](http://localhost:8181/cxf) context. Securing such endpoints is quite tricky. The approach, which Keycloak is currently using, +is providing ServletUnregistrationService, which undeploys builtin servlet at startup, so you are able to re-deploy it again on context secured by Keycloak. +You can see the `OSGI-INF/blueprint/blueprint.xml` inside `cxf-jaxrs` project, which adds JAX-RS "customerservice" endpoint and more importantly, it secures whole `/cxf` context. + +As a side effect, all other CXF services running on default CXF HTTP destination will be secured too. Once you uninstall feature "keycloak-fuse-example" the +original unsecured servlet on `/cxf` context is deployed back and hence context will become unsecured again. + +It's recommended to use your own Jetty engine for your apps (similarly like `cxf-jaxws` application is doing). + \ No newline at end of file