From fba2dd9ac2acf9fac132d70abfb6000e16da454a Mon Sep 17 00:00:00 2001 From: mposolda Date: Thu, 24 Nov 2016 16:48:35 +0100 Subject: [PATCH] KEYCLOAK-3956 Update fuse documentation. Added docs for Hawtio --- SUMMARY.adoc | 1 + book.json | 3 +- topics/oidc/java/fuse-adapter.adoc | 7 +- topics/oidc/java/fuse/camel.adoc | 2 +- topics/oidc/java/fuse/classic-war.adoc | 22 ++- topics/oidc/java/fuse/fuse-admin.adoc | 25 ++-- topics/oidc/java/fuse/hawtio.adoc | 129 ++++++++++++++++++ topics/oidc/java/fuse/install-feature.adoc | 18 +-- topics/oidc/java/fuse/servlet-whiteboard.adoc | 1 + 9 files changed, 180 insertions(+), 28 deletions(-) create mode 100644 topics/oidc/java/fuse/hawtio.adoc diff --git a/SUMMARY.adoc b/SUMMARY.adoc index ba5bd402c1..f228c8d62e 100644 --- a/SUMMARY.adoc +++ b/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] diff --git a/book.json b/book.json index 68d0d08daa..9250dfc76b 100755 --- a/book.json +++ b/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" } } diff --git a/topics/oidc/java/fuse-adapter.adoc b/topics/oidc/java/fuse-adapter.adoc index 9f3258a023..8f2f6bbc7c 100755 --- a/topics/oidc/java/fuse-adapter.adoc +++ b/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 <> as both JBoss Fuse 6.2 are bundled with http://eclipse.org/jetty/[Jetty 8.1 server] +It leverages <> 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 diff --git a/topics/oidc/java/fuse/camel.adoc b/topics/oidc/java/fuse/camel.adoc index 324c912bb7..a22ffcccfc 100644 --- a/topics/oidc/java/fuse/camel.adoc +++ b/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. diff --git a/topics/oidc/java/fuse/classic-war.adoc b/topics/oidc/java/fuse/classic-war.adoc index 56703c1c5c..9f0175cfe3 100644 --- a/topics/oidc/java/fuse/classic-war.adoc +++ b/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 <> section. +in the <> 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] +---- + + keycloak.config.resolver + org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver + +---- + +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 `-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` . + diff --git a/topics/oidc/java/fuse/fuse-admin.adoc b/topics/oidc/java/fuse/fuse-admin.adoc index e90849f598..f31c4d8675 100644 --- a/topics/oidc/java/fuse/fuse-admin.adoc +++ b/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 <> 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}}. \ No newline at end of file diff --git a/topics/oidc/java/fuse/hawtio.adoc b/topics/oidc/java/fuse/hawtio.adoc new file mode 100644 index 0000000000..32694a0130 --- /dev/null +++ b/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 <> + +* In `$WILDFLY_HOME/standalone/configuration/standalone.xml` configure system properties like this: + +[source,xml] +---- + +... + + + + + + + + + + + +---- + +Also add hawtio realm to this file to the `security-domains` section: + +[source,xml] +---- + + + + + + + +---- + +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] +---- + + + +---- + +* 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}} . + + diff --git a/topics/oidc/java/fuse/install-feature.adoc b/topics/oidc/java/fuse/install-feature.adoc index b2353392be..6cb17efab3 100644 --- a/topics/oidc/java/fuse/install-feature.adoc +++ b/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: - -[source] ----- -features:install keycloak-jetty8-adapter ----- - -Or in JBoss Fuse 6.3 you may need to install Jetty 9 feature: +Then 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 ---- diff --git a/topics/oidc/java/fuse/servlet-whiteboard.adoc b/topics/oidc/java/fuse/servlet-whiteboard.adoc index 386cca93ad..a1b8fc43d7 100644 --- a/topics/oidc/java/fuse/servlet-whiteboard.adoc +++ b/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] ----