Merge pull request #52 from mposolda/master
KEYCLOAK-3956 Update fuse documentation. Added docs for Hawtio
This commit is contained in:
Marek Posolda
GitHub
commit
5810dda1a5
9 changed files with 180 additions and 28 deletions
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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` .
|
||||
|
||||
|
|
|
|||
|
|
@ -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}}.
|
||||
129
topics/oidc/java/fuse/hawtio.adoc
Normal file
129
topics/oidc/java/fuse/hawtio.adoc
Normal file
|
|
@ -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}} .
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
----
|
||||
|
||||
|
|
|
|||
|
|
@ -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"?>
|
||||
|
|
|
|||
Loading…
Reference in a new issue