Tags:
authentication1Add my vote for this tag security1Add my vote for this tag create new tag
, view all tags

SMS Two-Step Authentication Contrib Package

sms-access-code-login-350.png
Two-step authentication using SMS for the second step

Introduction

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

This extension adds two-step authentication to TWiki. 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 (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.

Detailed Documentation

   Diagram of two-step log-in process:
sms-2step-auth-diagram.png
Once this extension is installed and configured properly, the log-in process happens as follows:

  • TWiki'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 TWiki'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.
    • 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 OK, the SmsTwoStepAuthContrib tells the Login Manager to log in the user.

Notes:

  • White-listed IP addresses are typically used for offices so that employees can log in with a single step at work. The second step is implicit at trusted locations.
  • The one-time-use access code has a configurable life-span, the default is 10 minutes.

Mobile Carriers

Users get an SMS as part of the second authentication step. This extension sends an e-mail to an "e-mail to SMS gateway". These gateways are carrier specific. This list defines the parameters of each gateway.

Type Carrier E-mail Filter Activation
E2SMS USA: AT&T $phone@txt.att.net ^\+?1?  
E2SMS USA: Cingular GSM $phone@cingularme.com ^\+?1?  
E2SMS USA: Cingular TDMA $phone@mmode.com ^\+?1?  
E2SMS USA: Cricket $phone@sms.mycricket.com ^\+?1?  
E2SMS USA: Metro PCS $phone@mymetropcs.com ^\+?1?  
E2SMS USA: Nextel $phone@messaging.nextel.com ^\+?1?  
E2SMS USA: Sprint PCS $phone@messaging.sprintpcs.com ^\+?1?  
E2SMS USA: T-Mobile $phone@tmomail.net ^\+?1?  
E2SMS USA: US Cellular $phone@email.uscc.net ^\+?1?  
E2SMS USA: Verizon $phone@vtext.com ^\+?1?  
E2SMS France: Orange $phone@orange.fr ^\+?(33)?  
E2SMS France: SFR $phone@sfr.fr ^\+?(33)?  
E2SMS Germany: E-Plus 0$phone@smseplus.de ^\+?(49)?0? Send START to 7676245
E2SMS Germany: Mobilis 0$phone@mobilis.de ^\+?(49)?0?  
E2SMS Germany: Mannesmann M. $phone@d2-message.de ^\+?(49)?0?  
E2SMS Germany: O2 0$phone@o2online.de ^\+?(49)?0? Send +OPEN to 6245
E2SMS Germany: Simyo $phone@eplus.de ^\+?(49)?0?  
E2SMS Germany: T-Mobile +49$phone@t-d1-sms.de ^\+?(49)?0? Send OPEN to 8000
E2SMS Germany: Vodafone $phone@vodafone-sms.de ^\+?(49)?0? Send OPEN to 3400
E2SMS Israel: Cellcom $phone@cellcom.co.il ^\+?(972)?  
E2SMS Israel: Orange IL $phone@shiny.co.il ^\+?(972)?  
E2SMS Israel: Spikko $phone@spikosms.com ^\+?(972)?  
E2SMS Netherlands: Dutchtone 0$phone@sms.orange.nl ^\+?(31)?  
E2SMS Netherlands: Orange-NL 0$phone@sms.orange.nl ^\+?(31)?  
E2SMS Netherlands: T-Mobile 31$phone@gin.nl ^\+?(31)? Send EMAIL ON to 555
E2SMS Switzerland: Sunrise Commun. $phone@gsm.sunrise.ch ^\+?(41)?0?  
E2SMS Switzerland: Sunrise Mobile $phone@mysunrise.ch ^\+?(41)?0?  
E2SMS Switzerland: Swisscom $phone@bluewin.ch ^\+?(41)?0?  
E2SMS UK: O2 44$phone@mmail.co.uk ^\+?(44)? Send text 'ON' to 212
E2SMS UK: Orange 44$phone@orange.net ^\+?(44)? Activate via website
E2SMS UK: T-Mobile 44$phone@t-mobile.uk.net ^\+?(44)? Dial 191 for info, activate via website
E2SMS UK: Virgin Mobile 44$phone@vmoble.com ^\+?(44)?  
E2SMS UK: Vodafone 44$phone@vodafone.net ^\+?(44)? Dial 242 for info. activate via website

Legend of columns:

  • Type: Has to be E2SMS
  • Carrier: Name of carrier in format Country: Carrier. Keep the name short.
  • E-mail: Gateway e-mail address. $phone expands to the user's mobile number.
  • Filter: Regular expression filter to clean up the mobile number. Typically used to strip country code and leading zeros. If a gateway requires the country code, strip it from the mobile number, then add it in the e-mail address.
  • Activation: Some carriers require users to activate the e-mail to SMS gateway. Activation info is listed here, if any.

Carrier missing? Find more in these e-mail to SMS gateway lists:

Sections for Include

These sections defines the application logic; the sections are used by UserProfileHeader.

Section carrierlist

The "carrierlist" section returns a comma separated list of carriers listed in this topic; it also sets spreadsheet hashes for later use.

USA: AT&T, USA: Cingular GSM, USA: Cingular TDMA, USA: Cricket, USA: Metro PCS, USA: Nextel, USA: Sprint PCS, USA: T-Mobile, USA: US Cellular, USA: Verizon, France: Orange, France: SFR, Germany: E-Plus, Germany: Mobilis, Germany: Mannesmann M., Germany: O2, Germany: Simyo, Germany: T-Mobile, Germany: Vodafone, Israel: Cellcom, Israel: Orange IL, Israel: Spikko, Netherlands: Dutchtone, Netherlands: Orange-NL, Netherlands: T-Mobile, Switzerland: Sunrise Commun., Switzerland: Sunrise Mobile, Switzerland: Swisscom, UK: O2, UK: Orange, UK: T-Mobile, UK: Virgin Mobile, UK: Vodafone

Section carrierselect

The "carrierselect" section returns an HTML selector with carrier listed in this topic.

Parameters:

  • carrier: Name of select, default: Carrier
  • selected: Carrier to show selected

Section twostepauthselect

The "twostepauthselect" section returns an HTML selector to set Two Step Authentication on or off.

Parameters:

  • selected: Current form field value (on or off)

Section sendsms

The "sendsms" section returns a button with label "Send SMS", or the same text striked-out in case user supplied settings are insufficient. When pressing the button, a modal dialog box with help text and a form to send an SMS is shown.

Parameters:

  • From: Name of person sending SMS
  • Email: E-mail of sender
  • For: Name of SMS recipient
  • Mobile: Mobile number of recipient
  • Carrier: Carrier of recipient

Warning: Can't find topic TWiki06x00.SmsTwoStepAuthContrib

Section sendsmsstriketext

The "sendsmsstriketext" section returns striked-out text "Send SMS", called by "sendsms" section if user supplied settings are insufficient.

Warning: Can't find topic TWiki06x00.SmsTwoStepAuthContrib

Send SMS
To make this site more secure, TWiki uses two-step authentication if you log in from an unknown location. First, log in with your log-in name and password. You will get an SMS with a one-time-use access code. Enter the access code as the second step, which concludes the log-in process.

ALERT! Important: In order to log in with SMS you have to specify a mobile number and select a mobile carrier. Edit your user profile info to do that. Save the settings, then send a test SMS using the "Send SMS" button to verify proper operation.

Section sendsmsdialogbox

The "sendsmsdialogbox" section returns a modal dialog box with help text and a form to send an SMS. This section is called by "sendsms" section if user supplied settings are sufficient.

Parameters are passed via SetGetPlugin variables set in the "sendsms" section.

Section smshelpstyle

The "smshelpstyle" section defines the help styles, used by other sections.

Section help

The "help" section returns a "Mobile carrier missing?" link and a help text as a drop-down on hover over the link. A user can send an e-mail to the TWiki admin to ask to add a missing carrier.

Mobile carrier missing?
To make this site more secure, TWiki uses two-step authentication if you log in from an unknown location. First, log in with your log-in name and password. You will get an SMS with a one-time-use access code. Enter the access code as the second step, which concludes the log-in process.

ALERT! Important: In order to log in with SMS you have to specify a mobile number and select a mobile carrier. Save your settings, then send a test SMS using the "Send SMS" button to verify proper operation.

Let us know in case your mobile carrier missing.

Security Considerations

This extension is primarily intended for access restricted TWiki sites that are installed in a public cloud, such as Amazon AWS. We recommend to install an SSL certificate and to enforce the https protocol.

IP address spoofing cannot be done because establishing an SSL connection requires a handshake. The response to a request is sent to the indicated IP address, and if spoofed, it ends up at the actual address, not the intruder's. Thus a handshake fails because the would-be intruder does not receive the response.

Installation Instructions

You do not need to install anything on the browser to use this extension. These instructions are for the administrator who installs the package on the server where TWiki is running.

Install SmsTwoStepAuthContrib extension

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SmsTwoStepAuthContrib.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SmsTwoStepAuthContrib.txt Contrib documentation topic
      pub/TWiki/SmsTwoStepAuthContrib/*.png Image files
      templates/smstwosteplogin.tmpl Second log-in screen template for SMS
      templates/smstwostepmessage.tmpl Template for SMS message with access code
      templates/smstwostepemaillogin.tmpl Second log-in screen template for e-mail
      templates/smstwostepemailmessage.tmpl Template for e-mail message with access code
      lib/TWiki/Contrib/SmsTwoStepAuthContrib.pm Contrib Perl module
      lib/TWiki/Contrib/SmsTwoStepAuthContrib/Config.spec Configure spec file
      lib/TWiki/LoginManager/SmsTwoStepAuth.pm Login manager for two-step login via e-mail
    • Set the ownership of the extracted directories and files to the webserver user.

  • Patch core TWiki for versions TWiki-6.0.0 and older:
    • Update lib/TWiki/LoginManager/TemplateLogin.pm to the latest version from the SVN repository, http://svn.twiki.org/svn/twiki/branches/TWikiRelease06x00/core/lib/TWiki/LoginManager/TemplateLogin.pm
    • Update lib/TWiki.spec: Below $TWiki::cfg{LoginManager} add the following content, also at http://svn.twiki.org/svn/twiki/branches/TWikiRelease06x00/core/lib/TWiki.spec :
      # **SELECTCLASS none,TWiki::LoginManager::*TwoStepAuth**
      # TWiki can be configured to require two-step authentication, which is more
      # secure because it makes it harder to impersonate a user. The first step is
      # the usual authentication with username and password. After a successful
      # first step, a second authentication step is required in order to log in.
      # The two steps should be of different types, such as something the user
      # <i>knows</i> (username and password), and something the user <i>has</i>
      # (mobile phone with SMS). Two-step authentication currently requires
      # {LoginManager} set to 'TWiki::LoginManager::TemplateLogin'.
      # Available two-step authentication managers:
      # <ol><li>
      # none - Disable two-step authentication.
      # </li><li>
      # TWiki::LoginManager::EmailTwoStepAuth - Use e-mail for second step
      #   authentication. User receives e-mail with one-time-use access code.
      #   Requires installation of EmailTwoStepAuthContrib.
      #   Requires enabling {UseClientSessions} to track client sessions.
      # </li><li>
      # TWiki::LoginManager::SmsTwoStepAuth - Use SMS for second step
      #   authentication. User receives e-mail with one-time-use access code.
      #   Requires installation of SmsTwoStepAuthContrib.
      #   Requires enabling {UseClientSessions} to track client sessions.
      # </li></ol>
      $TWiki::cfg{TwoStepAuthManager} = 'none';

  • Configuration:
    • Run the configure script and open up the Security setup section.
      • The {LoginManager} needs to be set to TWiki::LoginManager::TemplateLogin
      • Set {TwoStepAuthManager} to TWiki::LoginManager::SmsTwoStepAuth
    • Configure additional contrib settings in the Extensions section:
      • White-listed IP addresses, typically used for offices so that employees can log in with a single step at work. Specify a comma-space separated list. Partial IP addresses ending in a dot can be used to specify a range. Example: 1.2.3.4, 5.6.7.
        {SmsTwoStepAuthContrib}{WhitelistAddresses} = '';
      • Maximum age of access code in seconds, default is 600 (10 min):
        {SmsTwoStepAuthContrib}{MaxAge} = 600;
      • Mode of two-step authentication:
        • disabled: Single step authentication.
        • optional: Optional, e.g. user can chose. Attention: The UserForm and UserProfileHeader need to be updated - see instructions below.
        • required: Required for all users. (default)
        {SmsTwoStepAuthContrib}{TwoStepAuth} = 'required';
      • It is possible to send the access code by e-mail instead of SMS if the user has not specified a mobile number and a carrier. Possible values:
        • 0 or empty value: No e-mail sent, user cannot login (more secure).
        • 1: Users with missing mobile and carrier get an e-mail with access code (more flexible).
        • List of users: Specify a comma-space separated list of WikiWord names of users who can get an e-mail. Examples:
          JimmyNeutron - only one specified user
          JimmyNeutron, DonaldDuck - only two specified users
        {SmsTwoStepAuthContrib}{AllowEmail} = '';
      • Name of two-step message template for SMS message:
        {SmsTwoStepAuthContrib}{SmsMessageTmpl} = 'smstwostepmessage';
      • Name of log-in screen template for SMS log-in:
        {SmsTwoStepAuthContrib}{SmsLoginTmpl} = 'smstwosteplogin';
      • Name of two-step message template for e-mail message:
        {SmsTwoStepAuthContrib}{EmailMessageTmpl} = 'smstwostepemailmessage';
      • Name of log-in screen template for e-mail log-in:
        {SmsTwoStepAuthContrib}{EmailLoginTmpl} = 'smstwostepemaillogin';
      • Name of log-in screen template in case of insufficient credentials:
        {SmsTwoStepAuthContrib}{ErrorLoginTmpl} = 'smstwosteperrorlogin';
      • Access code error message:
        {SmsTwoStepAuthContrib}{AcessCodeError} = 'Invalid or outdated access code, please try again.';

Install dependencies

Run configure, and follow "Find More Extensions" in the in the Extensions section to:

  • install or upgrade SendMailPlugin to version 2014-08-20 or later.
  • install or upgrade GeoLookupPlugin to version 2012-11-21 or later. This is optional, used to show the country of the user who is asking the TWiki administrator to add a carrier.

New mobile-carrier and sms icons

In case missing, attach the mobile-carrier.gif mobile-carrier icon and sms.gif sms icon to TWiki06x00.TWikiDocGraphics or Main.SiteDocGraphics and add this to the topic:

| %ICON{mobile-carrier}% | =%<nop>ICON{mobile-carrier}%= | Mobile carrier | gif | 16x16 | |
| %ICON{sms}% | =%<nop>ICON{sms}%= | SMS | gif | 16x16 | |

Update UserForm

The UserForm topic needs to be updated. After the "Mobile" row add this row:

| Mobile Carrier | select | 1 | , %INCLUDE{ "%SYSTEMWEB%.SmsTwoStepAuthContrib" section="carrierlist" }% | Mobile carrier | H |

In case {SmsTwoStepAuthContrib}{TwoStepAuth} is set to 'optional', add the following to the UserForm topic after the "Mobile Carrier" row:

| Two Step Auth | radio | 2 | off, on | Select on to use two-factor authentication | H |

Update UserProfileHeader

The UserProfileHeader topic needs to be enhanced.

1. Add Send SMS button:

After this line:

%BR%%ICON{mobile}% %FORMFIELD{ "Mobile" topic="%INCLUDINGTOPIC%" }% &nbsp;

Add these lines:

%BR%%ICON{sms}% %INCLUDE{
 "%SYSTEMWEB%.SmsTwoStepAuthContrib" section="sendsms"
 From="%FORMFIELD{ "FirstName" topic="%WIKINAME%" }% %FORMFIELD{ "LastName" topic="%WIKINAME%" }%"
 For="%FORMFIELD{ "FirstName" topic="%INCLUDINGTOPIC%" }% %FORMFIELD{ "LastName" topic="%INCLUDINGTOPIC%" }%"
 Email="%FORMFIELD{ "Email" topic="%USERSWEB%.%WIKINAME%" }%"
 Mobile="%FORMFIELD{ "Mobile" topic="%INCLUDINGTOPIC%" }%"
 Carrier="%FORMFIELD{ "MobileCarrier" topic="%INCLUDINGTOPIC%" }%"
}% &nbsp;

2. Add select Mobile Carrier selector:

After these lines:

%ICON{mobile}% <input type="text" name="Mobile" value="%FORMFIELD{ "Mobile" topic="...
%BR%

Add these lines:

%ICON{mobile-carrier}% %INCLUDE{
 "%SYSTEMWEB%.SmsTwoStepAuthContrib"
 section="carrierselect"
 carrier="MobileCarrier"
 selected="%FORMFIELD{ "MobileCarrier" topic="%INCLUDINGTOPIC%" }%" 
}%
<div>
%ICON{empty}% %INCLUDE{ "%SYSTEMWEB%.SmsTwoStepAuthContrib" section="help" }%
</div>

3. Add Two-Step Auth selector:

In case {SmsTwoStepAuthContrib}{TwoStepAuth} is set to 'optional', add these lines after the &lt/div&gt of the previous step:

%ICON{lock}% %INCLUDE{
 "%SYSTEMWEB%.SmsTwoStepAuthContrib"
 section="twostepauthselect"
 selected="%FORMFIELD{ "TwoStepAuth" topic="%INCLUDINGTOPIC%" }%" 
}%

Verify mobile carrier list

Review the #MobileCarriers table above. Add additional carriers if needed.

Test configuration

Test if the configuration is successful:

  • From a location that is white-listed, e.g. has its IP address in {SmsTwoStepAuthContrib}{WhitelistAddresses} do this:
    • Log in with log-in name and password. You should be able to log in with a single step.
    • Edit your user profile topic and specify a mobile number and mobile carrier.
    • A "Send SMS" button should appear below the mobile number.
    • Click on the "Send SMS" button and send yourself an SMS to verify proper operation.

  • From a location that is not white-listed do this:
    • Log in with log-in name and password.
    • You should see an "Enter access code" screen, and get an SMS on your mobile phone with the access code.
    • Enter the access code to complete the second authentication step.
    • Repeat the log-in. This time enter an invalid access code to verify failed log-in and one-time-use of access code.

Contrib Info

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Two-step authentication using SMS for the second step

Author: TWiki:Main.PeterThoeny
Copyright: © 2014 Wave Systems Corp.
© 2014 TWiki:Main.PeterThoeny
© 2014 TWiki:TWiki.TWikiContributor
License: GPL ( GNU General Public License)
Sponsor: Wave Systems Corp.
Version: 2014-09-10
2014-09-22: TWikibug:Item7539: Add {TwoStepAuth} configuration, with 'disabled', 'optional' and 'required' two-step authentication modes
2014-09-11: TWikibug:Item7540: Add debug flag and debug code
2014-09-10: TWikibug:Item7540: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 6.0
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Plugin Benchmark: GoodStyle nn%, FormattedSearch nn%, SmsTwoStepAuthContrib nn%
Home: http://TWiki.org/cgi-bin/view/Plugins/SmsTwoStepAuthContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SmsTwoStepAuthContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SmsTwoStepAuthContribAppraisal

Related Topics: TWikiContribs, TWikiPreferences

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 SmsTwoStepAuthContrib.md5 r4 r3 r2 r1 manage 0.2 K 2014-09-23 - 00:01 PeterThoeny  
Compressed Zip archivetgz SmsTwoStepAuthContrib.tgz r4 r3 r2 r1 manage 188.7 K 2014-09-23 - 00:01 PeterThoeny  
Compressed Zip archivezip SmsTwoStepAuthContrib.zip r4 r3 r2 r1 manage 194.8 K 2014-09-23 - 00:01 PeterThoeny  
Unknown file formatEXT SmsTwoStepAuthContrib_installer r1 manage 4.3 K 2014-09-23 - 00:01 PeterThoeny  
Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2014-09-23 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.