libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

KEYCLOAK-3956 Update fuse documentation

Browse source
This commit is contained in:
mposolda 2016-11-24 15:31:06 +01:00
parent 0262b64062
commit 82423db239
5 changed files with 61 additions and 156 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

82
examples/fuse/README.md
View file

@ -2,24 +2,17 @@ Keycloak Fuse demo
==================
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 for both JBoss Fuse 6.2 and Apache Karaf 3, that include [Jetty8](http://eclipse.org/jetty/) server under the covers and Jetty is used for running various kinds of web applications
- Jetty9 adapter for both JBoss Fuse 6.3 and Apache Karaf 4, that include [Jetty9](http://eclipse.org/jetty/) server under the covers and Jetty is used for running various kinds of web applications
- Jetty8 adapter for both JBoss Fuse 6.2 and Apache Karaf 3, that include [Jetty8](http://eclipse.org/jetty/) server under the covers and Jetty is used for running various kinds of web applications
**WARNING:** Running your applications inside standalone Apache Karaf may work, however we are testing just with JBoss Fuse and not with standalone Karaf server.
So if you really want adapter on standalone Karaf server, it's up to you to figure exact steps to have it working.
It's highly recommended to use the JBoss Fuse 6.3.0 Rollup 1 or newer for this tutorial.
**WARNING:** Running your applications inside standalone Apache Karaf may work, however we are testing just with JBoss Fuse 6.3.0 Rollup 1 and not with standalone Karaf server. Also we
did not test with Fuse versions older than 6.3.0 Rollup 1. So if you really want adapter on standalone Karaf server or older Fuse, it's up to you to figure exact steps to have it working.
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 server. Keycloak server is supposed to run separately on Wildfly.
What is supported for Fuse is:
* Security for classic WAR applications deployed on Fuse with [pax-war extender](https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War).
* Security for servlets deployed on Fuse 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) . NOTE: Actually It's better and
more secure to use the separate Jetty Engine instead of the default one. The default engine works fine, but I would recommend the separate one.
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)
@ -29,6 +22,7 @@ The customer-app-fuse invokes the endpoint to get data.
The customer-app-fuse invokes the endpoint to get data
* **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.
* **external-config** A WAR application with external adapter configuration not bundled within the application, but instead in `$FUSE_HOME/etc` directory.
Running of demo consists of 2 steps. First you need to run separate Keycloak server and then Fuse server with the applications
@ -46,15 +40,16 @@ cd keycloak-examples-<VERSION>/fuse
mvn clean install
```
Running demo on JBoss Fuse 6.2.1 or JBoss Fuse 6.2.0
----------------------------------------------------
Running demo on JBoss Fuse 6.3.0 Rollup 1
------------------------------
You just need to download and run JBoss Fuse and then run those commands from the karaf terminal to install the needed features and Keycloak fuse demo (Replace Keycloak versions with the current Keycloak version number):
```
KEYCLOAK_VERSION="2.2.1.Final"
features:addurl mvn:org.keycloak/keycloak-osgi-features/$KEYCLOAK_VERSION/xml/features
features:addurl mvn:org.keycloak.example.demo/keycloak-fuse-example-features/$KEYCLOAK_VERSION/xml/features
features:install keycloak-fuse-6.2-example
features:install keycloak-fuse-6.3-example
```
After that you can test running on [http://localhost:8181/customer-portal](http://localhost:8181/customer-portal) and login as "bburke@redhat.com" with password "password". Customer-portal is able to
@ -65,59 +60,12 @@ From [http://localhost:8181/product-portal](http://localhost:8181/product-portal
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.
To have the `external-config` example running, you can copy the file `examples/fuse/external-config/external-config-keycloak.json` to the `$FUSE_HOME/etc` directory.
Then go to [http://localhost:8181/external-config/index.html](http://localhost:8181/external-config/index.html) to test the secured application.
Running demo on JBoss Fuse 6.3
------------------------------
Similar steps to the instructions for JBoss Fuse 6.2.1 but you need to install a different feature (due to the usage of Jetty9 instead of Jetty8): `keycloak-fuse-6.3-example`
You just need to download and run JBoss Fuse and then run those commands from the karaf terminal to install the needed features and Keycloak fuse demo (Replace Keycloak versions with the current Keycloak version number):
```
KEYCLOAK_VERSION="2.2.1.Final"
features:addurl mvn:org.keycloak/keycloak-osgi-features/$KEYCLOAK_VERSION/xml/features
features:addurl mvn:org.keycloak.example.demo/keycloak-fuse-example-features/$KEYCLOAK_VERSION/xml/features
features:install keycloak-fuse-6.3-example
```
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-web.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 ServletReregistrationService, 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).
How to secure WAR application with external keycloak.json configuration
-----------------------------------------------------------------------
It's possible to secure your WAR application with the `keycloak.json` configuration provided outside of the WAR bundle itself.
See [external-config](external-config/README.md) for more details. This is supported on JBoss Fuse 6.3.
How to secure your own application
----------------------------------
See [Docs](https://keycloak.gitbooks.io/securing-client-applications-guide/content/v/latest/topics/oidc/java/fuse-adapter.html) for more details.
How to secure Fuse admin services

22
examples/fuse/external-config/README.md
View file

@ -1,22 +0,0 @@
Keycloak Example - Externalized keycloak.json
=======================================
The following example was tested on JBoss Fuse 6.3 and shows a way to package an OSGi compatible .war file that does not
include keycloak.json file in the .war archive but that automatically loads it based on a naming convention.
To enable the functionality you need to add this section to your `web.xml`:
```
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
</context-param>
```
That component will use `keycloak.config` or `karaf.etc` java properties to look for a base folder to look for the configuration.
Inside one of those folders it will look for a file called `<your_web_context>-keycloak.json`.
For this example you need to copy the file `external-config-keycloak.json` to your JBoss Fuse `etc/` folder.
Once you have done that and once you added feature `keycloak-fuse-6.3-example` (See [here](../README.md) for more details), you can try to access the endpoint: http://localhost:8181/external-config/index.html

97
examples/fuse/fuse-admin/README.md
View file

@ -1,88 +1,51 @@
How to secure Fuse admin services
=================================
Fuse admin console authentication
Fuse admin console authentication on JBoss Fuse 6.3.0 Rollup 1 or newer
---------------------------------
Fuse admin console is Hawt.io. See [Hawt.io documentation](http://hawt.io/docs/index.html) for more info about how to secure it with keycloak. The demo realm
has users `root` , `john` and `mary`, which you can test in similar way like described in the [Hawt.io README](https://github.com/hawtio/hawtio/blob/master/sample-keycloak-integration/README.md) .
Fuse admin console is Hawt.io. Follow the instructions in [Docs](https://keycloak.gitbooks.io/securing-client-applications-guide/content/v/latest/topics/oidc/java/fuse/hawtio.html) for details on how to integrate it.
WARN: Hawt.io version bundled in JBoss Fuse has Keycloak support from JBoss Fuse 6.3.1 . For JBoss Fuse 6.3.0 or older, if you want Keycloak integration, you need to uninstall the provided Hawt.io
version and replace it with the different one, which has Keycloak support. You can ideally use the Hawt.io community version 1.4.66 or newer.
Example steps:
1) Import `demo` realm as mentioned in [Base steps](../README.md#base-steps) . It contains `hawtio-client` and some example users.
2) Copy files [keycloak-hawtio.json](keycloak-hawtio.json) and [keycloak-hawtio-client.json](keycloak-hawtio-client.json) to the `$FUSE_HOME/etc/` directory.
3) Edit properties in `$FUSE_HOME/etc/system.properties` as described in the documentation pointed above.
3) Run Fuse and install `keycloak` feature in the terminal as described in the documentation pointed above.
4) Test. After going to `http://localhost:8181/hawtio` you can login as any of these users. Password of all the sample users is `password` :
* root - He has role `admin` . He can access to everything in Hawtio
* john - He has role `viewer` . He can access to man functionalities in Hawtio.
* mary - She is not able to successfully authenticate to Hawtio
SSH authentication with keycloak credentials on JBoss Fuse 6.2 or newer
SSH authentication with keycloak credentials on JBoss Fuse 6.3.0 Rollup 1 or newer
-----------------------------------------------------------------------
Keycloak mainly addresses usecases for authentication of web applications, however if your admin services (like fuse admin console) are protected
with Keycloak, it may be good to protect non-web services like SSH with Keycloak credentials too. It's possible to do it by using JAAS login module, which
allows to remotely connect to Keycloak and verify credentials based on [Direct grants](https://keycloak.gitbooks.io/server-adminstration-guide/content/v/2.2/topics/sso-protocols/oidc.html).
Follow the instructions in [Docs](https://keycloak.gitbooks.io/securing-client-applications-guide/content/v/latest/topics/oidc/java/fuse/fuse-admin.html) for details
Example steps for enable SSH authentication:
1) Import 'demo' realm as mentioned in [Base steps](../README.md#base-steps) . It contains client `ssh-jmx-admin-client`, which is used for SSH authentication.
Skip this step if you installed demo already.
1) Import `demo` realm as mentioned in [Base steps](../README.md#base-steps) . It contains `ssh-jmx-admin-client` and some example users.
2) Then you need to update/specify this property in file `$FUSE_HOME/etc/org.apache.karaf.shell.cfg`:
2) Then you need to update/specify this property in file `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` as mentioned in the docs pointed above.
```
sshRealm=keycloak
```
3) Copy file from Keycloak fuse examples [keycloak-direct-access.json](keycloak-direct-access.json) to `$FUSE_HOME/etc/` directory.
3) Copy file from Keycloak fuse examples `keycloak-examples-<VERSION>/fuse/fuse-admin/keycloak-direct-access.json` to `$FUSE_HOME/etc/` directory.
This file contains configuration of the client application, which is used by JAAS DirectAccessGrantsLoginModule from `keycloak` JAAS realm for SSH authentication.
4) Start Fuse and install `keycloak` JAAS realm into Fuse as mentioned in the docs pointed above.
4) Start Fuse and install `keycloak` JAAS realm into Fuse. This could be done easily by installing `keycloak-jaas` feature, which has JAAS realm predefined
(you are able to override it by using your own `keycloak` JAAS realm with higher ranking). As long as you already installed `keycloak-fuse-example` feature as mentioned
in [examples readme](../README.md), you can skip this step as `keycloak-jaas` is installed already. Otherwise use those commands (replace Keycloak version in this command with the current version):
```
features:addurl mvn:org.keycloak/keycloak-osgi-features/2.2.1.Final/xml/features
features:install keycloak-jaas
```
5) Now let's type this from your terminal to login via SSH as `admin` user:
```
ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
```
6) In JBoss Fuse 6.2 you may need to install `ssh` feature as it doesn't seem to be installed here by default.
```
features:install ssh
```
And login with password `password` . Note that other users from "demo" realm like bburke@redhat.com don't have SSH access as they don't have `admin` role.
5) Try to login into SSH as different users with the command shown in the docs pointed above. Password of all the sample users is `password` :
* root - He can run any command in Fuse Karaf SSH terminal
* john - He can run just read-only commands (eg. `features:list` ) but not write command (eg. `features:addurl` ).
* mary - She is not able to successfully authenticate to SSH
JMX authentication with keycloak credentials on JBoss Fuse 6.2 or newer
JMX authentication with keycloak credentials on JBoss Fuse 6.3.0 Rollup 1 or newer
-----------------------------------------------------------------------
This may be needed in case if you really want to use jconsole or other external tool to perform remote connection to JMX through RMI. Otherwise it may
be better to use just hawt.io/jolokia as jolokia agent is installed in hawt.io by default.
1) In file `$FUSE_HOME/etc/org.apache.karaf.management.cfg` you can change this property:
```
jmxRealm=keycloak
```
2) In jconsole you can fill URL like:
```
service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root
```
and credentials: admin/password
Note again that users without `admin` role are not able to login as they are not authorized. However users with access to Hawt.io admin console
may be still able to access MBeans remotely via HTTP (Hawtio). So make sure to protect Hawt.io web console with same roles like JMX through RMI to
really protect JMX mbeans.
For JMX, there is fine grained authorization for JMX access in Fuse 6.2.
Actually if you login as user `admin`, you have very limited privileges without possibility to do much JMX operations as this user has just `admin` role, which is not allowed to do much in JMX.
However if you login as user `jmxadmin` with password `password`, you will have all JMX privileges! This user has composite role `jmxAdmin`, which is mapped to
all possible roles used in JMX authorization files like `etc/jmx.acl.*.cfg` . See karaf documentation for more info about fine grained JMX authorization.
See [Docs](https://keycloak.gitbooks.io/securing-client-applications-guide/content/v/latest/topics/oidc/java/fuse/fuse-admin.html) for details
You can use file [keycloak-direct-access.json](keycloak-direct-access.json) to be copied into `$FUSE_HOME/etc/` as mentioned above in the SSH section. You can
also test with same users.

7
examples/fuse/fuse-admin/keycloak-hawtio-client.json Normal file
View file

@ -0,0 +1,7 @@
{
"realm" : "demo",
"resource" : "hawtio-client",
"auth-server-url" : "http://localhost:8080/auth",
"ssl-required" : "external",
"public-client" : true
}

9
examples/fuse/fuse-admin/keycloak-hawtio.json Normal file
View file

@ -0,0 +1,9 @@
{
"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"
}