From 8dd7e8e2e3eb17ab844c97ecb90bfc6f3034f104 Mon Sep 17 00:00:00 2001
From: Bill Burke <bburke@redhat.com>
Date: Mon, 18 Apr 2016 15:15:28 -0400
Subject: [PATCH] servlet filter

---
 topics/servlet-filter-adapter.adoc | 55 ++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100755 topics/servlet-filter-adapter.adoc

diff --git a/topics/servlet-filter-adapter.adoc b/topics/servlet-filter-adapter.adoc
new file mode 100755
index 0000000000..07092c4a77
--- /dev/null
+++ b/topics/servlet-filter-adapter.adoc
@@ -0,0 +1,55 @@
+
+= Java Servlet Filter Adapter
+
+If you want to use Keycloak with a Java servlet application that doesn't have an adapter for that servlet platform, you can opt to use the servlet filter adapter that Keycloak has.
+This adapter works a little differently than the other adapters.
+You do not define security constraints in web.xml.
+Instead you define a filter mapping using the Keycloak servlet filter adapter to secure the url patterns you want to secure. 
+
+WARNING: Backchannel logout works a bit differently than the standard adapters.
+Instead of invalidating the http session it instead marks the session id as logged out.
+There's just no way of arbitrarily invalidating an http session based on a session id. 
+
+[source]
+----
+
+        
+<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>
+
+    <filter>
+        <filter-name>Keycloak Filter</filter-name>
+        <filter-class>org.keycloak.adapters.servlet.KeycloakOIDCFilter</filter-class>
+    </filter>
+    <filter-mapping>
+        <filter-name>Keycloak Filter</filter-name>
+        <url-pattern>/keycloak/*</url-pattern>
+        <url-pattern>/protected/*</url-pattern>
+    </filter-mapping>
+</web-app>
+----
+
+If you notice above, there are two url-patterns.
+ `/protected/*` are just the files we want protected. `/keycloak/*` url-pattern will handle callback from the keycloak server.
+Note that you should configure your client in the Keycloak Admin Console with an Admin URL that points to a secured section covered by the filter's url-pattern.
+The Admin URL will make callbacks to the Admin URL to do things like backchannel logout.
+So, the Admin URL in this example should be `http[s]://hostname/{context-root}/keycloak`.
+There is an example of this in the distribution. 
+
+The Keycloak filter has the same configuration parameters available as the other adapters except you must define them as filter init params instead of context params. 
+
+To use this filter, include this maven artifact in your WAR poms 
+
+[source]
+----
+
+           <dependency>
+                <groupId>org.keycloak</groupId>
+                <artifactId>keycloak-servlet-filter-adapter</artifactId>
+                <version>&project.version;</version>
+            </dependency>
+----
\ No newline at end of file