From 6c9708c700605e020fae85cc38ed657f6e641cb6 Mon Sep 17 00:00:00 2001
From: Bill Burke <bburke@redhat.com>
Date: Wed, 8 Jul 2015 19:47:15 -0400
Subject: [PATCH] recaptcha docs

---
 docbook/reference/en/en-US/master.xml         |  2 ++
 .../reference/en/en-US/modules/recaptcha.xml  | 26 +++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100755 docbook/reference/en/en-US/modules/recaptcha.xml

diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index d379ac8151..59b2be1ba6 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -44,6 +44,7 @@
                 <!ENTITY Proxy SYSTEM "modules/proxy.xml">
                 <!ENTITY CustomAttributes SYSTEM "modules/custom-attributes.xml">
                 <!ENTITY ProtocolMappers SYSTEM "modules/protocol-mappers.xml">
+                <!ENTITY Recaptcha SYSTEM "modules/recaptcha.xml">
                 ]>
 
 <book>
@@ -108,6 +109,7 @@ This one is short
 
     &IdentityBroker;
     &Themes;
+    &Recaptcha;
 
     <chapter>
         <title>Email</title>
diff --git a/docbook/reference/en/en-US/modules/recaptcha.xml b/docbook/reference/en/en-US/modules/recaptcha.xml
new file mode 100755
index 0000000000..27f9177c83
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/recaptcha.xml
@@ -0,0 +1,26 @@
+<chapter id="recaptcha">
+    <title>Recaptcha Support on Registration</title>
+
+    <para>
+        To safeguard registration against bots, Keycloak has integration with Google Recaptcha.  To enable this you
+        need to first go to <ulink url="https://developers.google.com/recaptcha/">Google Recaptcha</ulink>
+        and create an API key so that you can get your recaptcha site key and secret.  (FYI, localhost works by default
+        so you don't have to specify a domain).
+     </para>
+    <para>Next, go to the Keycloak Admin Console.  Go to
+        Authentication->Flows page.  Select the 'registration' flow.  Set the 'Recaptcha' requirement to 'Required'.  Click
+        on the 'Configure' button and enter in the Recaptcha site key and secret.
+    </para>
+    <para>
+        Finally, you have to change Keycloak's default security headers.  In the Admin Console, go to Settings->Security Defenses
+        of your realm.  Add a space and <literal>https://www.google.com</literal> to the values of both the <literal>X-Frame-Options</literal>
+        and <literal>Content-Security-Policy</literal> headers.  i.e.
+        <programlisting>
+            frame-src 'self' https://www.google.com
+        </programlisting>
+    </para>
+    <para>
+        That's it!  You may want to edit register.ftl in your login theme to muck around with the placement and styling
+        of the recaptcha button.  Up to you.
+    </para>
+</chapter>