From 0697a34bc075345aa42785169ba1c30cba3ed613 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hynek=20Mlna=C5=99=C3=ADk?= Date: Tue, 12 Jun 2018 09:49:39 +0200 Subject: [PATCH] KEYCLOAK-7413 Fuse 7 documentation (#401) --- securing_apps/topics.adoc | 9 ++ .../topics/oidc/java/fuse-adapter.adoc | 15 ++- .../topics/oidc/java/fuse7-adapter.adoc | 36 ++++++ .../topics/oidc/java/fuse7/camel.adoc | 103 ++++++++++++++++++ .../topics/oidc/java/fuse7/classic-war.adoc | 90 +++++++++++++++ .../topics/oidc/java/fuse7/cxf-builtin.adoc | 82 ++++++++++++++ .../topics/oidc/java/fuse7/cxf-separate.adoc | 69 ++++++++++++ .../topics/oidc/java/fuse7/fuse-admin.adoc | 83 ++++++++++++++ .../topics/oidc/java/fuse7/hawtio.adoc | 66 +++++++++++ .../oidc/java/fuse7/install-feature.adoc | 84 ++++++++++++++ .../oidc/java/fuse7/servlet-whiteboard.adoc | 55 ++++++++++ .../document-attributes-community.adoc | 2 + .../document-attributes-product.adoc | 2 + 13 files changed, 688 insertions(+), 8 deletions(-) create mode 100644 securing_apps/topics/oidc/java/fuse7-adapter.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/camel.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/classic-war.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/cxf-builtin.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/cxf-separate.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/fuse-admin.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/hawtio.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/install-feature.adoc create mode 100644 securing_apps/topics/oidc/java/fuse7/servlet-whiteboard.adoc diff --git a/securing_apps/topics.adoc b/securing_apps/topics.adoc index 60096e7187..1761fec891 100644 --- a/securing_apps/topics.adoc +++ b/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[] diff --git a/securing_apps/topics/oidc/java/fuse-adapter.adoc b/securing_apps/topics/oidc/java/fuse-adapter.adoc index 50d9564332..3e2c90a418 100644 --- a/securing_apps/topics/oidc/java/fuse-adapter.adoc +++ b/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 -understanding the demo. -endif::[] \ No newline at end of file +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::[] diff --git a/securing_apps/topics/oidc/java/fuse7-adapter.adoc b/securing_apps/topics/oidc/java/fuse7-adapter.adoc new file mode 100644 index 0000000000..fcf22929ac --- /dev/null +++ b/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::[] diff --git a/securing_apps/topics/oidc/java/fuse7/camel.adoc b/securing_apps/topics/oidc/java/fuse7/camel.adoc new file mode 100644 index 0000000000..a5d15c82f7 --- /dev/null +++ b/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] +---- + + + + + + + + + + + + + + + + + + + + +---- + + +* 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] +---- + + + + + + + + + + Hello rest service + + Just a hello + + + + + + + + + + + (__This second sentence is returned from a Camel RestDSL endpoint__) + + + + + +---- diff --git a/securing_apps/topics/oidc/java/fuse7/classic-war.adoc b/securing_apps/topics/oidc/java/fuse7/classic-war.adoc new file mode 100644 index 0000000000..6eb0672994 --- /dev/null +++ b/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 element +* login configuration in the element. Make sure that the `` is `KEYCLOAK`. +* security roles in the element ++ +For example: ++ +[source,xml] +---- + + + + customer-portal + + + index.html + + + + + Customers + /customers/* + + + user + + + + + KEYCLOAK + does-not-matter + + + + admin + + + user + + +---- + +. 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] +---- + + keycloak.config.resolver + org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver + +---- + +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 `-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. + diff --git a/securing_apps/topics/oidc/java/fuse7/cxf-builtin.adoc b/securing_apps/topics/oidc/java/fuse7/cxf-builtin.adoc new file mode 100644 index 0000000000..89ee70349c --- /dev/null +++ b/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] +---- + + + + + + + + + + + + + + + + + + + + + + + user + + + + + + + + + + + + + + + + + + + + + + + +---- + +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}", +---- diff --git a/securing_apps/topics/oidc/java/fuse7/cxf-separate.adoc b/securing_apps/topics/oidc/java/fuse7/cxf-separate.adoc new file mode 100644 index 0000000000..c0605f7b93 --- /dev/null +++ b/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] +---- + + + + + + + + + + + + + + + + + + + + +---- ++ +For the CXF JAX-RS application, the only difference might be in the configuration of the endpoint dependent on engine-factory: ++ +[source,xml] +---- + + + + + +---- + + +. 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}" +---- diff --git a/securing_apps/topics/oidc/java/fuse7/fuse-admin.adoc b/securing_apps/topics/oidc/java/fuse7/fuse-admin.adoc new file mode 100644 index 0000000000..edfafec120 --- /dev/null +++ b/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). diff --git a/securing_apps/topics/oidc/java/fuse7/hawtio.adoc b/securing_apps/topics/oidc/java/fuse7/hawtio.adoc new file mode 100644 index 0000000000..1af9ee80a1 --- /dev/null +++ b/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`. + diff --git a/securing_apps/topics/oidc/java/fuse7/install-feature.adoc b/securing_apps/topics/oidc/java/fuse7/install-feature.adoc new file mode 100644 index 0000000000..43335dcae3 --- /dev/null +++ b/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. + diff --git a/securing_apps/topics/oidc/java/fuse7/servlet-whiteboard.adoc b/securing_apps/topics/oidc/java/fuse7/servlet-whiteboard.adoc new file mode 100644 index 0000000000..b51ac01b68 --- /dev/null +++ b/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] +---- + + + + + + + user + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +* 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. diff --git a/topics/templates/document-attributes-community.adoc b/topics/templates/document-attributes-community.adoc index 8c5b507e66..cad53f3f56 100644 --- a/topics/templates/document-attributes-community.adoc +++ b/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 diff --git a/topics/templates/document-attributes-product.adoc b/topics/templates/document-attributes-product.adoc index 8cc7bdb83d..9cae860b2b 100644 --- a/topics/templates/document-attributes-product.adoc +++ b/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