Merge pull request #52 from mposolda/master

KEYCLOAK-3956 Update fuse documentation. Added docs for Hawtio

SUMMARY.adoc

@@ -18,6 +18,7 @@
       .... link:topics/oidc/java/fuse/cxf-separate.adoc[Apache CXF on Separate Jetty]
       .... link:topics/oidc/java/fuse/cxf-builtin.adoc[Apache CXF on default Jetty]
       .... link:topics/oidc/java/fuse/fuse-admin.adoc[Fuse Admin Services]
+      .... link:topics/oidc/java/fuse/hawtio.adoc[Hawtio Admin Console]
       {% if book.community %}
       ... link:topics/oidc/java/tomcat-adapter.adoc[Tomcat 6, 7 and 8 Adapters]
       ... link:topics/oidc/java/jetty9-adapter.adoc[Jetty 9.x Adapters]

book.json

@@ -29,6 +29,7 @@
     "installguide": {
       "name": "Server Installation and Configuration Guide",
       "link": "https://keycloak.gitbooks.io/server-installation-and-configuration/content/"
-    }
+    },
+    "fuseVersion": "JBoss Fuse 6.3.0 Rollup 1"
   }
 }

topics/oidc/java/fuse-adapter.adoc

@@ -7,11 +7,15 @@ NOTE: JBoss Fuse is a Technology Preview feature and is not fully supported
 {% endif %}
 
 Currently {{book.project.name}} supports securing your web applications running inside http://www.jboss.org/products/fuse/overview/[JBoss Fuse] .
+
 {% if book.community %}
-It leverages <<fake/../jetty8-adapter.adoc#_jetty8_adapter,Jetty 8 adapter>> as both JBoss Fuse 6.2 are bundled with http://eclipse.org/jetty/[Jetty 8.1 server]
+It leverages <<fake/../jetty9-adapter.adoc#_jetty9_adapter,Jetty 9 adapter>> as {{book.fuseVersion}} is bundled with http://eclipse.org/jetty/[Jetty 9.2 server]
 under the covers and Jetty is used for running various kinds of web applications.
 {% endif %}
 
+WARNING: The only supported Fuse version is {{book.fuseVersion}} . If you use older Fuse versions, it's possible that some functionalities won't work correctly.
+Especially the http://hawt.io[Hawtio] integration won't work with older Fuse versions.
+
 What is supported for Fuse is:
 
 * Security for classic WAR applications deployed on Fuse with https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War[Pax Web War Extender].
@@ -20,6 +24,7 @@ What is supported for Fuse 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[Hawtio admin console]
 
 ===== How to secure your web applications inside Fuse
 

topics/oidc/java/fuse/camel.adoc

@@ -97,7 +97,7 @@ org.osgi.service.event,
 
 Camel RestDSL is a Camel feature to define your REST endpoints in a fluent way.
 But under the hood, the capability to provide all this magic, is still demanded to specific implementation classes and
-you have to instruct them on how to integrate with Keycloak.
+you have to instruct them on how to integrate with {{book.project.name}}.
 
 The way to configure the integration mechanism depends on the Camel component that you configure your RestDSL defined routes to work with.
 

topics/oidc/java/fuse/classic-war.adoc

@@ -63,7 +63,7 @@ The example configuration can look like this:
 ----
 
 * Add `/WEB-INF/keycloak.json` with your {{book.project.name}} configuration. The format of this config file is described
-in the <<fake/../../java-adapter-config.adoc#_java_adapter_config,Java Adapters Config>> section.
+in the <<fake/../../java-adapter-config.adoc#_java_adapter_config,Java Adapters Config>> section. It is also possible to have this file available externally as described below.
 
 * Make sure your WAR imports `org.keycloak.adapters.jetty` and maybe some more packages in `META-INF/MANIFEST.MF` file in header `Import-Package`. It's
 recommended to use `maven-bundle-plugin` in your project to properly generate OSGI headers in manifest.
@@ -80,3 +80,23 @@ org.keycloak.*;version="{{book.project.versionMvn}}",
 *;resolution:=optional
 ----
 
+====== External adapter configuration
+
+This is for the case when you don't want adapter configuration file `keycloak.json` to be bundled inside your WAR application. Instead it will be available
+externally and loaded based on naming conventions.
+
+To enable the functionality you need to add this section to your `web.xml`:
+
+[source,xml]
+----
+<context-param>
+    <param-name>keycloak.config.resolver</param-name>
+    <param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
+</context-param>
+----
+
+That component will use `keycloak.config` or `karaf.etc` java properties to look for a base folder to look for the configuration.
+Inside one of those folders it will look for a file called `<your_web_context>-keycloak.json`.
+
+So for example if your web application has context `my-portal`, then your adapter configuration will be loaded from the file `$FUSE_HOME/etc/my-portal-keycloak.json` .
+

topics/oidc/java/fuse/fuse-admin.adoc

@@ -12,7 +12,7 @@ by using JAAS login module, which allows to remotely connect to {{book.project.n
 Example steps for enable SSH authentication:
 
 * In  {{book.project.name}} you need to create client (assume it's called `ssh-jmx-admin-client`), which will be used for SSH authentication.
-This client needs to have switch `Direct grant enabled` to true.
+This client needs to have switch `Direct Access Grants Enabled` to `On`.
 
 * You need to update/specify this property in file `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`:
 
@@ -22,6 +22,7 @@ sshRealm=keycloak
 ----
 
 * Add file `$FUSE_HOME/etc/keycloak-direct-access.json` with the content similar to this (change based on your environment and {{book.project.name}} client settings):
+
 [source,json]
 ----
 {
@@ -37,7 +38,7 @@ sshRealm=keycloak
 This file contains configuration of the client application, which is used by JAAS DirectAccessGrantsLoginModule from `keycloak` JAAS realm for SSH authentication.
 
 * Start Fuse and install `keycloak` JAAS realm into Fuse. This could be done easily by installing `keycloak-jaas` feature, which has JAAS realm predefined
-(you are able to override it by using your own `keycloak` JAAS realm with higher ranking). Use those commands in Fuse terminal:
+(you are able to override it by using your own `keycloak` JAAS realm with higher ranking. See JBoss Fuse documentation for more details). Use those commands in Fuse terminal:
 
 [source, subs="attributes"]
 ----
@@ -51,13 +52,20 @@ features:install keycloak-jaas
 ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
 ```
 
-And login with password `password`. Note that your user needs to have realm role `admin` . The required roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`
+And login with password `password`.
+
+NOTE: On some newer operating systems, you may also need to use this option of SSH command `-o HostKeyAlgorithms=+ssh-dss` because newer SSH clients
+don't allow to use `ssh-dss` algorithm by default, but it's currently used by default in {{book.fuseVersion}} .
+
+
+Note that your user needs to have realm role `admin` if he wants to do everything or some other roles to be able to do just subset of operations
+(eg. role `viewer` to be able to run just read-only Karaf commands) . The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties` .
 
 
 ====== JMX authentication
 
 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 hawt.io by default.
+be better to use just hawt.io/jolokia as jolokia agent is installed in hawt.io by default. See <<fake/../hawtio.adoc#_hawtio,Hawtio Admin Console>> section for more details.
 
 * In file `$FUSE_HOME/etc/org.apache.karaf.management.cfg` you can change this property:
 
@@ -76,12 +84,3 @@ service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root
 ----
 
 and credentials: admin/password (based on the user with admin privileges according to your environment)
-
-Note again that users without `admin` role are not able to login as they are not authorized. However users with access to Hawt.io admin console
-may be still able to access MBeans remotely via HTTP (Hawtio). So make sure to protect Hawt.io web console with same roles like JMX through RMI to
-really protect JMX mbeans.
-
-
-====== 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 {{book.project.name}}.

topics/oidc/java/fuse/hawtio.adoc

@@ -0,0 +1,129 @@
+
+[[_hawtio]]
+===== Secure Hawtio Admin Console
+
+The steps to secure Hawtio Admin Console with {{book.project.name}} are:
+
+* Add these properties to the file `$FUSE_HOME/etc/system.properties` :
+
+[source]
+----
+hawtio.keycloakEnabled=true
+hawtio.realm=keycloak
+hawtio.keycloakClientConfig=${karaf.base}/etc/keycloak-hawtio-client.json
+hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal
+----
+
+* Create client in {{book.project.name}} admin console in your realm. Assuming you have {{book.project.name}} realm `demo` and you created client `hawtio-client`, which is marked
+with `public` Access Type and has redirect URI pointing to Hawtio -  http://localhost:8181/hawtio/* .
+
+* Create file `keycloak-hawtio-client.json` in the directory `$FUSE_HOME/etc` and use the content like this (Change properties `realm`, `resource` and `auth-server-url` according to
+your {{book.project.name}} environment. The property `resource` should point to the client created in previous step. This file is used by the client (Hawtio Javascript application) side.
+
+[source,json]
+----
+{
+  "realm" : "demo",
+  "resource" : "hawtio-client",
+  "auth-server-url" : "http://localhost:8080/auth",
+  "ssl-required" : "external",
+  "public-client" : true
+}
+----
+
+* Create file `keycloak-hawtio.json` in the directory `$FUSE_HOME/etc` and use the content like this (Change properties `realm` and `auth-server-url` according to
+your {{book.project.name}} environment. This file is used by the adapters on server (JAAS Login module) side.
+
+
+[source,json]
+----
+{
+  "realm" : "demo",
+  "resource" : "jaas",
+  "bearer-only" : true,
+  "auth-server-url" : "http://localhost:8080/auth",
+  "ssl-required" : "external",
+  "use-resource-role-mappings": false,
+  "principal-attribute": "preferred_username"
+}
+----
+
+* Start {{book.fuseVersion}} and install feature `keycloak` if you didn't already. The commands in Karaf terminal are like:
+
+
+[source, subs="attributes"]
+----
+features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.version}}/xml/features
+features:install keycloak
+----
+
+* Go to http://localhost:8181/hawtio and login as some user from your {{book.project.name}} realm. See file `$FUSE_HOME/etc/system.properties` and property `hawtio.roles` .
+Just those with some of the role are able to successfully authenticate to Hawtio and do something here.
+
+
+====== Secure Hawtio on EAP
+
+This subsection contains needed steps for the case, when you want to run Hawtio on the Wildfly 10 server.
+
+* Setup {{book.project.name}} similarly like mentioned above in the section for securing Hawtion on JBoss Fuse. So assuming you have {{book.project.name}} realm `demo`
+and client `hawtio-client`. Assumption is that your {{book.project.name}} is running on `localhost:8080` when the Wildfly with deployed hawtio will be running on `localhost:8181`.
+
+* Copy `hawtio.war` to the `$WILDFLY_HOME/standalone/configuration` directory. See Hawtio/Fuse documentation for more details about the Hawtio deployment.
+
+* Copy files `keycloak-hawtio.json` and `keycloak-hawtio-client.json` with the above content to the `$WILDFLY_HOME/standalone/configuration` directory.
+
+* Install {{book.project.name}} adapter subsystem to your Wildfly as described in the <<fake/../../jboss-adapter.adoc#_jboss_adapter,JBoss adapter documentation>>
+
+* In `$WILDFLY_HOME/standalone/configuration/standalone.xml` configure system properties like this:
+
+[source,xml]
+----
+<extensions>
+...
+</extensions>
+
+<system-properties>
+    <property name="hawtio.authenticationEnabled" value="true" />
+    <property name="hawtio.realm" value="hawtio" />
+    <property name="hawtio.roles" value="admin,viewer" />
+    <property name="hawtio.rolePrincipalClasses" value="org.keycloak.adapters.jaas.RolePrincipal" />
+    <property name="hawtio.keycloakEnabled" value="true" />
+    <property name="hawtio.keycloakClientConfig" value="${jboss.server.config.dir}/keycloak-hawtio-client.json" />
+    <property name="hawtio.keycloakServerConfig" value="${jboss.server.config.dir}/keycloak-hawtio.json" />
+</system-properties>
+----
+
+Also add hawtio realm to this file to the `security-domains` section:
+
+[source,xml]
+----
+<security-domain name="hawtio" cache-type="default">
+    <authentication>
+        <login-module code="org.keycloak.adapters.jaas.BearerTokenLoginModule" flag="required">
+            <module-option name="keycloak-config-file" value="${hawtio.keycloakServerConfig}"/>
+        </login-module>
+    </authentication>
+</security-domain>
+----
+
+Finally add the `secure-deployment` section `hawtio` to the adapter subsystem. It should ensure that Hawtio WAR is able to find the JAAS login module classes.
+
+
+[source,xml]
+----
+<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
+    <secure-deployment name="hawtio.war" />
+</subsystem>
+----
+
+* Restart Wildfly server with Hawtio
+
+[source,xml]
+----
+cd $WILDFLY_HOME/bin
+./standalone.sh -Djboss.socket.binding.port-offset=101
+----
+
+* Access Hawtio on http://localhost:8181/hawtio . It will be secured by the {{book.project.name}} .
+
+

topics/oidc/java/fuse/install-feature.adoc

@@ -29,7 +29,7 @@ org.ops4j.pax.url.mvn.repositories= \
 ----
 {% endif %}
 
-You need to start JBoss Fuse and then in the Karaf terminal you type this:
+You need to start {{book.fuseVersion}} and then in the Karaf terminal you type this:
 
 [source]
 ----
@@ -37,20 +37,16 @@ features:addurl mvn:org.keycloak/keycloak-osgi-features/{{book.project.versionMv
 features:install keycloak
 ----
 
-Then in JBoss Fuse 6.2 you may need to install Jetty 8 feature:
+Then you may need to install Jetty 9 feature:
-
-[source]
-----
-features:install keycloak-jetty8-adapter
-----
-
-Or in JBoss Fuse 6.3 you may need to install Jetty 9 feature:
 
 [source]
 ----
 features:install keycloak-jetty9-adapter
 ----
 
+NOTE: If you are on JBoss Fuse 6.2 or older, you should use `keycloak-jetty8-adapter` . However it's highly recommended to
+rather upgrade to {{book.fuseVersion}} instead.
+
 Then you can check that requested features were installed:
 
 [source]
@@ -61,11 +57,11 @@ features:list | grep keycloak
 ====== Install from ZIP bundle
 
 This is useful if you are offline and/or don't want to use maven for download jar files and other artifacts. Once you download ZIP bundle of {{book.project.name}} Fuse adapter,
-you will need to unzip it into the root directory of JBoss Fuse. This should install the dependencies under the `system` directory. For example see this for Fuse 6.2.1 :
+you will need to unzip it into the root directory of JBoss Fuse. This should install the dependencies under the `system` directory. Use this for {{book.fuseVersion}} :
 
 [source]
 ----
-cd /path-to-fuse/jboss-fuse-6.2.1.redhat-084
+cd /path-to-fuse/jboss-fuse-6.3.0.redhat-198
 unzip -q /path-to-adapter-zip/keycloak-fuse-adapter-dist-{{book.project.versionMvn}}.zip
 ----
 

topics/oidc/java/fuse/servlet-whiteboard.adoc

@@ -10,6 +10,7 @@ The needed steps to secure your servlet with {{book.project.name}} are:
 * {{book.project.name}} provides PaxWebIntegrationService, which allows to inject jetty-web.xml and configure security constraints for your application.
   You need to declare such service in `OSGI-INF/blueprint/blueprint.xml` inside your application. Note that your servlet needs to depend on it.
   The example configuration can look like this:
+
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>