Merge branch 'master' of github.com:keycloak/securing_apps_guide

topics/oidc/java/application-clustering.adoc

@@ -1,5 +1,5 @@
 [[_applicationclustering]]
-= Application Clustering
+=== Application Clustering
 
 This chapter is focused on clustering support for your own AS7, EAP6 or Wildfly applications, which are secured by Keycloak.
 We support various deployment scenarios according if your application is: 
@@ -13,7 +13,7 @@ The situation is a bit tricky as application communicates with Keycloak directly
 NOTE: To enable distributable (replicated) HTTP Sessions in your application, you may need to do some additional steps.
 Usually you need to put tag into `WEB-INF/web.xml` file of your application and possibly do some additional steps to configure underlying cluster cache (In case of Wildfly, the implementation of cluster cache is based on Infinispan). These steps are server specific, so consult documentation of your application server for more details. 
 
-== Stateless token store
+==== Stateless token store
 
 By default, the servlet web application secured by Keycloak uses HTTP session to store information about authenticated user account.
 This means that this info could be replicated across cluster and your application will safely survive failover of some cluster node. 
@@ -42,7 +42,7 @@ It works without issues if you init servlet logout (HttpServletRequest.logout) f
 But back-channel logout initialized from different application can't be propagated by Keycloak to this application with cookie store.
 Hence it's recommended to use very short value of access token timeout (1 minute for example). 
 
-== Relative URI optimization
+==== Relative URI optimization
 
 In many deployment scenarios will be Keycloak and secured applications deployed on same cluster hosts.
 For this case Keycloak already provides option to use relative URI as value of option _auth-server-url_ in `WEB-INF/keycloak.json` . In this case, the URI of Keycloak server is resolved from the URI of current request. 
@@ -63,7 +63,7 @@ This would mean that browser requests (like redirecting to Keycloak login screen
 
 Note that additionally to network optimization, you may not need "https" in this case as application and keycloak are communicating directly within same cluster host. 
 
-== Admin URL configuration
+==== Admin URL configuration
 
 Admin URL for particular application can be configured in Keycloak admin console.
 It's used by Keycloak server to send backend requests to application for various tasks, like logout users or push revocation policies. 
@@ -88,7 +88,7 @@ http://${application.session.host}:8080/myapp::
   Keycloak will track hosts where is particular HTTP Session served and it will send session invalidation message to proper cluster node.             
 
 [[_registration_app_nodes]]
-== Registration of application nodes to Keycloak
+==== Registration of application nodes to Keycloak
 
 Previous section describes how can Keycloak send logout request to proper application node.
 However in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them.
@@ -116,7 +116,7 @@ which means that registration is sent at startup (accurately when 1st request is
 In Keycloak admin console you can specify the maximum node re-registration timeout (makes sense to have it bigger than _register-node-period_ from adapter configuration for particular application). Also you can manually add and remove cluster nodes in admin console, which is useful if you don't want to rely on adapter's automatic registration or if you want to remove stale application nodes, which weren't unregistered (for example due to forced shutdown). 
 
 [[_refresh_token_each_req]]
-== Refresh token in each request
+==== Refresh token in each request
 
 By default, application adapter tries to refresh access token when it's expired (period can be specified as <<_token_timeouts,Access Token Lifespan>>) . However if you don't want to rely on the fact, that Keycloak is able to successfully propagate admin events like logout to your application nodes, then you have possibility to configure adapter to refresh access token in each HTTP request. 
 

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: 
 
@@ -14,6 +16,87 @@ What is supported for Fuse/Karaf is:
 * 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] .     
 
-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.