From fda62c21b7bf79078471cfab20416dbe9dc36a61 Mon Sep 17 00:00:00 2001 From: mposolda Date: Thu, 2 Jun 2016 16:29:37 +0200 Subject: [PATCH] Fuse adapter documentation --- topics/oidc/java/fuse-adapter.adoc | 91 ++++++++++++++++++++++++++++-- 1 file changed, 87 insertions(+), 4 deletions(-) diff --git a/topics/oidc/java/fuse-adapter.adoc b/topics/oidc/java/fuse-adapter.adoc index b74d5a52fa..c8833f4154 100755 --- a/topics/oidc/java/fuse-adapter.adoc +++ b/topics/oidc/java/fuse-adapter.adoc @@ -4,7 +4,9 @@ NOTE: JBoss Fuse is a Technology Preview feature and is not fully supported -Currently Keycloak supports securing your web applications running inside http://www.jboss.org/products/fuse/overview/[JBoss Fuse] or http://karaf.apache.org/[Apache Karaf] . It leverages <<_jetty8_adapter,Jetty 8 adapter>> as both JBoss Fuse 6.1 and Apache Karaf 3 are bundled with http://eclipse.org/jetty/[Jetty 8.1 server] under the covers and Jetty is used for running various kinds of web applications. +Currently Keycloak supports securing your web applications running inside http://www.jboss.org/products/fuse/overview/[JBoss Fuse] or http://karaf.apache.org/[Apache Karaf] . +It leverages <<_jetty8_adapter,Jetty 8 adapter>> as both JBoss Fuse 6.2 and Apache Karaf 3 are bundled with http://eclipse.org/jetty/[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: @@ -13,7 +15,88 @@ What is supported for Fuse/Karaf is: * Security for http://camel.apache.org/[Apache Camel] Jetty endpoints running with http://camel.apache.org/jetty.html[Camel Jetty] component. * Security for http://cxf.apache.org/[Apache CXF] endpoints running on their own separate http://cxf.apache.org/docs/jetty-configuration.html[Jetty engine]. * Security for http://cxf.apache.org/[Apache CXF] endpoints running on default engine provided by CXF servlet. -* Security for SSH and JMX admin access. -* Security for http://hawt.io/[Hawt.io admin console] . +* Security for SSH and JMX admin access. -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 +==== How to secure your web applications inside Fuse + +The best place to start is look at Fuse demo bundled as part of Keycloak examples in directory `fuse` . Most of the steps should be understandable from testing and +understanding the demo. + +Basically all mentioned web applications require to inject Keycloak Jetty authenticator into underlying Jetty server . The steps to achieve it are bit different +according to application type. + + +===== Classic WAR application + +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. + +Take a look at `customer-portal-app` from fuse example for inspiration. + +===== Servlet web application deployed by pax-whiteboard-extender + +The needed steps are: + +* Keycloak provides PaxWebIntegrationService, which allows to inject jetty-web.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 + +Take a look at `product-portal-app` for inspiration. + +===== Apache camel application + +You can secure your Apache camel endpoint using http://camel.apache.org/jetty.html[camel-jetty] 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 in details. + +===== Apache CXF endpoint + +It's recommended to run your CXF endpoints secured by Keycloak on separate Jetty engine. You need to add `META-INF/spring/beans.xml` to your application +and then declare `httpj:engine-factory` with Jetty SecurityHandler with injected `KeycloakJettyAuthenticator` inside. + +Fore more details, take a look at example application `cxf-ws` from Keycloak Fuse demo, which is using separate endpoint on +http://localhost:8282 . All the important configuration inside this application is declared in `META-INF/spring/beans.xml` . + +===== Builtin CXF web applications + +Some services automatically come with deployed servlets on startup. One of such examples is CXF servlet running on +http://localhost:8181/cxf context. Securing such endpoints is quite tricky. The approach, which Keycloak is currently using, +is providing ServletReregistrationService, 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` example, 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-6.2-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). + + +==== How to secure Fuse admin services + +===== SSH authentication to Fuse terminal with Keycloak credentials + +Keycloak mainly addresses usecases for authentication of web applications, however if your admin services (like fuse admin console) are protected +with Keycloak, it may be good to protect non-web services like SSH with Keycloak credentials too. It's possible to do it by using JAAS login module, which +allows to remotely connect to Keycloak and verify credentials based on <<_direct_access_grants,Direct Access Grants>> . + +Example steps for enable SSH authentication require changing the configuration of `sshRealm` in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`, then adding +file `$FUSE_HOME/etc/keycloak-direct-access.json` (this is default location, which can be changed) and install the needed feature `keycloak-jaas`. It's described in details +in the README file of Fuse example, which in example distribution is inside `fuse/fuse-admin/README.md` . + + +===== JMX authentication with Keycloak credentials + +This may be needed in case if you really want to use jconsole or other external tool to perform remote connection to JMX through RMI. Otherwise it may +be better to use just hawt.io/jolokia as jolokia agent is installed in http://hawt.io by default. + +You need to configure `jmxRealm` in `$FUSE_HOME/etc/org.apache.karaf.management.cfg`, then adding file `$FUSE_HOME/etc/keycloak-direct-access.json` +(this is default location, which can be changed) and install the needed feature `keycloak-jaas`. +It's described in details in the README file of Fuse example, which in example distribution is inside `fuse/fuse-admin/README.md` . + + +===== Secure Fuse admin console + +Fuse admin console is Hawt.io. See http://hawt.io/configuration/index.html[Hawt.io documentation] for more info about how to secure it with Keycloak. \ No newline at end of file