Skip to main content  
        iSeries home   |   Easy400  
 Terminal operation
 Browser operation

One Time Password
2-Factor Authentication
by Giovanni B. Perotti (Italy)

This utility is for IBMi applications using user-profile based logins, both in green-screen mode and in WEB mode.
If provides tools for One Time Password (OTP) management and for 2-Factor Authentication (2FA).

1. About One Time Password (OTP)  5. PWDRESET installation
2. About 2-Factor Authentication (2FA) 6. PWDRESET setup
3. Restrictions 7. National Language
4. Prerequisites 8. Updates

1. About One Time Password (OTP)
With this utility, user profile password are assigned by a central Security Administrator. They are One Time Passwords: once the user of a user-profile logs in using the password given by the Security Administrator, he is requested to change his password of one of his choice.
This must be done either from a green screen session or from a WEB browser session. If a user forgets his password, he must then ask a new OTP to his Security Administrator.
The utility provides features for communicating the OTP passwords to the users by e-mail messages and/or SMS's.

2. About 2-Factor Authentication (2FA)
The central Security Administrator, when generating a One Time Password, has the option to enable a 2-Factor Authentication (2FA).
When 2FA enabled, the user, after signing on to his user profile with its password, must ask the utility to generate a secret code and to send it to his mobile phone or to his e-mail address. Once the user receives such a code, he must enter it from his terminal to complete his logon.
This applies both to logons from green screen and to logons from WEB pages.

3. Restrictions
The following restrictions apply:

  1. PWDRESET OPT and 2FA technique can be used only for used profiles exclusively dedicated to single persons.
    Using OTP or 2FA for an user profile shared among a group of people makes no sense.
  2. PWDRESET 2FA technique can be used in a WEB environment only with application initial programs developed using the CCGIDEV2 CGI technique.

    4. Prerequisites

    1. All IBMi Operating System are supported from release V6R1 to release V7R4. Futher releases will have no impact, as the utility has no release dependencies.
    2. Scott Klement's utility LIBHTTP (it is needed to support SMS communications). This is the one needing at least V6R1.
    3. A recent release of utility MMAIL is needed to send e-mail messages and SMS's.
      • MMAIL command EMLPTUMSG is used to send e-mail messages
      • MMAIL SMS feature, based on interfaces to Clickatell fee product. Check out the MMAIL SMS page for main prerequisite information.
      • distributed utility CGIDEV2 (only if interested in providing OTP and 2FA support for WEB pages from CGIDEV2-based HTTP instances).

    5. PWDRESET installation

    1. You must first install the Scott Klement's utility LIBHTTP and generate service programs HTTPAPIR4 and EXPAT in library LIBHTTP.
      Note that this utility requires at least release V6R1.
    2. Then install the MMAIL utility. Use the installation instructions packaged in the dowload file .
    3. Last install the PWDRESET utility. Use the installation instructions packaged in the dowload file .

    6. PWDRESET setup

    1. E-mail message sending
      1. If you are new with MMAIL, you have better to check that yout SMTP configuration (command CHGTCPA) is all right.
        To check it, run command SNDDST to send an e-mail address to an external mail-box (such as amnd make sure that the e-mail message arrives at its destination.
        If it does not, you must fix your SMTP configuration. The MMAIL FAQ page may help you.
      2. Try command MMAIL/EMAILPTUMSG to send and impromptu e-mail message and make sure that the e-mail message arrives at its destination.
      3. In PWDRESET, all the e-mail sending commands MMAIL/EMAILPTUMSG retrieve their sender e-mail address from a record in file PWDRESETDT/SENDERADDR.
        This is a mono-record file, and you must use DFU in order to add to it the e-mail sender address you like to use.
        Before doing that, make sure that such a sender address does work executing some MMAIL/EMLPTUMSG command with that sender address.
      Note - If MMAIL e-mail message sending does not work, you may still use PWDRESET utility, provided that MMAIL can at least send SMS messages.
    2. SMS sending
      1. Install and setup the MMAIL Clickatell SMS service as specified at the approriate MMAIL online manual page and perform all the operations mentioned in point 5. Setting up MMAIL databases for Clickatell SMS integration.
      2. Use command MMAIL/CLICKAT2 to send an SMS via a "Production" Clickatell "integration API key" and make sure that the SMS reacher the destination phone number.
      Note - If MMAIL SMS message sending does not work, you may still use PWDRESET utility, provided that MMAIL can at least send e-mail messages, though e-mail messages may require a longer time to be read.
    3. Enabling the 2-Factor Authentication (2FA) feature
      In order to enable the system to support the 2FA feature, you must signon with a CLASS(*SECADM) user profile and enter command PWDRESET/AUTH2F
                              2-factor authentication (AUTH2F)                        
       Type choices, press Enter.                                
       Enable 2-factor authentication . ACTION    *YES          *YES, *NO
       Clickatell Integration ID  . . . INTEGRID                  
      Figure 1 - Command AUTH2F
      This command can only be run from an user profile with *SECADM special authority.
      Use this command to enable or disable (for all users) the 2-Factor Authentication feature of tool PWDRESET. This feature allows to authenticate logins of given user profiles through codes sent via SMS to users smartphones.
      Prerequisites - To enable this feature, the following is required:
      1. A MMAIL release dated at least August 15 2019 (initial support for Clickatell generated SMS messages)
      2. Command MMAIL/CLICKAT2 must be available
      3. A productive CLICKATELL Interface API must have been bought from Clickatell
      4. The name of this Interface API must have been documented in file MMAILDATA/CLICKAINT.
        You may use page /mmailp/wrksms.pgm of your local MMAIL HTTP instance to display a list of your installed Clickatell Interface API's.
      Note: For a detail presentation of MMAIL support for Clickatell SMS messages, see page .
      Use command PWDRESET/AUTH2FDSP to display the status (enabled / disabled) of the 2FA feature.
    4. HTTP instance
      • PWDRESET 2FA feature can be used only in HTTP instances supporting CGIDEV2-based CGI programs.
      • To use 2FA in a CGIDEV2-compatible HTTP instance of yours, you must add the following HTTP directives:
        ScriptAliasMatch /pwdresetp/(.*)  /qsys.lib/pwdreset.lib/$1
        ScriptAliasMatch /xresetpwd(.*)   /qsys.lib/pwdreset.lib/resetpwd.pgm
        ScriptAliasMatch /xchgpwd(.*)     /qsys.lib/pwdreset.lib/chgpwd.pgm
        ScriptAliasMatch /cgilogon   /qsys.lib/pwdreset.lib/cgilogon.pgm
        Alias /pwdreset/ /pwdreset/
        <Directory /pwdreset>
           Options None
           Require all granted
        <Directory /qsys.lib/pwdreset.lib>
           AllowOverride None
           Require all granted
           Options +ExecCGI
           CGIConvMode %%EBCDIC/EBCDIC%%
        <LocationMatch (^/pwdresetp/(.*)$|^/xresetpwd(.*)$|^/xchgpwd(.*)$)>
          AuthType Basic
          AuthName "PWDRESET utility"         
          PasswdFile %%SYSTEM%%       
          UserID %%CLIENT%%               
          Require valid-user 
        <LocationMatch /pwdresetp/cgilogon.pgm>
          AuthType Basic
          AuthName "CGI logon"
          PasswdFile %%SYSTEM%%
          UserID %%CLIENT%%
          Require valid-user
      • A HTTP instance named PWDRESET is available for test.
        Its HTTP directives are available in IFS stream file '/pwdreset/conf/httpd.conf' .
        To start it enter command STRTCPSVR SERVER(*HTTP) HTTPSVR(PWDRESET) .
        This HTTP instance listens on port 8072. Therefore, in your HTTP browser enther an URL like the following: http://......:8072/pwdreset/html/page1.htm or
        http://......:8072/pwdresetp/cgilogon.pgm .

    7. National language
    During the installation process, HTML pages are copied from IFS directory /pwdreset/html to IFS directory /pwdresetdt/html.
    This last directory is the one actually used in the PWDRESET HTTP instance. Therefore, if you want to have PWDRESET WEB pages in your national language, just translate the HTML pages in directory /pwdresetdt/html. HTML pages in directory /pwdreset/html are your original WEB pages in English language, should something go wrong.

    8. Updates
    To know about the latest updates to this tool, press this link.

    next page