Merge pull request #6 from mposolda/master

Fuse adapter documentation
This commit is contained in:
Stian Thorgersen 2016-06-02 19:06:50 +02:00
commit b12802f0d3

View file

@ -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` .
==== 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.