diff --git a/docbook/auth-server-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml b/docbook/auth-server-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml
index 69ac70562ff..79a4c9fc970 100755
--- a/docbook/auth-server-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml
+++ b/docbook/auth-server-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml
@@ -112,6 +112,14 @@
                     check adapter config switches.
                 </para>
             </simplesect>
+            <simplesect>
+                <title>SAML SP Client Adapter Changes</title>
+                <para>
+                    Keycloak SAML SP Client Adapter now requires a specific endpoint, <literal>/saml</literal> to be
+                    registered with your IDP.
+                </para>
+            </simplesect>
+
         </section>
         <section>
             <title>Migrating to 1.8.0</title>
diff --git a/docbook/saml-adapter-docs/reference/en/en-US/master.xml b/docbook/saml-adapter-docs/reference/en/en-US/master.xml
index 89d16e61a49..b1c69384d1f 100755
--- a/docbook/saml-adapter-docs/reference/en/en-US/master.xml
+++ b/docbook/saml-adapter-docs/reference/en/en-US/master.xml
@@ -12,6 +12,8 @@
                 <!ENTITY Logout SYSTEM "modules/logout.xml">
                 <!ENTITY ErrorHandling SYSTEM "modules/adapter_error_handling.xml">
                 <!ENTITY DEBUGGING SYSTEM "modules/debugging.xml">
+                <!ENTITY Migrating SYSTEM "modules/MigrationFromOlderVersions.xml">
+                <!ENTITY IDP_REG SYSTEM "modules/idp-registration.xml">
                 ]>
 
 <book>
@@ -51,10 +53,12 @@ This one is short
     &Jetty9Adapter;
     &Jetty8Adapter;
     &FilterAdapter;
+    &IDP_REG;
     &Logout;
     &Assertions;
     &ErrorHandling;
     &DEBUGGING;
+    &Migrating;
 
 
 
diff --git a/docbook/saml-adapter-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml b/docbook/saml-adapter-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml
new file mode 100755
index 00000000000..23161fab6aa
--- /dev/null
+++ b/docbook/saml-adapter-docs/reference/en/en-US/modules/MigrationFromOlderVersions.xml
@@ -0,0 +1,21 @@
+<chapter id="Migration_from_older_versions">
+    <title>Migration from older versions</title>
+
+    <section>
+        <title>Version specific migration</title>
+        <section>
+            <title>Migrating to 1.9.0</title>
+            <simplesect>
+                <title>SAML SP Client Adapter Changes</title>
+                <para>
+                    Keycloak SAML SP Client Adapter now requires a specific endpoint, <literal>/saml</literal> to be
+                    registered with your IDP.  The SamlFilter must also be bound to /saml in addition to any other binding it has.
+                    This had to be done because SAML POST binding would eat the request input stream and this would be really
+                    bad for clients that relied on it.
+                </para>
+            </simplesect>
+
+        </section>
+
+    </section>
+</chapter>
\ No newline at end of file
diff --git a/docbook/saml-adapter-docs/reference/en/en-US/modules/idp-registration.xml b/docbook/saml-adapter-docs/reference/en/en-US/modules/idp-registration.xml
new file mode 100755
index 00000000000..5a3fe344f3a
--- /dev/null
+++ b/docbook/saml-adapter-docs/reference/en/en-US/modules/idp-registration.xml
@@ -0,0 +1,7 @@
+<chapter id="idp-reg">
+    <title>Registering with an IDP</title>
+    <para>
+        For each servlet based adapter, the endpoint you register for the assert consumer service url and and single logout service
+        must be the base url of your servlet application with <literal>/saml</literal> appended to it i.e. https://example.com/contextPath/saml
+    </para>
+</chapter>
\ No newline at end of file
diff --git a/docbook/saml-adapter-docs/reference/en/en-US/modules/servlet-filter-adapter.xml b/docbook/saml-adapter-docs/reference/en/en-US/modules/servlet-filter-adapter.xml
index dc6526aa571..97419229bbb 100755
--- a/docbook/saml-adapter-docs/reference/en/en-US/modules/servlet-filter-adapter.xml
+++ b/docbook/saml-adapter-docs/reference/en/en-US/modules/servlet-filter-adapter.xml
@@ -42,6 +42,14 @@
         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>
+        You can define multiple filter mappings if you have various different secure and unsecure url patterns.
+    </para>
+    <warning>
+        <para>
+            You must have a filter mapping for <literal>/saml</literal>
+        </para>
+    </warning>
     <para>
         To use this filter, include this maven artifact in your WAR poms
     </para>