From 14832aa4b94762bb89ee62e67f3fb66e0203b4af Mon Sep 17 00:00:00 2001 From: Antonio Ramirez Date: Thu, 21 Sep 2017 18:42:34 +0200 Subject: [PATCH] re #15 add two factor authentication docs --- .../how-to-implement-two-factor-auth.md | 49 +++++++++++++++++++ docs/index.md | 1 + docs/installation/configuration-options.md | 9 ++++ 3 files changed, 59 insertions(+) create mode 100644 docs/helpful-guides/how-to-implement-two-factor-auth.md diff --git a/docs/helpful-guides/how-to-implement-two-factor-auth.md b/docs/helpful-guides/how-to-implement-two-factor-auth.md new file mode 100644 index 0000000..da9ed9b --- /dev/null +++ b/docs/helpful-guides/how-to-implement-two-factor-auth.md @@ -0,0 +1,49 @@ +How to Implement Two-Factor Auth +================================ + +Two-Factor Authentication products add an additional layer of security. Typically, users are asked to prove their +identity by providing simple credentials such as an email address and a password. A second factor (2F) adds an extra +layer of unauthorized access protection by prompting the user to provide an additional means of authentication such as +a physical token (e.g. a card) or an additional secret that only they know. + +With this module is quite easy. It basically implements two-factor authentication using the following 2amigos libraries: + +- [2amigos/2fa-library](https://github.com/2amigos/2fa-library) +- [2amigos/qrcode-library](https://github.com/2amigos/qrcode-library) + + +Enable Two-Factor +----------------- + +We simply need to enable two factor authentication: + +```php +'modules' => [ + 'user' => [ + 'class' => Da\User\Module::class, + 'enableTwoFactorAuthentication' => true + ] +] +``` + +Now, when the user go to its settings via `user/settings`, it will display the option to enable two-factor +authentication or not. + +When enabled, the module will show a modal with a QrCode that has to be scanned by the Google Authenticator App +(**Recommended**. You can download from +[Google Play](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2) or +[iTunes](https://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8)). + +The application will display a code that needs to be inserted into the modal input box. If code verification goes well, +it will enable the two-factor for the user. + +If a user has enabled the two-factor, and after successfully login via username and email, it will render a new section +where user will have to enter the code displayed on its Google Authenticator App in order to complete with the login +process. + + +### Recommended Reading + +- [2amigos Two-Factor Library Docs]()http://2fa-library.readthedocs.io/en/latest/) + +© [2amigos](http://www.2amigos.us/) 2013-2017 diff --git a/docs/index.md b/docs/index.md index 03d994d..c55a66d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -151,6 +151,7 @@ Helpful Guides -------------- - [How to Add Captcha Widget](helpful-guides/how-to-add-captcha-widget.md) +- [How to Implement Two-Factor Authentication](helpful-guides/how-to-implement-two-factor-auth.md) - [How to Switch Identities](helpful-guides/how-to-swith-identities.md) - [Separate Frontend and Backend Sessions](helpful-guides/separate-frontend-and-backend-sessions.md) - [Social Network Authentication](helpful-guides/social-network-authentication.md) diff --git a/docs/installation/configuration-options.md b/docs/installation/configuration-options.md index 649f12a..99bc29c 100644 --- a/docs/installation/configuration-options.md +++ b/docs/installation/configuration-options.md @@ -3,6 +3,15 @@ Configuration Options The module comes with a set of attributes to configure. The following is the list of all available options: +#### enableTwoFactorAuthentication (type: `boolean`, default: `false`) + +Setting this attribute will allow users to configure their login process with two-factor authentication. + +### twoFactorAuthenticationCycles (type: `integer`, default: `1`) + +By default, Google Authenticator App for two-factor authentication cycles in periods of 30 seconds. In order to allow +a bigger period so to avoid out of sync issues. + #### enableRegistration (type: `boolean`, default: `true`) Setting this attribute allows the registration process. If you set it to `false`, the module won't allow users to