TIP SmsTwoStepAuthContrib is not installed on Foswiki.org.

SMS Two-Step Authentication Contrib Package


Provide 2-factor login authentication using SMS messages.


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 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 (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

   Diagram of two-step log-in process:
Once this extension is installed and configured properly, the log-in process happens as follows:

  • 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.
    • 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.


  • 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. If a user's carrier does not provide an SMS e-mail gateway, use of two-step login will not be possible. (Example: Google Voice does not make a SMS gateway available.)

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:

Section carrierlist

The "carrierlist" section returns a comma separated list of carriers listed in this topic. Access the carrier list using %INCLUDE{"System.SmsTwoStepAuthContrib" section="carrierlist"}%

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 the carrier list as HTML options statements for use in the user registration drop-down, or other forms Access the carrier selection list using %INCLUDE{"System.SmsTwoStepAuthContrib" section="carrierselect"}% .

Security Considerations

This extension is primarily intended for access restricted Foswiki 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.

This extension stores the user's Mobile number in the UserForm. This can reveal mobile numbers if the user's topics are publicly readable.

This extensions sends the security code using email. For best security and to prevent spoofing of email server, sensure that the email server is configured to validate Server Certificates . If Foswiki is sending email directly using Net::SMTP, the setting {Email}{SSLVerifyServer} should be enabled.

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 Foswiki is running.

Install SmsTwoStepAuthContrib extension

  • Configuration:
    • Run the configure script and open up the Security setup section.
      • The {LoginManager} needs to be set to Foswiki::LoginManager::SmsTwoStepLogin
    • 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:, 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.';
    • Note that this extension requires a CGI Session prior to login. If you have turned off guest sessions using the expert setting: {Sessions}{EnableGuestSessions} it needs to be enabled for two-step login to work. The fix for Foswikitask:Item14460 will remove this restriction. This is planned for Foswiki 2.1.5 / 2.2.0.

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 |

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.

  • 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

Related Topics: Contribs, PreferenceSettings, UserAuthentication

Change History

23 Aug 2017 (1.01) - Foswikitask:Item14459: Intial release for Foswiki
2016-01-17: TWikibug:Item7708: Copyright update to 2016
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

Many thanks to the following sponsors for supporting this work:

Topic revision: r2 - 30 Nov 2018, MichaelDaum
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy