DOCS Added user guide and screenshots

camfindlay · Aug 8, 2015 · 4be6f2e · 4be6f2e
1 parent 2b0b337
commit 4be6f2e
Show file tree

Hide file tree

Showing 6 changed files with 46 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# 2 factor authentication for SilverStripe CMS
+# Two factor authentication for SilverStripe CMS
 
 Enable two factor authentication Timed One-Time Password) for SilverStripe CMS using QR codes and Google Authenticator app.
 
@@ -12,12 +12,19 @@ Enable two factor authentication Timed One-Time Password) for SilverStripe CMS u
 composer require camfindlay/silverstripe-twofactorauth
 ```
 
-## Configuration
-See [Configuration documentation](docs/en/configuration.md)
+## Documentation
+### Configuration
+See [Configuration](docs/en/configuration.md) documentation
 
-## Usage
+### User guide
+See [User guide](docs/en/userguide.md) documentation
 
+## Maintainers
+- Cam Findlay <cam@silverstripe.com>
 
+## Contributing
+See [Contributing documentation and license agreement](CONTRIBUTING.md)
 
-## Maintainers
-- Cam Findlay <cam@silverstripe.com>
+## License
+Code is license under the BSD 3-Clause Open Source license.
+See [License](LICENSE.md)
diff --git a/composer.json b/composer.json
@@ -31,7 +31,12 @@
 		"installer-name": "twofactorauth",
 		"branch-alias": {
 			"dev-master": "1.0.x-dev"
-		}
+		},
+		"screenshots": [
+			"docs/en/_images/2fa-token-qr.png",
+			"docs/en/_images/2fa-login.png",
+			"docs/en/_images/2fa-backup.png"
+		]
 	},
 	"replace" : {
         "91carriage/2fa": "*"

diff --git a/docs/en/_images/2fa-backup.png b/docs/en/_images/2fa-backup.png
diff --git a/docs/en/_images/2fa-login.png b/docs/en/_images/2fa-login.png
diff --git a/docs/en/_images/2fa-token-qr.png b/docs/en/_images/2fa-token-qr.png
diff --git a/docs/en/userguide.md b/docs/en/userguide.md
@@ -0,0 +1,27 @@
+# User guide
+
+## Setting up a user with two factor authentication
+Setting up two factor authentication can only be performed by a CMS user with permissions to the Security section of your SilverStripe CMS.
+
+1. Log into the CMS.
+2. For a given user select, "Enable Two Factor Authentication" checkbox and save the user. This will generate a Timed One-Time Password token and a QR code to set up in your second factor application (Google Authenticator for example).
+
+![2FA token and QR code](_images/2fa-token-qr.png)
+
+4. Scan QR (or enter the token) into your two factor authentication application and use alongside your regular email and password when logging into the CMS.
+
+![Security token prompt](_images/2fa-login.png)
+
+## Setting backup tokens
+You can set up backup security tokens just in case you lose access to your second factor device.
+
+1. Log into the CMS (again you will need access to the Security section).
+2. For a given user, select the "Backup Tokens" tab.
+3. Click "Add OTP Backup Token"
+
+![Backup tokens](_images/2fa-backup.png)
+
+4. Enter a random set of characters to act as the backup token (this is up to you to provide a suitable token). Save.
+5. You can now use this token in place of two factor authentication. 
+
+Tokens are single use by default and will be removed from the pool of backup tokens for a given user once entered during the log in process. This can be configured to be multiuse by a developer in the [configuration](configuration.md) by setting `single_use: false`. This is not recomendaed as it negates the improved security of having a second factor involved in your log in process. Effectively you end up with two passwords with this configuration setting, and is only marginally better security wise.