Merge pull request #1703 from patriot1burke/master

filter docs

docbook/auth-server-docs/reference/en/en-US/master.xml

@@ -47,6 +47,7 @@
                 <!ENTITY ProtocolMappers SYSTEM "modules/protocol-mappers.xml">
                 <!ENTITY Recaptcha SYSTEM "modules/recaptcha.xml">
                 <!ENTITY AuthSPI SYSTEM "modules/auth-spi.xml">
+                <!ENTITY FilterAdapter SYSTEM "modules/servlet-filter-adapter.xml">
                 ]>
 
 <book>
@@ -105,6 +106,7 @@ This one is short
         &TomcatAdapter;
         &Jetty9Adapter;
         &Jetty8Adapter;
+        &FilterAdapter;
         &FuseAdapter;
         &JavascriptAdapter;
         &SpringBootAdapter;

docbook/auth-server-docs/reference/en/en-US/modules/servlet-filter-adapter.xml

@@ -0,0 +1,51 @@
+<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>/*</url-pattern>
+    </filter-mapping>
+</web-app>
+]]>
+    </programlisting>
+    <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>

docbook/saml-adapter-docs/reference/en/en-US/master.xml

@@ -7,6 +7,7 @@
                 <!ENTITY TomcatAdapter SYSTEM "modules/tomcat-adapter.xml">
                 <!ENTITY Jetty9Adapter SYSTEM "modules/jetty9-adapter.xml">
                 <!ENTITY Jetty8Adapter SYSTEM "modules/jetty8-adapter.xml">
+                <!ENTITY FilterAdapter SYSTEM "modules/servlet-filter-adapter.xml">
                 <!ENTITY Logout SYSTEM "modules/logout.xml">
                 ]>
 
@@ -46,6 +47,7 @@ This one is short
     &TomcatAdapter;
     &Jetty9Adapter;
     &Jetty8Adapter;
+    &FilterAdapter;
     &Logout;
 
 

docbook/saml-adapter-docs/reference/en/en-US/modules/adapter-config.xml

@@ -59,13 +59,13 @@
         <para>
             Here is the explanation of the SP element attributes
         </para>
-        <para><![CDATA[
+        <programlisting><![CDATA[
 <SP entityID="sp"
     sslPolicy="ssl"
     nameIDPolicyFormat="format"
     forceAuthentication="true">
 ...
-</SP>]]></para>
+</SP>]]></programlisting>
         <para>
             <variablelist>
                 <varlistentry>
@@ -129,7 +129,7 @@
             or you can cut and paste the keys directly within <literal>keycloak-saml.xml</literal>
             in the PEM format.
         </para>
-        <para><![CDATA[
+        <programlisting><![CDATA[
         <Keys>
             <Key signing="true" >
                 <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
@@ -139,7 +139,7 @@
             </Key>
         </Keys>
 ]]>
-        </para>
+        </programlisting>
         <para>
             The <literal>Key</literal> element has two optional attributes <literal>signing</literal>
             and <literal>encryption</literal>.  When set to true these tell the adapter what the
@@ -215,13 +215,13 @@
     </section>
     <section>
         <title>RoleIdentifiers element</title>
-        <para><![CDATA[
+        <programlisting><![CDATA[
 <RoleIdentifiers>
      <Attribute name="Role"/>
      <Attribute name="member"/>
      <Attribute name="memberOf"/>
 </RoleIdentifiers>
-]]></para>
+]]></programlisting>
         <para>
             This element is optional.  It defines which SAML attribute values in the assertion should be
             mapped to a Java EE role.  By default <literal>Role</literal> attribute values are converted
@@ -236,7 +236,7 @@
             Everything in the IDP element describes the settings for the IDP the SP is communicating
             with.
         </para>
-        <para>
+        <programlisting>
 <![CDATA[
 <IDP entityID="idp"
      signaturesRequired="true"
@@ -244,7 +244,7 @@
      signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
 ...
 </IDP>]]>
-        </para>
+        </programlisting>
         <para>
             <variablelist>
                 <varlistentry>
@@ -300,12 +300,12 @@
             The <literal>SignleSignOnService</literal> sub element defines the
             login SAML endpoint of the IDP.
         </para>
-        <para><![CDATA[
+        <programlisting><![CDATA[
 <SingleSignOnService signRequest="true"
                      validateResponseSignature="true"
                      requestBinding="post"
                      bindingUrl="url"/>
-]]></para>
+]]></programlisting>
         <para>
             <variablelist>
                 <varlistentry>
@@ -367,7 +367,7 @@
         The <literal>SignleSignOnService</literal> sub element defines the
         login SAML endpoint of the IDP.
     </para>
-    <para><![CDATA[
+    <programlisting><![CDATA[
 <SingleLogoutService validateRequestSignature="true"
                      validateResponseSignature="true"
                      signRequest="true"
@@ -376,7 +376,7 @@
                      responseBinding="post"
                      postBindingUrl="posturl"
                      redirectBindingUrl="redirecturl">
-]]></para>
+]]></programlisting>
     <para>
         <variablelist>
             <varlistentry>

docbook/saml-adapter-docs/reference/en/en-US/modules/servlet-filter-adapter.xml

@@ -0,0 +1,55 @@
+<chapter>
+    <title>Java Servlet Filter Adapter</title>
+    <para>
+        If you want to use  SAML 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>
+    <warning>
+        <para>
+            Backchannel logout does not currently work when you have a clustered application that uses the SAML filter.
+        </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.saml.servlet.SamlFilter</filter-class>
+    </filter>
+    <filter-mapping>
+        <filter-name>Keycloak Filter</filter-name>
+        <url-pattern>/*</url-pattern>
+    </filter-mapping>
+</web-app>
+]]>
+    </programlisting>
+    <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-saml-servlet-filter-adapter</artifactId>
+                <version>&project.version;</version>
+            </dependency>
+]]></programlisting>
+</chapter>