Documentation for fuse adapter and example
This commit is contained in:
mposolda
parent
d928c26e27
commit
aacbdf5748
4 changed files with 155 additions and 3 deletions
|
|
@ -14,6 +14,7 @@
|
||||||
<!ENTITY TomcatAdapter SYSTEM "modules/tomcat-adapter.xml">
|
<!ENTITY TomcatAdapter SYSTEM "modules/tomcat-adapter.xml">
|
||||||
<!ENTITY Jetty9Adapter SYSTEM "modules/jetty9-adapter.xml">
|
<!ENTITY Jetty9Adapter SYSTEM "modules/jetty9-adapter.xml">
|
||||||
<!ENTITY Jetty8Adapter SYSTEM "modules/jetty8-adapter.xml">
|
<!ENTITY Jetty8Adapter SYSTEM "modules/jetty8-adapter.xml">
|
||||||
|
<!ENTITY FuseAdapter SYSTEM "modules/fuse-adapter.xml">
|
||||||
<!ENTITY InstalledApplications SYSTEM "modules/installed-applications.xml">
|
<!ENTITY InstalledApplications SYSTEM "modules/installed-applications.xml">
|
||||||
<!ENTITY Logout SYSTEM "modules/logout.xml">
|
<!ENTITY Logout SYSTEM "modules/logout.xml">
|
||||||
<!ENTITY SAML SYSTEM "modules/saml.xml">
|
<!ENTITY SAML SYSTEM "modules/saml.xml">
|
||||||
|
|
@ -91,6 +92,7 @@ This one is short
|
||||||
&TomcatAdapter;
|
&TomcatAdapter;
|
||||||
&Jetty9Adapter;
|
&Jetty9Adapter;
|
||||||
&Jetty8Adapter;
|
&Jetty8Adapter;
|
||||||
|
&FuseAdapter;
|
||||||
&JavascriptAdapter;
|
&JavascriptAdapter;
|
||||||
&InstalledApplications;
|
&InstalledApplications;
|
||||||
&Logout;
|
&Logout;
|
||||||
|
|
|
||||||
41
docbook/reference/en/en-US/modules/fuse-adapter.xml
Normal file
41
docbook/reference/en/en-US/modules/fuse-adapter.xml
Normal file
|
|
@ -0,0 +1,41 @@
|
||||||
|
<section id="fuse-adapter">
|
||||||
|
<title>JBoss Fuse and Apache Karaf Adapter</title>
|
||||||
|
<para>
|
||||||
|
Currently Keycloak supports securing your web applications running inside <ulink url="http://www.jboss.org/products/fuse/overview/">JBoss Fuse</ulink>
|
||||||
|
or <ulink url="http://karaf.apache.org/">Apache Karaf</ulink> . It leverages <link linkend="jetty8-adapter">Jetty 8 adapter</link> as both JBoss Fuse 6.1
|
||||||
|
and Apache Karaf 3 are bundled with <ulink url="http://eclipse.org/jetty/">Jetty 8.1 server</ulink> under the covers and Jetty is used for running various kinds of web applications.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
What is supported for Fuse/Karaf is:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Security for classic WAR applications deployed on Fuse/Karaf with <ulink url="https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War">Pax Web War Extender</ulink>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Security for servlets deployed on Fuse/Karaf as OSGI services with <ulink url="https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard">Pax Web Whiteboard Extender</ulink>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Security for <ulink url="http://camel.apache.org/">Apache Camel</ulink> Jetty endpoints running with
|
||||||
|
<ulink url="http://camel.apache.org/jetty.html">Camel Jetty</ulink> component.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Security for <ulink url="http://cxf.apache.org/">Apache CXF</ulink> endpoints running on their own separate
|
||||||
|
<ulink url="http://cxf.apache.org/docs/jetty-configuration.html">Jetty engine</ulink>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Security for <ulink url="http://cxf.apache.org/">Apache CXF</ulink> endpoints running on default engine provided by CXF servlet.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>The best place to start is look at Fuse demo bundled as part of Keycloak examples in directory <literal>examples/fuse</literal> .</para>
|
||||||
|
</section>
|
||||||
|
|
@ -58,3 +58,13 @@ Multi tenancy
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
A complete application, showing how to achieve multi tenancy of web applications by using one realm per account. For more information look at `multi-tenant/README.md`
|
A complete application, showing how to achieve multi tenancy of web applications by using one realm per account. For more information look at `multi-tenant/README.md`
|
||||||
|
|
||||||
|
Basic authentication
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Example REST application configured to support both basic authentication with username/password as well as authentication with bearer token. For more information look at `basic-auth/README.md`
|
||||||
|
|
||||||
|
Fuse
|
||||||
|
----
|
||||||
|
|
||||||
|
This is set of demo applications, showing how to secure your own web applications running inside OSGI environment in JBoss Fuse or Apache Karaf. Fore more information look at `fuse/README.md`
|
||||||
|
|
|
||||||
|
|
@ -1,17 +1,80 @@
|
||||||
1) First step is to run Keycloak server on localhost:8080 and import realm "demo" from the file testrealm.json in this directory (Directory "fuse").
|
Keycloak Fuse demo
|
||||||
|
==================
|
||||||
|
|
||||||
Running example on Karaf 3.0.2
|
Currently Keycloak supports securing your web applications running inside [JBoss Fuse](http://www.jboss.org/products/fuse/overview/) or [Apache Karaf](http://karaf.apache.org/). It leverages Jetty8 adapter
|
||||||
------------------------------
|
as both JBoss Fuse 6.1 and Apache Karaf 3 are bundled with [Jetty8](http://eclipse.org/jetty/) server under the covers and Jetty is used for running various kinds of web applications.
|
||||||
|
|
||||||
|
The Fuse example is slightly modified version of Keycloak base demo applications. The main difference among base demo is that for Fuse demo
|
||||||
|
are applications running on separate Fuse/Karaf server. Keycloak server is supposed to run separately on Wildfly 8 or JBoss EAP 6.3.
|
||||||
|
|
||||||
|
What is supported for Fuse/Karaf is:
|
||||||
|
* Security for classic WAR applications deployed on Fuse/Karaf with [pax-war extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War).
|
||||||
|
* Security for servlets deployed on Fuse/Karaf as OSGI services with [pax-whiteboard extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard).
|
||||||
|
* Security for [Apache Camel](http://camel.apache.org/) Jetty endpoints running with [camel-jetty](http://camel.apache.org/jetty.html) component.
|
||||||
|
* Security for [Apache CXF](http://cxf.apache.org/) endpoints running on their own separate [Jetty engine](http://cxf.apache.org/docs/jetty-configuration.html).
|
||||||
|
Supports both securing JAX-RS and JAX-WS endpoints.
|
||||||
|
* Security for [Apache CXF](http://cxf.apache.org/) endpoints running on default engine provided by CXF servlet on [http://localhost:8181/cxf](http://localhost:8181/cxf)
|
||||||
|
|
||||||
|
Fuse demo contains those basic applications:
|
||||||
|
* **customer-app-fuse** A WAR application that is deployed with [pax-war extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War)
|
||||||
|
* **product-app-fuse** A servlet application deployed with [pax-whiteboard extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard)
|
||||||
|
* **cxf-jaxws** [Apache CXF](http://cxf.apache.org/) JAX-WS endpoint running on separate Jetty engine on [http://localhost:8282/PersonServiceCF](http://localhost:8282/PersonServiceCF).
|
||||||
|
The product-app-fuse invokes the endpoint to get data.
|
||||||
|
* **camel** [Apache Camel](http://camel.apache.org/) endpoint running on separate Jetty engine on [http://localhost:8383/admin-camel-endpoint](http://localhost:8383/admin-camel-endpoint).
|
||||||
|
The customer-app-fuse invokes the endpoint to get data.
|
||||||
|
* **cxf-jaxrs** [Apache CXF](http://cxf.apache.org/) JAX-RS endpoint running on default Jetty on [http://localhost:8181/cxf/customerservice](http://localhost:8181/cxf/customerservice).
|
||||||
|
The customer-app-fuse invokes the endpoint to get data
|
||||||
|
|
||||||
|
Running of demo consists of 2 steps. First you need to run separate Keycloak server and then Fuse/Karaf server with the applications
|
||||||
|
|
||||||
|
Base steps
|
||||||
|
----------
|
||||||
|
|
||||||
|
* Run external instance of Keycloak server on WildFly 8 or JBoss EAP 6.3 . Fuse demo suppose that server is running on [http://localhost:8080/auth](http://localhost:8080/auth)
|
||||||
|
* Import realm `demo` from the file testrealm.json on `examples/fuse/testrealm.json` .
|
||||||
|
* Then build examples, which is needed so the feature repository is added to your local maven repo:
|
||||||
|
|
||||||
|
```
|
||||||
|
cd examples/fuse
|
||||||
|
mvn clean install
|
||||||
|
```
|
||||||
|
|
||||||
|
Run demo applications on Apache Karaf 3.0.2
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
Demo is using Apache camel and Apache CXF, which are not in standalone Karaf by default. So you will need to install feature repositories for both of them.
|
||||||
|
Next step is to add feature repository for main set of Keycloak karaf features and for the demo. Once all feature URLs are added, you just need to install `keycloak-fuse-example` feature,
|
||||||
|
which automatically installs all other needed stuff.
|
||||||
|
|
||||||
|
Once you run Apache Karaf, you need to run these commands from Karaf console (Make sure to replace keycloak versions in the example with actual Keycloak version):
|
||||||
|
|
||||||
|
```
|
||||||
feature:repo-add mvn:org.apache.camel.karaf/apache-camel/2.12.5/xml/features
|
feature:repo-add mvn:org.apache.camel.karaf/apache-camel/2.12.5/xml/features
|
||||||
feature:repo-add mvn:org.apache.cxf.karaf/apache-cxf/2.7.14/xml/features
|
feature:repo-add mvn:org.apache.cxf.karaf/apache-cxf/2.7.14/xml/features
|
||||||
feature:repo-add mvn:org.keycloak/keycloak-osgi-features/1.1.0.Final/xml/features
|
feature:repo-add mvn:org.keycloak/keycloak-osgi-features/1.1.0.Final/xml/features
|
||||||
feature:repo-add mvn:org.keycloak.example.demo/keycloak-fuse-example-features/1.1.0.Final/xml/features
|
feature:repo-add mvn:org.keycloak.example.demo/keycloak-fuse-example-features/1.1.0.Final/xml/features
|
||||||
feature:install keycloak-fuse-example
|
feature:install keycloak-fuse-example
|
||||||
|
```
|
||||||
|
|
||||||
|
After that you can test running on [http://localhost:8080/customer-portal](http://localhost:8080/customer-portal) and login as "bburke@redhat.com" with password "password". Customer-portal is able to
|
||||||
|
receive the response from the endpoints provided by `cxf-jaxrs` and `camel` applications. Note that camel endpoint is available just for users with role `admin`
|
||||||
|
in this demo, so "bburke@redhat.com" can't access it. You may login as "admin" with password "password" in order to invoke camel endpoint.
|
||||||
|
|
||||||
|
From [http://localhost:8080/product-portal](http://localhost:8080/product-portal) you will see servlet endpoint, which invokes JAX-WS provided by `cxf-jaxws` application.
|
||||||
|
|
||||||
|
Note that this demo also secures whole default CXF endpoint on [http://localhost:8181/cxf](http://localhost:8181/cxf) hence every application running under it is secured too.
|
||||||
|
|
||||||
Running example on JBoss Fuse 6.1.0.redhat-379
|
Running example on JBoss Fuse 6.1.0.redhat-379
|
||||||
----------------------------------------------
|
----------------------------------------------
|
||||||
|
|
||||||
|
Securing your applications on JBoss Fuse 6.1 is a bit more tricky. There is bug [https://ops4j1.jira.com/browse/PAXWEB-666](https://ops4j1.jira.com/browse/PAXWEB-666)
|
||||||
|
, which doesn't easily allow to secure default Jetty engine on [http://localhost:8181](http://localhost:8181) as it's not possible to inject
|
||||||
|
custom Jetty authenticator provided by Keycloak Jetty adapter into underlying Jetty server. Hence first step is to upgrade pax-web
|
||||||
|
version from default 3.0.6 to newer 3.1.2 . Then you need to "refresh" cxf feature too. Final step is to install "keycloak-fuse-example" feature.
|
||||||
|
|
||||||
|
All the steps could be performed with these commands in Fuse console (Replace Keycloak versions with the current version number again):
|
||||||
|
|
||||||
|
```
|
||||||
features:uninstall pax-war
|
features:uninstall pax-war
|
||||||
features:uninstall pax-http-whiteboard
|
features:uninstall pax-http-whiteboard
|
||||||
features:uninstall pax-http
|
features:uninstall pax-http
|
||||||
|
|
@ -30,4 +93,40 @@ features:uninstall cxf
|
||||||
features:install cxf
|
features:install cxf
|
||||||
|
|
||||||
features:install keycloak-fuse-example
|
features:install keycloak-fuse-example
|
||||||
|
```
|
||||||
|
|
||||||
|
Now you can test example applications similarly like described for "Karaf" section.
|
||||||
|
|
||||||
|
How to secure your own applications
|
||||||
|
-----------------------------------
|
||||||
|
Most of the steps should be understandable from testing and understanding the demo. Basically all mentioned applications require to
|
||||||
|
inject Keycloak Jetty authenticator into underlying Jetty server . The steps are bit different according to application type.
|
||||||
|
|
||||||
|
**Classic WAR application** - Take a look at `customer-portal-app` for inspiration. The needed steps are:
|
||||||
|
* Declare needed constraints in `/WEB-INF/web.xml`
|
||||||
|
* Add `jetty-web.xml` file with the authenticator to `/WEB-INF/jetty-web.xml` and add `/WEB-INF/keycloak.json` with your Keycloak configuration
|
||||||
|
* Make sure your WAR imports `org.keycloak.adapters.jetty` and maybe some more packages in MANIFEST.MF file in header `Import-Package`. It's
|
||||||
|
recommended to use maven-bundle-plugin similarly like Fuse examples are doing, but note that "*" resolution for package doesn't import `org.keycloak.adapters.jetty` package
|
||||||
|
as it's not used by application or Blueprint or Spring descriptor, but it's used just in jetty-web.xml file.
|
||||||
|
|
||||||
|
**Servlet web application deployed by pax-whiteboard-extender** - Take a look at `product-portal-app` for inspiration. The needed steps are:
|
||||||
|
* Keycloak provides PaxWebIntegrationService, which allows to inject jetty-authenticator.xml and configure security constraints for your application.
|
||||||
|
Example `product-portal-app` declares this in `OSGI-INF/blueprint/blueprint.xml` . Note that your servlet needs to depend on it.
|
||||||
|
* Steps 2,3 are same like for classic WAR
|
||||||
|
|
||||||
|
**Apache camel application** - You can secure your Apache camel endpoint using [camel-jetty](http://camel.apache.org/jetty.html) endpoint by adding securityHandler with KeycloakJettyAuthenticator and
|
||||||
|
proper security constraints injected. Take a look at `OSGI-INF/blueprint/blueprint.xml` configuration in `camel` application on example of how it can be done.
|
||||||
|
|
||||||
|
**Apache CXF endpoint** - It's recommended to run your CXF endpoints secured by Keycloak on separate Jetty engine. Application `cxf-ws` is using separate endpoint on
|
||||||
|
[http://localhost:8282](http://localhost:8282) . All the important configuration is declared in cxf-jaxws app in `META-INF/spring/beans.xml` .
|
||||||
|
|
||||||
|
**Builtin web applications** - Some services automatically come with deployed servlets on startup. One of such examples is CXF servlet running on
|
||||||
|
[http://localhost:8181/cxf](http://localhost:8181/cxf) context. Securing such endpoints is quite tricky. The approach, which Keycloak is currently using,
|
||||||
|
is providing ServletUnregistrationService, which undeploys builtin servlet at startup, so you are able to re-deploy it again on context secured by Keycloak.
|
||||||
|
You can see the `OSGI-INF/blueprint/blueprint.xml` inside `cxf-jaxrs` project, which adds JAX-RS "customerservice" endpoint and more importantly, it secures whole `/cxf` context.
|
||||||
|
|
||||||
|
As a side effect, all other CXF services running on default CXF HTTP destination will be secured too. Once you uninstall feature "keycloak-fuse-example" the
|
||||||
|
original unsecured servlet on `/cxf` context is deployed back and hence context will become unsecured again.
|
||||||
|
|
||||||
|
It's recommended to use your own Jetty engine for your apps (similarly like `cxf-jaxws` application is doing).
|
||||||
|
|
||||||
Loading…
Reference in a new issue