KEYCLOAK-7413 Fuse 7 documentation (#401)

securing_apps/topics.adoc

@@ -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/fuse-admin.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[]
 ifeval::[{project_community}==true]
 include::topics/oidc/java/tomcat-adapter.adoc[]

securing_apps/topics/oidc/java/fuse-adapter.adoc

@@ -1,15 +1,15 @@
 
 [[_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]
-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.
 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:
 
@@ -21,12 +21,11 @@ Security for the following items is supported for Fuse:
 * SSH and JMX admin access
 * 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.
 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]
-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::[]

securing_apps/topics/oidc/java/fuse7-adapter.adoc

@@ -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::[]

securing_apps/topics/oidc/java/fuse7/camel.adoc

@@ -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>
+
+----

securing_apps/topics/oidc/java/fuse7/classic-war.adoc

@@ -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.
+

securing_apps/topics/oidc/java/fuse7/cxf-builtin.adoc

@@ -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}",
+----

securing_apps/topics/oidc/java/fuse7/cxf-separate.adoc

@@ -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}"
+----

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

@@ -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).

securing_apps/topics/oidc/java/fuse7/hawtio.adoc

@@ -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`.
+

securing_apps/topics/oidc/java/fuse7/install-feature.adoc

@@ -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.
+

securing_apps/topics/oidc/java/fuse7/servlet-whiteboard.adoc

@@ -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.

topics/templates/document-attributes-community.adoc

@@ -87,5 +87,7 @@
 :fuseHawtioEAPVersion: JBoss EAP 6.4
 :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
 :saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_9.xsd

topics/templates/document-attributes-product.adoc

@@ -103,5 +103,7 @@ endif::[]
 :fuseHawtioEAPVersion: JBoss EAP 6.4
 :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
 :saml_adapter_xsd_urn: https://www.keycloak.org/schema/keycloak_saml_adapter_1_9.xsd