<!--
  ~ Copyright 2016 Red Hat, Inc. and/or its affiliates
  ~ and other contributors as indicated by the @author tags.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<section>
    <title>Java Servlet Filter Adapter</title>
    <para>
        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.
    </para>
    <warning>
        <para>
            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.
        </para>
    </warning>

    <programlisting>
        <![CDATA[
<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>
]]>
    </programlisting>
    <para>
        If you notice above, there are two url-patterns.  <literal>/protected/*</literal> are just the files we want protected.
        <literal>/keycloak/*</literal> 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 <literal>http[s]://hostname/{context-root}/keycloak</literal>.  There is an example of this in the distribution.
    </para>
    <para>
        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.
    </para>
    <para>
        To use this filter, include this maven artifact in your WAR poms
    </para>
    <programlisting><![CDATA[
           <dependency>
                <groupId>org.keycloak</groupId>
                <artifactId>keycloak-servlet-filter-adapter</artifactId>
                <version>&project.version;</version>
            </dependency>
]]></programlisting>
</section>