Skip to content

Commit

Permalink
Item14459: More twiki cleanup
Browse files Browse the repository at this point in the history 
Improve docmentation.
  • Loading branch information
@gac410
gac410 committed Aug 20, 2017
1 parent 2442e70 commit 78fd2a8
Show file tree
Hide file tree
Showing 11 changed files with 68 additions and 62 deletions.
44 changes: 26 additions & 18 deletions data/System/SmsTwoStepAuthContrib.txt
View file
@@ -1,11 +1,11 @@
%META:TOPICINFO{author="BaseUserMapping_333" comment="" date="1503108486" format="1.1" version="2"}%
%META:TOPICINFO{author="ProjectContributor" comment="" date="1503197778" format="1.1" version="1"}%
---+!! SMS Two-Step Authentication Contrib Package
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{ title="Page contents" depth="2" }%
</div>
<div style="float:right; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
<img src="%ATTACHURLPATH%/sms-access-code-login-350.png" alt="sms-access-code-login-350.png" width="350" height="230" />
<img src="%ATTACHURLPATH%/sms-access-code-login-350.png" alt="sms-access-code-login-350.png" width="329" height="350" />
</div>
</sticky>
%SHORTDESCRIPTION%
Expand All @@ -14,27 +14,36 @@

A single step log-in may not be sufficient in a high security environment. [[Wikipedia:Two-step_verification][Two-step verification]] makes it harder for an intruder to impersonate a user.

This extension adds two-step authentication to Foswiki. The first step is the usual log-in with name and password. After that, a second authentication screen is shown prompting the user to enter an access code. The access code is sent via SMS ([[Wikipedia:Short_Message_Service][Short Message Service]]) to the mobile phone of the user who just logged in. This access code can be used only once. If enabled, the access code can also be sent to the registered e-mail address of the log-in user. A white-list can be defined so that users can log in with a single step at trusted locations, such as at known office locations.
This extension supplies an alternate !LoginManager (_SmsTwoStepLogin_) for Foswiki that implements two-step login. The first step is the usual log-in with name and password.
After that, a second authentication screen is shown prompting the user to enter an access code.
The access code is sent via SMS ([[Wikipedia:Short_Message_Service][Short Message Service]]) to the mobile phone of the user who just logged in.
* Each access code can be used only once.
* If SMS is unavailable, the access code can optionally be sent to the registered e-mail address of the log-in user.
* A white-list can be defined so that users can log in with a single step at trusted locations, such as at known office locations.

This requires the user to have two factors for access. Something they "know" - their password, and something they possess, their cell phone or email.

---++ Detailed Documentation

<sticky><div style="float:right; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
&nbsp;&nbsp; __Diagram of two-step log-in process:__ %BR%
<img src="%ATTACHURLPATH%/sms-2step-auth-diagram.png" alt="sms-2step-auth-diagram.png" width="638" height="487" />
<img src="%ATTACHURLPATH%/sms-2step-auth-diagram-v2.png" alt="sms-2step-auth-diagram-v2.png" width="600" height="600" />
</div></sticky>
Once this extension is installed and configured properly, the log-in process happens as follows:

* Foswiki's Login Manager shows the usual log-in screen.
* The user logs in with name and password.
* The Login Manager verifies the password - this can be against Foswiki's internal password manager or an external one, such as the LDAP password manager.
* If the password is OK, the !SmsTwoStepAuthContrib checks if the IP address of the user is white-listed.
* If white-listed, the !SmsTwoStepAuthContrib tells the Login Manager to log in the user.
* Else, the !SmsTwoStepAuthContrib generates a one-time-use access code, sends that to the registered user via SMS, and shows an access code log-in screen.
* The !SmsTwoStepLogin Manager shows the usual Template log-in screen.
* The user logs in with their WikiName, login name, or email address and password.
* The !SmsTwoStepLogin verifies the password - this can be against Foswiki's internal password manager or an external one, such as the LDAP password manager.
* If the password is OK, the !SmsTwoStepLogin checks if the IP address of the user is white-listed.
* If white-listed, the !SmsTwoStepLogin approves the login..
* Else, the !SmsTwoStepLogin generates a one-time-use access code, sends that to the registered user via SMS, and shows an access code log-in screen.
* If the user has not specified a mobile number and a carrier, and if enabled in configure, the access code is sent to the registered e-mail address of the user.
* Else, an error message of insufficient credentials is shown.
* The Login Manager receives the access code and forwards it to the !SmsTwoStepAuthContrib.
* The !SmsTwoStepAuthContrib verifies the access code against the generated one.
* If Two-step login is configured as optional, then the login is still permitted.
* Otherwise, an error message of insufficient credentials is shown.
* The !SmsTwoStepLogin receives the access code for validation.
* The !SmsTwoStepLogin verifies the access code against the generated one.
* If OK, the !SmsTwoStepAuthContrib tells the Login Manager to log in the user.
* If invalid, the login is rejected.

__Notes:__

Expand Down Expand Up @@ -251,8 +260,7 @@ Many thanks to the following sponsors for supporting this work:
%META:FIELD{name="License" title="License" value="[[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]]"}%
%META:FIELD{name="Home" title="Home" value="Foswiki:Extensions.%25$ROOTMODULE%25"}%
%META:FIELD{name="Support" title="Support" value="Foswiki:Support.%25$ROOTMODULE%25"}%
%META:FILEATTACHMENT{name="mobile-carrier.gif" attachment="mobile-carrier.gif" attr="h" comment="" date="1502939431" size="890" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms.gif" attachment="sms.gif" attr="h" comment="" date="1502939431" size="2243" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms-2step-auth-diagram.png" attachment="sms-2step-auth-diagram.png" attr="h" comment="" date="1502939431" size="79934" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms-access-code-login.png" attachment="sms-access-code-login.png" attr="h" comment="" date="1502939431" size="42595" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms-access-code-login-350.png" attachment="sms-access-code-login-350.png" attr="h" comment="" date="1502939431" size="53563" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="mobile-carrier.gif" attachment="mobile-carrier.gif" attr="h" comment="" date="1503197778" size="890" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms.gif" attachment="sms.gif" attr="h" comment="" date="1503197778" size="2243" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms-2step-auth-diagram.png" attachment="sms-2step-auth-diagram.png" attr="h" comment="" date="1503197778" size="79934" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="sms-access-code-login-350.png" attachment="sms-access-code-login-350.png" attr="h" comment="" date="1503197778" size="53563" user="ProjectContributor" version="1"}%
4 changes: 1 addition & 3 deletions lib/Foswiki/Contrib/SmsTwoStepAuthContrib/MANIFEST
View file
Expand Up @@ -6,10 +6,8 @@ lib/Foswiki/Contrib/SmsTwoStepAuthContrib/Config.spec 0644
lib/Foswiki/Contrib/SmsTwoStepAuthContrib/DEPENDENCIES 0644
lib/Foswiki/LoginManager/SmsTwoStepLogin.pm 0775
pub/System/SmsTwoStepAuthContrib/mobile-carrier.gif 0644
pub/System/SmsTwoStepAuthContrib/sms-2step-auth-diagram.png 0644
pub/System/SmsTwoStepAuthContrib/sms-2step-auth-diagram.ppt 0644
pub/System/SmsTwoStepAuthContrib/sms-2step-auth-diagram.png 0664
pub/System/SmsTwoStepAuthContrib/sms-access-code-login-350.png 0644
pub/System/SmsTwoStepAuthContrib/sms-access-code-login.png 0644
pub/System/SmsTwoStepAuthContrib/sms.gif 0644
templates/smstwostepemaillogin.tmpl 0644
templates/smstwostepemailmessage.tmpl 0644
Expand Down
Binary file added pub/System/SmsTwoStepAuthContrib/sms-2step-auth-diagram.odp
View file
Binary file not shown.
Binary file modified pub/System/SmsTwoStepAuthContrib/sms-2step-auth-diagram.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pub/System/SmsTwoStepAuthContrib/sms-2step-auth-diagram.xcf
View file
Binary file not shown.
Binary file modified pub/System/SmsTwoStepAuthContrib/sms-access-code-login-350.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed pub/System/SmsTwoStepAuthContrib/sms-access-code-login.png
View file
Binary file not shown.
Binary file added pub/System/SmsTwoStepAuthContrib/sms-access-code-login.xcf
View file
Binary file not shown.
36 changes: 18 additions & 18 deletions templates/smstwostepemaillogin.tmpl
View file
@@ -1,7 +1,7 @@
%{ Login template of SmsTwoStepAuthContrib }%
%TMPL:INCLUDE{"twiki"}%
%TMPL:INCLUDE{"foswiki"}%

%TMPL:DEF{"webaction"}%%MAKETEXT{"TWiki Two Factor Authentication"}%%TMPL:END%
%TMPL:DEF{"webaction"}%%MAKETEXT{"Foswiki Two Factor Authentication"}%%TMPL:END%
%TMPL:DEF{"titleaction"}%%MAKETEXT{"(E-mail login)"}% %TMPL:END%
%TMPL:DEF{"LOG_IN_BANNER"}%%TMPL:END%
%TMPL:DEF{"LOGGED_IN_BANNER"}%%TMPL:END%
Expand All @@ -13,50 +13,50 @@
%TMPL:DEF{"title"}%---++ %MAKETEXT{"Please enter the access code received by e-mail"}%
%TMPL:END%

%TMPL:DEF{"titlestep"}%<div class="twikiFormStep">
%TMPL:DEF{"titlestep"}%<div class="foswikiFormStep">
%TMPL:P{"title"}%
%TMPL:P{"notestep"}%
%TMPL:P{"errorstep"}%</div><!-- /twikiFormStep-->%TMPL:END%
%TMPL:P{"errorstep"}%</div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"notestep"}%<div style="display:%IF{'defined ERROR or defined NOTE or defined BANNER' then='block' else='none'}%;">
%IF{"defined NOTE AND $NOTE != ''" then='---+++ %NOTE%'}%</div>%TMPL:END%

%TMPL:DEF{"errorstep"}%%IF{"defined BANNER AND $BANNER != ''" then='<div class="twikiNotification twikiAlert twikiUnvisited patternLoginNotification">%BANNER%%IF{"defined ERROR AND $ERROR != ''" then='<!--%TMPL:P{"error"}%-->'}%</div>'}%%TMPL:END%
%TMPL:DEF{"errorstep"}%%IF{"defined BANNER AND $BANNER != ''" then='<div class="foswikiNotification foswikiAlert foswikiUnvisited patternLoginNotification">%BANNER%%IF{"defined ERROR AND $ERROR != ''" then='<!--%TMPL:P{"error"}%-->'}%</div>'}%%TMPL:END%

%TMPL:DEF{"error"}%%MAKETEXT{"Error: [_1]" args="%ERROR%"}%%TMPL:END%

%TMPL:DEF{"formstart"}%<form action='%SCRIPTURLPATH{"login"}%/%WEB%/%TOPIC%' name='loginform' method='post'>%TMPL:END%

%TMPL:DEF{"formend"}%<literal> <input type='hidden' name='username' value='%LOGINNAME%' /> %QUERYPARAMS{encoding="entity" format="<input type='hidden' name='$name' value='$value' />"}% </literal><input type="hidden" name="origurl" value="%ORIGURL%" /></form>%TMPL:END%

%TMPL:DEF{"accesscodefield"}%<input tabindex='1' type='text' class='twikiInputField twikiFocus' size='40' name='accesscode' value='' />%TMPL:END%
%TMPL:DEF{"accesscodefield"}%<input tabindex='1' type='text' class='foswikiInputField foswikiFocus' size='40' name='accesscode' value='' />%TMPL:END%

%TMPL:DEF{"accesscodestep"}%<div class="twikiFormStep">
%TMPL:DEF{"accesscodestep"}%<div class="foswikiFormStep">
---+++ %MAKETEXT{"Access code for <nop>[_1]" args="%LOGINNAME%"}%

%TMPL:P{"accesscodefield"}% %TMPL:P{"accesscodefieldhelp"}%

</div><!-- /twikiFormStep-->%TMPL:END%
</div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"accesscodenote"}%This <nop>%WIKITOOLNAME% requires two-step authentication. This is step two. Please check your e-mail - you will get a one-time-use access code. Enter the access code to log in. %TMPL:END%

%TMPL:DEF{"accesscodefieldhelp"}% <div class="twikiHelp">%TMPL:P{"accesscodenote"}%</div> %TMPL:END%
%TMPL:DEF{"accesscodefieldhelp"}% <div class="foswikiHelp">%TMPL:P{"accesscodenote"}%</div> %TMPL:END%

%TMPL:DEF{"submitstep"}%<div class="twikiFormStep">%TMPL:P{"submit"}%</div><!-- /twikiFormStep-->%TMPL:END%
%TMPL:DEF{"submitstep"}%<div class="foswikiFormStep">%TMPL:P{"submit"}%</div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"submit"}%<input tabindex='4' type='submit' class='twikiSubmit' value='%MAKETEXT{"Logon"}%' />%TMPL:END%
%TMPL:DEF{"submit"}%<input tabindex='4' type='submit' class='foswikiSubmit' value='%MAKETEXT{"Logon"}%' />%TMPL:END%

%{ please keep the spaces between the div and the TMPL seealsonote, it allows TWiki to process the emailaddress }%
%TMPL:DEF{"seealsostep"}%<div class="twikiFormStep twikiGrayText twikiLast"> %TMPL:P{"seealsonote"}% </div><!-- /twikiFormStep-->%TMPL:END%
%{ please keep the spaces between the div and the TMPL seealsonote, it allows Foswiki to process the emailaddress }%
%TMPL:DEF{"seealsostep"}%<div class="foswikiFormStep foswikiGrayText foswikiLast"> %TMPL:P{"seealsonote"}% </div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"seealsonote"}% %MAKETEXT{"If you have any questions, please contact [_1]" args="%IF{"defined WIKIWEBMASTER AND $WIKIWEBMASTER != ''" then="%WIKIWEBMASTER%" else="your TWiki administrator"}%"}% %TMPL:END%
%TMPL:DEF{"seealsonote"}% %MAKETEXT{"If you have any questions, please contact [_1]" args="%IF{"defined WIKIWEBMASTER AND $WIKIWEBMASTER != ''" then="%WIKIWEBMASTER%" else="your Foswiki administrator"}%"}% %TMPL:END%

%TMPL:DEF{"form"}%<div id="twikiLogin">
<div class="twikiFormSteps">%TMPL:P{"formstart"}%%TMPL:P{"titlestep"}%
%TMPL:DEF{"form"}%<div id="foswikiLogin">
<div class="foswikiFormSteps">%TMPL:P{"formstart"}%%TMPL:P{"titlestep"}%
%TMPL:P{"accesscodestep"}%%TMPL:P{"submitstep"}%
%TMPL:P{"formend"}%
%TMPL:P{"seealsostep"}%
</div><!-- /twikiFormSteps-->
</div><!-- /twikiLogin-->%TMPL:END%
</div><!-- /foswikiFormSteps-->
</div><!-- /foswikiLogin-->%TMPL:END%

%TMPL:DEF{"content"}%%TMPL:P{"form"}%%TMPL:END%
32 changes: 16 additions & 16 deletions templates/smstwosteperrorlogin.tmpl
View file
@@ -1,7 +1,7 @@
%{ Login template of SmsTwoStepAuthContrib }%
%TMPL:INCLUDE{"twiki"}%
%TMPL:INCLUDE{"foswiki"}%

%TMPL:DEF{"webaction"}%%MAKETEXT{"TWiki Two Factor Authentication"}%%TMPL:END%
%TMPL:DEF{"webaction"}%%MAKETEXT{"Foswiki Two Factor Authentication"}%%TMPL:END%
%TMPL:DEF{"titleaction"}%%MAKETEXT{"(Insufficient credentials)"}% %TMPL:END%
%TMPL:DEF{"LOG_IN_BANNER"}%%TMPL:END%
%TMPL:DEF{"LOGGED_IN_BANNER"}%%TMPL:END%
Expand All @@ -13,38 +13,38 @@
%TMPL:DEF{"title"}%---++ %MAKETEXT{"Insufficient credentials for two-factor authentication"}%
%TMPL:END%

%TMPL:DEF{"titlestep"}%<div class="twikiFormStep">
%TMPL:DEF{"titlestep"}%<div class="foswikiFormStep">
%TMPL:P{"title"}%
%TMPL:P{"notestep"}%
%TMPL:P{"errorstep"}%</div><!-- /twikiFormStep-->%TMPL:END%
%TMPL:P{"errorstep"}%</div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"notestep"}%<div style="display:%IF{'defined ERROR or defined NOTE or defined BANNER' then='block' else='none'}%;">
%IF{"defined NOTE AND $NOTE != ''" then='---+++ %NOTE%'}%</div>%TMPL:END%

%TMPL:DEF{"errorstep"}%%IF{"defined BANNER AND $BANNER != ''" then='<div class="twikiNotification twikiAlert twikiUnvisited patternLoginNotification">%BANNER%%IF{"defined ERROR AND $ERROR != ''" then='<!--%TMPL:P{"error"}%-->'}%</div>'}%%TMPL:END%
%TMPL:DEF{"errorstep"}%%IF{"defined BANNER AND $BANNER != ''" then='<div class="foswikiNotification foswikiAlert foswikiUnvisited patternLoginNotification">%BANNER%%IF{"defined ERROR AND $ERROR != ''" then='<!--%TMPL:P{"error"}%-->'}%</div>'}%%TMPL:END%

%TMPL:DEF{"error"}%%MAKETEXT{"Error: [_1]" args="%ERROR%"}%%TMPL:END%

%TMPL:DEF{"accesscodefield"}%<input tabindex='1' type='text' class='twikiInputField twikiFocus' size='40' name='accesscode' value='' />%TMPL:END%
%TMPL:DEF{"accesscodefield"}%<input tabindex='1' type='text' class='foswikiInputField foswikiFocus' size='40' name='accesscode' value='' />%TMPL:END%

%TMPL:DEF{"accesscodestep"}%<div class="twikiFormStep">
%TMPL:DEF{"accesscodestep"}%<div class="foswikiFormStep">
%TMPL:P{"accesscodefieldhelp"}%
</div><!-- /twikiFormStep-->%TMPL:END%
</div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"accesscodenote"}%This <nop>%WIKITOOLNAME% requires two-step authentication. Unfortunately you do not show sufficient credentials to log in to this site. You need to specify a mobile number and a mobile carrier in your user profile topic. Once done you will get an SMS (text message) on your mobile phone with a one-time-use access code you can use to log in as the second step. %TMPL:END%

%TMPL:DEF{"accesscodefieldhelp"}% <div class="twikiHelp">%TMPL:P{"accesscodenote"}%</div> %TMPL:END%
%TMPL:DEF{"accesscodefieldhelp"}% <div class="foswikiHelp">%TMPL:P{"accesscodenote"}%</div> %TMPL:END%

%{ please keep the spaces between the div and the TMPL seealsonote, it allows TWiki to process the emailaddress }%
%TMPL:DEF{"seealsostep"}%<div class="twikiFormStep twikiGrayText twikiLast"> %TMPL:P{"seealsonote"}% </div><!-- /twikiFormStep-->%TMPL:END%
%{ please keep the spaces between the div and the TMPL seealsonote, it allows Foswiki to process the emailaddress }%
%TMPL:DEF{"seealsostep"}%<div class="foswikiFormStep foswikiGrayText foswikiLast"> %TMPL:P{"seealsonote"}% </div><!-- /foswikiFormStep-->%TMPL:END%

%TMPL:DEF{"seealsonote"}% %MAKETEXT{"If you have any questions, please contact [_1]" args="%IF{"defined WIKIWEBMASTER AND $WIKIWEBMASTER != ''" then="%WIKIWEBMASTER%" else="your TWiki administrator"}%"}% %TMPL:END%
%TMPL:DEF{"seealsonote"}% %MAKETEXT{"If you have any questions, please contact [_1]" args="%IF{"defined WIKIWEBMASTER AND $WIKIWEBMASTER != ''" then="%WIKIWEBMASTER%" else="your Foswiki administrator"}%"}% %TMPL:END%

%TMPL:DEF{"form"}%<div id="twikiLogin">
<div class="twikiFormSteps">%TMPL:P{"titlestep"}%
%TMPL:DEF{"form"}%<div id="foswikiLogin">
<div class="foswikiFormSteps">%TMPL:P{"titlestep"}%
%TMPL:P{"accesscodestep"}%
%TMPL:P{"seealsostep"}%
</div><!-- /twikiFormSteps-->
</div><!-- /twikiLogin-->%TMPL:END%
</div><!-- /foswikiFormSteps-->
</div><!-- /foswikiLogin-->%TMPL:END%

%TMPL:DEF{"content"}%%TMPL:P{"form"}%%TMPL:END%

0 comments on commit 78fd2a8

Please sign in to comment.