servlet filter

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