registration and recaptcha

SUMMARY.adoc

@@ -3,7 +3,6 @@
 //. link:topics/templates/document-attributes.adoc[]
 :imagesdir: images
 
- . link:topics/preface.adoc[Preface]
  . link:topics/overview.adoc[Overview]
  .. link:topics/features.adoc[Features]
  .. link:topics/how.adoc[How Does Security Work?]
@@ -24,6 +23,8 @@
  .. link:topics/users/credentials.adoc[Credentials]
  .. link:topics/users/required-actions.adoc[Required Actions]
  .. link:topics/users/impersonation.adoc[Impersonation]
+ .. link:topics/users/user-registration.adoc[User Registration]
+ ... link:topics/users/recaptcha.adoc[Recaptcha Support]
  . link:topics/admin-permissions.adoc[Master Admin Access Control]
  . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
  . link:topics/client-registration.adoc[Client Registration]

topics/preface.adoc

@@ -1,20 +0,0 @@
-= Preface
-
-In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width.These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented.
-So: 
-
-[source]
-----
-Let's pretend to have an extremely \
-long line that \
-does not fit
-This one is short
-----         
-Is really: 
-
-[source]
-----
-Let's pretend to have an extremely long line that does not fit
-This one is short
-----      
-

topics/recaptcha.adoc

@@ -1,24 +0,0 @@
-[[_recaptcha]]
-= Recaptcha Support on Registration
-
-To safeguard registration against bots, Keycloak has integration with Google Recaptcha.
-To enable this you need to first go to https://developers.google.com/recaptcha/[Google Recaptcha]        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). 
-
-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. 
-
-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 `https://www.google.com` to the values of both the `X-Frame-Options` and `Content-Security-Policy` headers.
-i.e.
-
-[source]
-----
-frame-src 'self' https://www.google.com
-----    
-
-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. 

topics/users/recaptcha.adoc

@@ -0,0 +1,37 @@
+[[_recaptcha]]
+
+==== Recaptcha Support
+
+To safeguard registration against bots, {{book.project.name}} has integration with Google Recaptcha.
+To enable this you need to first go to link:https://developers.google.com/recaptcha/[Google Recaptcha Website]
+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). 
+
+Next, there's a few steps you need to perform in the {{book.project.name}} Admin Console.
+Click the `Authentication` left menu itme and go to the `Flows` tab.  Select the `Registration` flow from the drop down
+list on this page.
+
+.Registration Flow
+image:../../{{book.images}}/registration-flow.png[]
+
+
+Set the 'Recaptcha' requirement to `Required` by clicking the appropriate radio button.  This will enable
+Recaptcha on the screen.  Next, you have to enter in the Recaptcha site key and secret that you generated at the Google Recaptcha Website.
+Click on the 'Configure' button that is to the right of the Recaptcha flow entry and enter in the Recaptcha site key and secret on this config page.
+
+.Recaptcha Config Page
+image:../../{{book.images}}/recaptcha-config.png[]
+
+
+The final step you have to do is to change some default HTTP response headers that {{book.project.name} sets.  {{book.project.name}}
+will prevent website from including any login page within an iframe.  This is to prevent clickjacking attacks.  You need to
+authorize Google to use the registration page within an iframe.  Go to
+the `Realm Settings` left menu item and then go to the `Security Defenses` tab.  Y
+ou'll need to add `https://www.google.com` to the values of both the `X-Frame-Options` and `Content-Security-Policy` headers.
+
+.Authorizing Iframes
+image:../../{{book.images}}/security-headers.png[]
+
+Once you do this, Recaptcha should show up on your registration page.  You may want to edit _register.ftl_ in your login
+theme to muck around with the placement and styling of the recaptcha button.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
+for more information on extending and creating themes.

topics/users/user-registration.adoc

@@ -0,0 +1,26 @@
+
+=== User Registration
+
+You can enable {{book.project.name}} to allow user self registration.  When enabled, the login page has a registration
+link the user can click on to create their new account.  Enabling registration is pretty simple.  Go to the
+`Realm Settings` left menu and click it.  Then go to the `Login` tab.  There is a `User Registration` switch on this
+tab.  Turn it on, then click the `Save` button.
+
+.Login Tab
+image:../../{{book.images}}/login-tab.png[]
+
+After you enable this setting, a `Register` link should show up on the login page.
+
+.Registration Link
+image:../../{{book.images}}/registration-link.png[]
+
+Clicking on this link will bring the user to the registration page where they have to enter in some user profile information
+and a new password.
+
+.Registration Form
+image:../../{{book.images}}/registration-form.png[]
+
+You can change the look and feel of the registration form as well as removing or adding additional fields that must be entered.
+See the link:{{book.developerguide.link}}[{{book.developerguide.name}}] for more information.
+
+