SIP Support for Voice Delivery of OTPs

PortalGuard can leverage your existing phone infrastructure to call users with a recorded message that reads their One-Time Passcode (OTP) to them. This functionality supports both mobile phones and landlines.

Requirements

The following items are required for proper operation of SIP delivery:

  • Your phone system must support SIP clients
  • Phone extensions must be created for exclusive use by PortalGuard
  • The PortalGuard IIS website application pool identity must be changed from the default value
  • An exception must be added in the Windows Firewall on the PortalGuard server

Because the PortalGuard module that makes the SIP client connection to the gateway is based on the open source PJSIP project (link), this module is not included in the standard PortalGuard MSI and must be downloaded separately. The URL is below and although it also contains the full source code for PJSIP, the “PG_SIP.exe” file in the root folder is the only required file:

http://www.pistolstar.us/_download/PG/PG_SIP.zip

Extract PG_SIP.exe from the archive above and copy it to the C:\Program Files\PistolStar\PortalGuard\bin directory on the PortalGuard server. Right-click PG_SIP.exe, choose the “Properties” entry and ensure on the General tab that the file does not need to be “Unblocked”. After PG_SIP.exe has been copied, right-click the “bin” folder, and on the “Security” tab, push the ACL down to all the children files to ensure PG_SIP.exe has the proper ACL on it.

As part of this delivery the PortalGuard server will convert the text of the message to a WAV file using a Text-To-Speech API. It then places a call to the user’s phone using an extension from a pool of extensions defined in your phone system for exclusive use by PortalGuard. If you have multiple PortalGuard servers, then each server must have unique extensions for its use. The same SIP-enabled extensions cannot be shared across multiple PortalGuard servers.

In order to leverage the Text-To-Speech runtime, the IIS application pool used by the PortalGuard website may need to run under an identity other than the default. “Network Service” is one identity that will allow the Text-To-Speech to run successfully.

After converting the text to a WAV file, PortalGuard uses a SIP client executable to asynchronously place the call to the user’s phone. Each extension configured for SIP use must specify a unique port that will be used to relay SIP messages from your phone system back to the PortalGuard server.

By default the inbound messages from the phone system will be blocked by Windows Firewall. To fully enable SIP delivery of voice-based OTPs, an exception must be added to the Windows Firewall to allow this SIP traffic. Please use the following steps to do this on the PortalGuard server(s) leveraging SIP delivery:

  1. Under “Control Panel -> System and Security”, click the “Windows Firewall” item
  2. On the left-hand side, click the “Allow a program or feature through Windows Firewall” link

  1. Click the “Allow another program…” button under the list of ports/programs
  2. On the “Add a Program” dialog that appears, use the “Browse” button to find the “PG_SIP.exe” program. By default, it will be in C:\Program Files\PistolStar\PortalGuard\bin.
  3. Click the “Add” button then the “OK” button to save the change which should take effect immediately.

Email Expiration Reminders

PortalGuard has the ability to send reminder emails to users whose passwords are due to expire soon. Multiple emails can be sent to the users as the date of their password expiration approaches. A configurable email body template can include a URL to the PortalGuard server where the user can change their password and perform other account management if needed. There is also a “Test Only” mode where the agent performs all processing but stops short of actually sending the email. When coupled with a high log level or the auditing feature, you can test who would receive the emails without actually sending the notifications.

NOTE: The Windows server on which PortalGuard is installed must be restarted after installation before scheduled tasks will see the new PortalGuard environment variables and run correctly. Unfortunately, Microsoft decided the Task Scheduler service itself should not be started or stopped independently through the Services applet.

The Email Expiration Reminders feature is optional and is disabled by default. Please follow the steps below to configure and enable the feature:

  1. Login to the PortalGuard server as an administrative user
  2. From the PortalGuard root folder (default: C:\Program Files\PistolStar\PortalGuard), open the “bin” folder and launch “Email_Expiration_Reminders.exe”.
  3. Configure the settings as you see fit and save them. Moving the mouse cursor over each field label will show context-sensitive help. The configuration file will be created in “PortalGuard\Policies\Scheduled\Email_Expiration_Reminders.xml”.
  4. As per the NOTE above, restart the PortalGuard server at the operating system level
  5. The next step is to schedule the process to run each day. Launch the built-in Task Scheduler in Windows, installing the appropriate OS features if needed.
  6. In the right-hand Actions list, choose “Create Basic Task”

  1. Enter a Name and Description for the task, e.g. “PortalGuard - Expiration Reminder Emails”

  1. Select the “Daily” trigger option

  1. Choose an early morning time and have it recur every one (1) day

  1. The Action should “Start a program”

  1. Browse to the “PortalGuard\bin” folder and choose the “Email_Expiration_Reminders.exe” file

  1. Choose Finish on the next dialog to complete the task.
  2. The last step is to change the identity under which the scheduled process will run. In the left hand tree, click “Task Scheduler Library” and the scheduled tasks should appear in the middle frame. Click the newly created “PortalGuard” task and then click “Properties” in the right-hand Actions frame.

  1. Click the “Change User or Group…” button and specify the “SYSTEM” account so the process will run under the Local System account. The image below shows the dialog after this change.

  1. Click OK to save the change

The process should now run each day automatically. The History tab of the Windows Task Scheduler can be used to see if there were any errors launching the process. The configuration in step #3 also specifies a Runtime Log Level that can be used to troubleshoot what happened internally during the actual run of the process. A new runtime log file will be created for each day. These logs are created in the “PortalGuard\Logs\Scheduled” folder.

HINT: Windows scheduled tasks can also be run on demand from the Task Scheduler application to expedite the testing of any changes to the email template.