From 4d93e48b1049ec9a639b266fbb3bc5d3aa108e23 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 16 Jul 2019 10:11:37 +1200
Subject: [PATCH] DOCS Add silverstripe/login-forms (#9112)

See https://github.com/silverstripe/recipe-cms/issues/26.
Dependant on https://github.com/silverstripe/silverstripe-installer/pull/257.
---
 .../09_Security/03_Authentication.md          | 12 +++++++++
 docs/en/04_Changelogs/4.5.0.md                | 26 +++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/docs/en/02_Developer_Guides/09_Security/03_Authentication.md b/docs/en/02_Developer_Guides/09_Security/03_Authentication.md
index b72ca8db5..82d525f26 100644
--- a/docs/en/02_Developer_Guides/09_Security/03_Authentication.md
+++ b/docs/en/02_Developer_Guides/09_Security/03_Authentication.md
@@ -6,6 +6,18 @@ summary: Explains SilverStripe's Authentication options and custom authenticator
 By default, SilverStripe provides a [MemberAuthenticator](api:SilverStripe\Security\MemberAuthenticator\MemberAuthenticator) class which hooks into its own internal
 authentication system.
 
+## User Interface
+
+SilverStripe comes with a default login form interface,
+that's embedded into your page templates through the `$Form` placeholder.
+Since it's embedded into your own site styling and behaviour,
+it can require adjustments to your particular context. 
+
+Starting with SilverStripe 4.5, the view logic may be handled through the
+[silverstripe/login-forms](https://github.com/silverstripe/silverstripe-login-forms) module (if present).
+
+## Controllers
+
 The main login system uses these controllers to handle the various security requests:
 
 [Security](api:SilverStripe\Security\Security) - Which is the controller which handles most front-end security requests, including logging in, logging out, resetting password, or changing password. This class also provides an interface to allow configured [Authenticator](api:SilverStripe\Security\Authenticator) classes to each display a custom login form.
diff --git a/docs/en/04_Changelogs/4.5.0.md b/docs/en/04_Changelogs/4.5.0.md
index 170a6c20f..6b53454d4 100644
--- a/docs/en/04_Changelogs/4.5.0.md
+++ b/docs/en/04_Changelogs/4.5.0.md
@@ -2,10 +2,36 @@
 
 ## Overview {#overview}
 
+ * [Generic login form styling](#login-forms)
  * Removed `use_gzip` option on `HtmlEditorField` which used to compress the rich text editor dependency. 
    No longer required since compression is performed as part of the CMS build automatically.
    See (#832)(https://github.com/silverstripe/silverstripe-admin/issues/832)
 
+## Generic login form styling {#login-forms}
+
+Login forms in SilverStripe are traditionally embedded in your page template.
+This often requires style adjustments in your website, for example to cover variations
+such as error messages and validation feedback. It also complicates
+more advanced login flows such as multi-factor authentication.
+
+Starting with this release, new installations include the
+[silverstripe/login-forms](https://github.com/silverstripe/silverstripe-login-forms)
+module. It provides generic styles which look great without any adjustments.
+You can choose to add your own logo, or customise the templates.
+The URLs to login functionality have not changed (e.g. `Security/login`).
+
+Existing SilverStripe websites upgrading to this release can opt in to using
+login forms via composer:
+
+```
+composer require silverstripe/login-forms
+```
+
+Note that any customisations you might have in `Page.ss` or `Layout/Security.ss`
+no longer apply when this module is installed. If you have customised the login process
+by adding form fields, or through custom handlers such as SAML or LDAP,
+you'll need to review those before starting to use the module. 
+
 ## Deprecation
 
  * `PasswordValidator` methods `minLength`, `characterStrength`, and `checkHistoricalPasswords` are now deprecated from