KEYCLOAK-7413 Fuse 7 documentation (#401)

This commit is contained in:
Hynek Mlnařík 2018-06-12 09:49:39 +02:00 committed by GitHub
parent 692ace2c8d
commit 0697a34bc0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 688 additions and 8 deletions

View file

@ -18,6 +18,15 @@ include::topics/oidc/java/fuse/cxf-separate.adoc[]
include::topics/oidc/java/fuse/cxf-builtin.adoc[] include::topics/oidc/java/fuse/cxf-builtin.adoc[]
include::topics/oidc/java/fuse/fuse-admin.adoc[] include::topics/oidc/java/fuse/fuse-admin.adoc[]
include::topics/oidc/java/fuse/hawtio.adoc[] include::topics/oidc/java/fuse/hawtio.adoc[]
include::topics/oidc/java/fuse7-adapter.adoc[]
include::topics/oidc/java/fuse7/install-feature.adoc[]
include::topics/oidc/java/fuse7/classic-war.adoc[]
include::topics/oidc/java/fuse7/servlet-whiteboard.adoc[]
include::topics/oidc/java/fuse7/camel.adoc[]
include::topics/oidc/java/fuse7/cxf-separate.adoc[]
include::topics/oidc/java/fuse7/cxf-builtin.adoc[]
include::topics/oidc/java/fuse7/fuse-admin.adoc[]
include::topics/oidc/java/fuse7/hawtio.adoc[]
include::topics/oidc/java/spring-boot-adapter.adoc[] include::topics/oidc/java/spring-boot-adapter.adoc[]
ifeval::[{project_community}==true] ifeval::[{project_community}==true]
include::topics/oidc/java/tomcat-adapter.adoc[] include::topics/oidc/java/tomcat-adapter.adoc[]

View file

@ -1,15 +1,15 @@
[[_fuse_adapter]] [[_fuse_adapter]]
==== JBoss Fuse Adapter ==== JBoss Fuse 6 Adapter
Currently {project_name} supports securing your web applications running inside https://developers.redhat.com/products/fuse/overview/[JBoss Fuse]. {project_name} supports securing your web applications running inside https://developers.redhat.com/products/fuse/overview/[JBoss Fuse 6].
ifeval::[{project_community}==true] ifeval::[{project_community}==true]
It leverages <<_jetty9_adapter,Jetty 9 adapter>> as {fuseVersion} is bundled with http://www.eclipse.org/jetty/[Jetty 9.2 server] JBoss Fuse 6 leverages <<_jetty9_adapter,Jetty 9 adapter>> as {fuseVersion} is bundled with http://www.eclipse.org/jetty/[Jetty 9.2 server]
under the covers and Jetty is used for running various kinds of web applications. under the covers and Jetty is used for running various kinds of web applications.
endif::[] endif::[]
WARNING: The only supported version of Fuse is {fuseVersion}. If you use earlier versions of Fuse, it is possible that some functions will not work correctly. In particular, the http://hawt.io[Hawtio] integration will not work with earlier versions of Fuse. WARNING: The only supported version of Fuse 6 is {fuseVersion}. If you use earlier versions of Fuse 6, it is possible that some functions will not work correctly. In particular, the http://hawt.io[Hawtio] integration will not work with earlier versions of Fuse 6.
Security for the following items is supported for Fuse: Security for the following items is supported for Fuse:
@ -21,12 +21,11 @@ Security for the following items is supported for Fuse:
* SSH and JMX admin access * SSH and JMX admin access
* http://hawt.io[Hawtio administration console] * http://hawt.io[Hawtio administration console]
===== Securing Your Web Applications Inside Fuse ===== Securing Your Web Applications Inside Fuse 6
You must first install the {project_name} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure. You must first install the {project_name} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure.
All referenced web applications require injecting the {project_name} Jetty authenticator into the underlying Jetty server. The steps to achieve this depend on the application type. The details are described below. All referenced web applications require injecting the {project_name} Jetty authenticator into the underlying Jetty server. The steps to achieve this depend on the application type. The details are described below.
ifeval::[{project_community}==true] ifeval::[{project_community}==true]
The best place to start is look at Fuse demo bundled as part of {project_name} examples in directory `fuse` . Most of the steps should be understandable from testing and The best place to start is look at Fuse demo bundled as part of {project_name} examples in directory `fuse` . Most of the steps should be understandable from testing and understanding the demo.
understanding the demo.
endif::[] endif::[]

View file

@ -0,0 +1,36 @@
[[_fuse7_adapter]]
==== JBoss Fuse 7 Adapter
{project_name} supports securing your web applications running inside https://developers.redhat.com/products/fuse/overview/[JBoss Fuse 7].
JBoss Fuse 7 leverages Undertow adapter which is essentially the same as
ifeval::[{project_community}==true]
<<_jboss_adapter,EAP 7 / WildFly 10 Adapter>>
endif::[]
ifeval::[{project_product}==true]
<<_jboss_adapter,JBoss EAP 7 Adapter>>
endif::[]
as {fuse7Version} is bundled with http://undertow.io/[Undertow HTTP engine] under the covers and Undertow is used for running various kinds of web applications.
WARNING: The only supported versions of Fuse 7 is {fuse7Version}. If you use earlier versions of Fuse 7, it is possible that some functions will not work correctly. In particular, integration will not work at all for earlier versions of Fuse 7 than 7.0.1.
Security for the following items is supported for Fuse:
* Classic WAR applications deployed on Fuse with Pax Web War Extender
* Servlets deployed on Fuse as OSGI services with Pax Web Whiteboard Extender and additionally servlets registered through
org.osgi.service.http.HttpService#registerServlet() which is standard OSGi Enterprise HTTP Service
* http://camel.apache.org/[Apache Camel] Undertow endpoints running with the http://camel.apache.org/undertow.html[Camel Undertow] component
* http://cxf.apache.org/[Apache CXF] endpoints running on their own separate Undertow engine
* http://cxf.apache.org/[Apache CXF] endpoints running on the default engine provided by the CXF servlet
* SSH and JMX admin access
* http://hawt.io[Hawtio administration console]
===== Securing Your Web Applications Inside Fuse 7
You must first install the {project_name} Karaf feature. Next you will need to perform the steps according to the type of application you want to secure.
All referenced web applications require injecting the {project_name} Undertow authentication mechanism into the underlying web server. The steps to achieve this depend on the application type. The details are described below.
ifeval::[{project_community}==true]
The best place to start is look at Fuse demo bundled as part of {project_name} examples in directory `fuse` . Most of the steps should be understandable from testing and understanding the demo.
endif::[]

View file

@ -0,0 +1,103 @@
[[_fuse7_adapter_camel]]
===== Securing an Apache Camel Application
You can secure Apache Camel endpoints implemented with the http://camel.apache.org/undertow.html[camel-undertow] component by injecting the proper security constraints via blueprint and updating the used component to `undertow-keycloak`. You have to add the `OSGI-INF/blueprint/blueprint.xml` file to your Camel application with a similar configuration as below. The roles and security constraint mappings, and adapter configuration might differ slightly depending on your environment and needs.
Compared to the standard `undertow` component, `undertow-keycloak` component adds two new properties:
- `configResolver` is a bean that supplies {project_name} configuration file to:
- `org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver`: the {project_name} adapter configuration will be looked up inside the bundle and should be stored in `WEB-INF/keycloak.json` file.
- `org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver`: the {project_name} adapter configuration will be looked up as described in <<_fuse7_config_external_adapter,External adapter configuration>>.
- `allowedRoles` is a comma-separated list of roles. User accessing the service has to have at least one role to be permitted the access.
For example:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:camel="http://camel.apache.org/schema/blueprint"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint-2.17.1.xsd">
<bean id="keycloakConfigResolver" class="org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver" >
<property name="bundleContext" ref="blueprintBundleContext" />
</bean>
<bean id="helloProcessor" class="org.keycloak.example.CamelHelloProcessor" />
<camelContext id="blueprintContext"
trace="false"
xmlns="http://camel.apache.org/schema/blueprint">
<route id="httpBridge">
<from uri="undertow-keycloak:http://0.0.0.0:8383/admin-camel-endpoint?matchOnUriPrefix=true&amp;configResolver=#keycloakConfigResolver&amp;allowedRoles=admin" />
<process ref="helloProcessor" />
<log message="The message from camel endpoint contains ${body}"/>
</route>
</camelContext>
</blueprint>
----
* The `Import-Package` in `META-INF/MANIFEST.MF` needs to contain these imports:
[source, subs="attributes"]
----
javax.servlet;version="[3,4)",
javax.servlet.http;version="[3,4)",
javax.net.ssl,
org.apache.camel.*,
org.apache.camel;version="[2.13,3)",
io.undertow.*,
org.keycloak.*;version="{project_versionMvn}",
org.osgi.service.blueprint,
org.osgi.service.blueprint.container
----
===== Camel RestDSL
Camel RestDSL is a Camel feature used to define your REST endpoints in a fluent way. But you must still use specific implementation classes and provide instructions on how to integrate with {project_name}.
The way to configure the integration mechanism depends on the Camel component for which you configure your RestDSL-defined routes.
The following example shows how to configure integration using the `undertow-keycloak` component, with references to some of the beans defined in previous Blueprint example.
[source,xml]
----
<camelContext id="blueprintContext"
trace="false"
xmlns="http://camel.apache.org/schema/blueprint">
<!--the link with Keycloak security handlers happens by using undertow-keycloak component -->
<restConfiguration apiComponent="undertow-keycloak" contextPath="/restdsl" port="8484">
<endpointProperty key="configResolver" value="#keycloakConfigResolver" />
<endpointProperty key="allowedRoles" value="admin,superadmin" />
</restConfiguration>
<rest path="/hello" >
<description>Hello rest service</description>
<get uri="/{id}" outType="java.lang.String">
<description>Just a hello</description>
<to uri="direct:justDirect" />
</get>
</rest>
<route id="justDirect">
<from uri="direct:justDirect"/>
<process ref="helloProcessor" />
<log message="RestDSL correctly invoked ${body}"/>
<setBody>
<constant>(__This second sentence is returned from a Camel RestDSL endpoint__)</constant>
</setBody>
</route>
</camelContext>
----

View file

@ -0,0 +1,90 @@
[[_fuse7_adapter_classic_war]]
===== Securing a Classic WAR Application
The needed steps to secure your WAR application are:
. In the `/WEB-INF/web.xml` file, declare the necessary:
* security constraints in the <security-constraint> element
* login configuration in the <login-config> element. Make sure that the `<auth-method>` is `KEYCLOAK`.
* security roles in the <security-role> element
+
For example:
+
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<module-name>customer-portal</module-name>
<welcome-file-list>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
<security-constraint>
<web-resource-collection>
<web-resource-name>Customers</web-resource-name>
<url-pattern>/customers/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>user</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>KEYCLOAK</auth-method>
<realm-name>does-not-matter</realm-name>
</login-config>
<security-role>
<role-name>admin</role-name>
</security-role>
<security-role>
<role-name>user</role-name>
</security-role>
</web-app>
----
. Within the `/WEB-INF/` directory of your WAR, create a new file, keycloak.json. The format of this configuration file is described in the <<_java_adapter_config,Java Adapters Config>> section. It is also possible to make this file available externally as described in xref:config_external_adapter[Configuring the External Adapter].
+
For example:
+
[source,json]
----
{
"realm": "demo",
"resource": "customer-portal",
"auth-server-url": "http://localhost:8080/auth",
"ssl-required" : "external",
"credentials": {
"secret": "password"
}
}
----
. Contrary to the Fuse 6 adapter, there are no special OSGi imports needed in MANIFEST.MF.
[[_fuse7_config_external_adapter]]
====== Configuring the External Adapter
If you do not want the `keycloak.json` adapter configuration file to be bundled inside your WAR application, but instead made available externally and loaded based on naming conventions, use this configuration method.
To enable the functionality, add this section to your `/WEB_INF/web.xml` file:
[source,xml]
----
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
</context-param>
----
That component uses `keycloak.config` or `karaf.etc` java properties to search for a base folder to locate the configuration.
Then inside one of those folders it searches for a file called `<your_web_context>-keycloak.json`.
So, for example, if your web application has context `my-portal`, then your adapter configuration is loaded from the `$FUSE_HOME/etc/my-portal-keycloak.json` file.

View file

@ -0,0 +1,82 @@
[[_fuse7_adapter_cxf_builtin]]
===== Securing an Apache CXF Endpoint on the Default Jetty Engine
Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Securing such endpoints can be complicated. One approach, which {project_name} is currently using, is `ServletReregistrationService` which undeploys a built-in servlet at startup, enabling you to redeploy it on a context secured by {project_name}.
The configuration file `OSGI-INF/blueprint/blueprint.xml` inside your application might resemble the one below. Note that it adds the JAX-RS `customerservice` endpoint, which is endpoint-specific to your application, but more importantly, secures the entire `/cxf` context.
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd">
<!-- JAXRS Application -->
<bean id="customerBean" class="org.keycloak.example.rs.CxfCustomerService" />
<jaxrs:server id="cxfJaxrsServer" address="/customerservice">
<jaxrs:providers>
<bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
</jaxrs:providers>
<jaxrs:serviceBeans>
<ref component-id="customerBean" />
</jaxrs:serviceBeans>
</jaxrs:server>
<!-- Securing of whole /cxf context by unregister default cxf servlet from paxweb and re-register with applied security constraints -->
<bean id="cxfConstraintMapping" class="org.keycloak.adapters.osgi.PaxWebSecurityConstraintMapping">
<!-- user accessing the servise has to have at least one of the following roles -->
<property name="roles">
<list>
<value>user</value>
</list>
</property>
<property name="url" value="/cxf/*" />
<property name="authentication" value="true"/>
</bean>
<bean id="cxfKeycloakPaxWebIntegration" class="org.keycloak.adapters.osgi.undertow.PaxWebIntegrationService"
init-method="start" destroy-method="stop">
<property name="bundleContext" ref="blueprintBundleContext" />
<property name="constraintMappings">
<list>
<ref component-id="cxfConstraintMapping" />
</list>
</property>
</bean>
<bean id="defaultCxfReregistration" class="org.keycloak.adapters.osgi.ServletReregistrationService" depends-on="cxfKeycloakPaxWebIntegration"
init-method="start" destroy-method="stop">
<property name="bundleContext" ref="blueprintBundleContext" />
<property name="managedServiceReference">
<reference interface="org.osgi.service.cm.ManagedService" filter="(service.pid=org.apache.cxf.osgi)" timeout="5000" />
</property>
</bean>
</blueprint>
----
As a result, all other CXF services running on the default CXF HTTP destination are also secured. Similarly, when the application is undeployed, the entire `/cxf` context becomes unsecured as well. For this reason, use your own undertow engine for your applications as described in <<_fuse7_adapter_cxf_separate,Secure CXF Application on separate Undertow Engine>> since that gives you more control over security for each individual application.
* The `WEB-INF` directory might need to be inside your project (even if your project is not a web application). You might also need to edit the `/WEB-INF/keycloak.json` file similarly to <<_fuse7_adapter_classic_war,Classic WAR application>>.
Note that you do not need the `web.xml` file as the security constraints are declared in the blueprint configuration file.
* The `Import-Package` in `META-INF/MANIFEST.MF` must contain at least these imports:
[source, subs="attributes"]
----
javax.ws.rs;version="[2,3)",
META-INF.cxf;version="[2.7,3.3)",
META-INF.cxf.osgi;version="[2.7,3.3)";resolution:=optional,
org.apache.cxf.transport.http;version="[2.7,3.3)",
org.apache.cxf.*;version="[2.7,3.3)",
com.fasterxml.jackson.jaxrs.json;version="${jackson.version}",
org.keycloak.*;version="${project.version}",
----

View file

@ -0,0 +1,69 @@
[[_fuse7_adapter_cxf_separate]]
===== Securing an Apache CXF Endpoint on a Separate Undertow Engine
To run your CXF endpoints secured by {project_name} on a separate Undertow engine, complete the following steps:
. Add `OSGI-INF/blueprint/blueprint.xml` to your application, and in it, add the proper configuration resolver bean similarly to <<_fuse7_adapter_camel,Camel configuration>>.
In the `httpu:engine-factory` declare `org.keycloak.adapters.osgi.undertow.CxfKeycloakAuthHandler` handler using that camel configuration. The configuration for a CFX JAX-WS application might resemble this one:
+
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"
xmlns:cxf="http://cxf.apache.org/blueprint/core"
xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration".
xsi:schemaLocation="
http://cxf.apache.org/transports/http-undertow/configuration http://cxf.apache.org/schemas/configuration/http-undertow.xsd
http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/blueprint/jaxws.xsd">
<bean id="keycloakConfigResolver" class="org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver" >
<property name="bundleContext" ref="blueprintBundleContext" />
</bean>
<httpu:engine-factory bus="cxf" id="kc-cxf-endpoint">
<httpu:engine port="8282">
<httpu:handlers>
<bean class="org.keycloak.adapters.osgi.undertow.CxfKeycloakAuthHandler">
<property name="configResolver" ref="keycloakConfigResolver" />
</bean>
</httpu:handlers>
</httpu:engine>
</httpu:engine-factory>
<jaxws:endpoint implementor="org.keycloak.example.ws.ProductImpl"
address="http://localhost:8282/ProductServiceCF" depends-on="kc-cxf-endpoint"/>
</blueprint>
----
+
For the CXF JAX-RS application, the only difference might be in the configuration of the endpoint dependent on engine-factory:
+
[source,xml]
----
<jaxrs:server serviceClass="org.keycloak.example.rs.CustomerService" address="http://localhost:8282/rest"
depends-on="kc-cxf-endpoint">
<jaxrs:providers>
<bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
</jaxrs:providers>
</jaxrs:server>
----
. The `Import-Package` in `META-INF/MANIFEST.MF` must contain those imports:
[source, subs="attributes"]
----
META-INF.cxf;version="[2.7,3.3)",
META-INF.cxf.osgi;version="[2.7,3.3)";resolution:=optional,
org.apache.cxf.bus;version="[2.7,3.3)",
org.apache.cxf.bus.spring;version="[2.7,3.3)",
org.apache.cxf.bus.resource;version="[2.7,3.3)",
org.apache.cxf.transport.http;version="[2.7,3.3)",
org.apache.cxf.*;version="[2.7,3.3)",
org.springframework.beans.factory.config,
org.keycloak.*;version="{project_versionMvn}"
----

View file

@ -0,0 +1,83 @@
[[_fuse7_adapter_admin]]
===== Securing Fuse Administration Services
====== Using SSH Authentication to Fuse Terminal
{project_name} mainly addresses use cases for authentication of web applications; however, if your other web services and applications are protected
with {project_name}, protecting non-web administration services such as SSH with {project_name} credentials is a best pracrice. You can do this using the JAAS login module, which allows remote connection to {project_name} and verifies credentials based on
<<_resource_owner_password_credentials_flow,Resource Owner Password Credentials>>.
To enable SSH authentication, complete the following steps:
. In {project_name} create a client (for example, `ssh-jmx-admin-client`), which will be used for SSH authentication.
This client needs to have `Direct Access Grants Enabled` selected to `On`.
. In the `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` file, update or specify this property:
+
[source]
----
sshRealm=keycloak
----
. Add the `$FUSE_HOME/etc/keycloak-direct-access.json` file with content similar to the following (based on your environment and {project_name} client settings):
+
[source,json]
----
{
"realm": "demo",
"resource": "ssh-jmx-admin-client",
"ssl-required" : "external",
"auth-server-url" : "http://localhost:8080/auth",
"credentials": {
"secret": "password"
}
}
----
This file specifies the client application configuration, which is used by JAAS DirectAccessGrantsLoginModule from the `keycloak` JAAS realm for SSH authentication.
. Start Fuse and install the `keycloak` JAAS realm. The easiest way is to install the `keycloak-jaas` feature, which has the JAAS realm predefined. You can override the feature's predefined realm by using your own `keycloak` JAAS realm with higher ranking. For details see the https://access.redhat.com/documentation/en-us/red_hat_fuse/7.0/html-single/security_guide/#ESBSecureContainer[JBoss Fuse documentation].
+
Use these commands in the Fuse terminal:
+
[source, subs="attributes"]
----
features:addurl mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features
features:install keycloak-jaas
----
. Log in using SSH as `admin` user by typing the following in the terminal:
+
```
ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
```
. Log in with password `password`.
NOTE: On some later operating systems, you might also need to use the SSH command's -o option `-o HostKeyAlgorithms=+ssh-dss` because later SSH clients do not allow use of the `ssh-dss` algorithm, by default. However, by default, it is currently used in {fuse7Version}.
Note that the user needs to have realm role `admin` to perform all operations or another role to perform a subset of operations (for example, the *viewer* role that restricts the user to run only read-only Karaf commands). The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties`.
====== Using JMX Authentication
JMX authentication might be necessary if you want to use jconsole or another external tool to remotely connect to JMX through RMI. Otherwise it might be better to use hawt.io/jolokia, since the jolokia agent is installed in hawt.io by default. For more details see <<_fuse7_hawtio,Hawtio Admin Console>>.
To use JMX authentication, complete the following steps:
. In the `$FUSE_HOME/etc/org.apache.karaf.management.cfg` file, change the jmxRealm property to:
+
[source]
----
jmxRealm=keycloak
----
. Install the `keycloak-jaas` feature and configure the `$FUSE_HOME/etc/keycloak-direct-access.json` file as described in the SSH section above.
. In jconsole you can use a URL such as:
[source]
----
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).

View file

@ -0,0 +1,66 @@
[[_fuse7_hawtio]]
===== Securing the Hawtio Administration Console
To secure the Hawtio Administration Console with {project_name}, complete the following steps:
. Create a client in the {project_name} administration console in your realm. For example, in the {project_name} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, \http://localhost:8181).
. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {project_name} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio JavaScript application) side.
+
[source,json]
----
{
"realm" : "demo",
"clientId" : "hawtio-client",
"url" : "http://localhost:8080/auth",
"ssl-required" : "external",
"public-client" : true
}
----
. Create the `keycloak-direct-access.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm` and `url` properties according to your {project_name} environment. This file is used by JavaScript client.
+
[source,json]
----
{
"realm" : "demo",
"resource" : "ssh-jmx-admin-client",
"auth-server-url" : "http://localhost:8080/auth",
"ssl-required" : "external",
"credentials": {
"secret": "password"
}
}
----
. Create the `keycloak-bearer.json` file in the `$FUSE_HOME/etc` dicrectory using content similar to that shown in the example below. Change the `realm` and `auth-server-url` properties according to your {project_name} environment. This file is used by the adapters on the 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 {fuse7Version}, <<_fuse7_install_feature,install the Keycloak feature>>. Then type in the Karaf terminal:
+
[source,subs="attributes"]
----
system:property hawtio.keycloakEnabled true
system:property hawtio.realm keycloak
system:property hawtio.keycloakClientConfig file://\${karaf.base}/etc/keycloak-hawtio-client.json
system:property hawtio.rolePrincipalClasses org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal
restart io.hawt.hawtio-war
----
. Go to http://localhost:8181/hawtio and log in as a user from your {project_name} realm.
+
Note that the user needs to have the proper realm role to successfully authenticate to Hawtio. The available roles are configured in the `$FUSE_HOME/etc/system.properties` file in `hawtio.roles`.

View file

@ -0,0 +1,84 @@
[[_fuse7_install_feature]]
===== Installing the Keycloak Feature
You must first install the `keycloak-pax-http-undertow` and `keycloak-jaas` features in the JBoss Fuse environment. The `keycloak` feature includes the Fuse adapter and all third-party dependencies. The `keycloak-jaas` contains JAAS module used in realm for SSH and JMX authentication. You can install it either from the Maven repository or from an archive.
====== Installing from the Maven Repository
As a prerequisite, you must be online and have access to the Maven repository.
ifeval::[{project_community}==true]
For community it's sufficient to be online as all the artifacts and 3rd party dependencies should be available in the maven central repository.
endif::[]
ifeval::[{project_product}==true]
For {project_name} you first need to configure a proper Maven repository, so you can install the artifacts. For more information see the
https://access.redhat.com/maven-repository[JBoss Enterprise Maven repository] page.
Assuming the Maven repository is https://maven.repository.redhat.com/ga/, add the following to the `$FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg` file and add the repository to the list of supported repositories. For example:
[source]
----
config:edit org.ops4j.pax.url.mvn
config:property-append org.ops4j.pax.url.mvn.repositories ,https://maven.repository.redhat.com/ga@id=redhat.product.repo
config:update
feature:repo-refresh
----
endif::[]
To install the keycloak feature using the Maven repository, complete the following steps:
. Start {fuse7Version}; then in the Karaf terminal type:
+
[source,subs="attributes"]
----
feature:repo-add mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features
feature:install keycloak-pax-http-undertow keycloak-jaas
----
. You might also need to install the Undertow feature:
+
[source]
----
feature:install pax-http-undertow
----
. Ensure that the features were installed:
[source]
----
feature:list | grep keycloak
----
====== Installing from the ZIP bundle
This is useful if you are offline or do not want to use Maven to obtain the JAR files and other artifacts.
To install the Fuse adapter from the ZIP archive, complete the following steps:
. Download the {project_name} Fuse adapter ZIP archive.
. Unzip it into the root directory of JBoss Fuse. The dependencies are then installed under the `system` directory. You can overwrite all existing jar files.
+
Use this for {fuse7Version}:
+
[source,subs="attributes"]
----
cd /path-to-fuse/jboss-fuse-7.0.z
ifeval::[{project_community}==true]
unzip -q /path-to-adapter-zip/keycloak-fuse-adapter-{project_versionMvn}.zip
endif::[]
ifeval::[{project_product}==true]
unzip -q /path-to-adapter-zip/rh-sso-{project_version}-fuse-adapter.zip
endif::[]
----
. Start Fuse and run these commands in the fuse/karaf terminal:
+
[source,subs="attributes"]
----
feature:repo-add mvn:org.keycloak/keycloak-osgi-features/{project_versionMvn}/xml/features
feature:install keycloak-pax-http-undertow keycloak-jaas
----
. Install the corresponding Undertow adapter. Since the artifacts are available directly in the JBoss Fuse `system` directory, you do not need to use the Maven repository.

View file

@ -0,0 +1,55 @@
[[_fuse7_adapter_servlet_whiteboard]]
===== Securing a Servlet Deployed as an OSGI Service
You can use this method if you have a servlet class inside your OSGI bundled project that is not deployed as a classic WAR application. Fuse uses Pax Web Whiteboard Extender to deploy such servlets as web applications.
To secure your servlet with {project_name}, complete the following steps:
. {project_name} provides `org.keycloak.adapters.osgi.undertow.PaxWebIntegrationService`, which allows configuring authentication method and security constraints for your application. You need to declare such services in the `OSGI-INF/blueprint/blueprint.xml` file inside your application. Note that your servlet needs to depend on it.
An example configuration:
+
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">
<bean id="servletConstraintMapping" class="org.keycloak.adapters.osgi.PaxWebSecurityConstraintMapping">
<property name="roles">
<list>
<value>user</value>
</list>
</property>
<property name="authentication" value="true"/>
<property name="url" value="/product-portal/*"/>
</bean>
<!-- This handles the integration and setting the login-config and security-constraints parameters -->
<bean id="keycloakPaxWebIntegration" class="org.keycloak.adapters.osgi.undertow.PaxWebIntegrationService"
init-method="start" destroy-method="stop">
<property name="bundleContext" ref="blueprintBundleContext" />
<property name="constraintMappings">
<list>
<ref component-id="servletConstraintMapping" />
</list>
</property>
</bean>
<bean id="productServlet" class="org.keycloak.example.ProductPortalServlet" depends-on="keycloakPaxWebIntegration" />
<service ref="productServlet" interface="javax.servlet.Servlet">
<service-properties>
<entry key="alias" value="/product-portal" />
<entry key="servlet-name" value="ProductServlet" />
<entry key="keycloak.config.file" value="/keycloak.json" />
</service-properties>
</service>
</blueprint>
----
* You might need to have the `WEB-INF` directory inside your project (even if your project is not a web application) and create the `/WEB-INF/keycloak.json` file as described in the <<_fuse7_adapter_classic_war,Classic WAR application>> section.
Note you don't need the `web.xml` file as the security-constraints are declared in the blueprint configuration file.
. Contrary to the Fuse 6 adapter, there are no special OSGi imports needed in MANIFEST.MF.

View file

@ -87,5 +87,7 @@
:fuseHawtioEAPVersion: JBoss EAP 6.4 :fuseHawtioEAPVersion: JBoss EAP 6.4
:fuseHawtioWARVersion: hawtio-wildfly-1.4.0.redhat-630254.war :fuseHawtioWARVersion: hawtio-wildfly-1.4.0.redhat-630254.war
:fuse7Version: JBoss Fuse 7.0.1
:subsystem_undertow_xml_urn: urn:jboss:domain:undertow:4.0 :subsystem_undertow_xml_urn: urn:jboss:domain:undertow:4.0
:saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_9.xsd :saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_9.xsd

View file

@ -103,5 +103,7 @@ endif::[]
:fuseHawtioEAPVersion: JBoss EAP 6.4 :fuseHawtioEAPVersion: JBoss EAP 6.4
:fuseHawtioWARVersion: hawtio-wildfly-1.4.0.redhat-630254.war :fuseHawtioWARVersion: hawtio-wildfly-1.4.0.redhat-630254.war
:fuse7Version: JBoss Fuse 7.0.1
:subsystem_undertow_xml_urn: urn:jboss:domain:undertow:4.0 :subsystem_undertow_xml_urn: urn:jboss:domain:undertow:4.0
:saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_9.xsd :saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_9.xsd