Integrating Bravura Pass and Phone Password Manager

The following sections outline steps to configure the Phone Password Manager service, and to customize the interaction between Bravura Pass and Phone Password Manager.

Integrating Bravura Pass and Phone Password Manager provides:

Self-service password reset and password synchronization from a telephone
Self-service token management from a telephone
Active enrollment of biometric voice print sample registration

Integration Mechanisms

Bravura Pass exposes APIs suitable for use by an IVR system using HTTPS web access. The API implements strong encryption policies for all connections, allowing you to securely locate the IVR system at a different site from the Bravura Pass server.

Web service

A web service allows IVR systems and other applications to remotely invoke methods on the Bravura Pass server to perform functions such as user and account lookup, security question authentication, random password generation, and to initiate password resets or to clear intruder lockouts. Remote applications normally access the web service over HTTPS for security. Security is also accomplished by use of a secure transport layer, an API user and password, and a one-time-use session ID. Organizations wanting an extra level of security can limit the range of IP addresses that are permitted to access the api to just legitimate IVR systems or other applications.

IVR systems that support integration using web services include those from Intervoice and Nortel/Periphonics.

Example function call sequence

The touch-tone-authenticated password reset process, described here , is implemented by calling the following library functions using any of the API variants described above:

Login – initialize the API session and connect with a valid username and password. Required to start any API session.
UserIVRList – Return a list of users matching a numerical ID. This function returns all users which match the numerical identifier. For more information on mapping users to a numerical ID, see: Mapping user IDs to telephone keypads
UserQuestionsGet – get a random selection of authentication questions that the user might be required to answer. The IVR system must be pre-programmed with speech recordings for every available question, or a text-to-speech engine.
UserAnswersValidate – validate that the answers keyed in by the user are correct.
PasswordRandomGet – called at least once, and possibly several times, to generate a random valid password, and read it out to the user as a possible new password.
UserPasswordSync Reset one or more passwords associated to a user account. Depending on the parameters passed, this call can also allow the user to reset individual passwords, rather than every one.
Logout – close the current API session.

See Bravura Security Fabric Remote API (api.pdf) for more information on writing customized API calls.

Event actions

The following event actions are supported for Phone Password Manager, and can be configured on the Bravura Pass server:

ET_ADMIN_RESET_SUCCESS Triggered when Phone Password Manager successfully attempts to reset a user’s password using the UserPasswordSync API Service call.
ET_ADMIN_RESET_FAILURE Triggered when Phone Password Manager fails an attempt at resetting a user’s password using the UserPasswordSync API Service call.
ET_ADMIN_UNLOCK_SUCCESS Triggered when Phone Password Manager successfully attempts to unlock a user’s account using the UserAccountsUnlock API Service call.
ET_ADMIN_UNLOCK_FAILURE Triggered when Phone Password Manager fails an attempt to unlock a user’s account using the UserAccountsUnlock API Service call.

For more information on using these API Service calls, see Bravura Security Fabric Remote API (api.pdf) .

Editing the configuration file

The Phone Password Manager service uses one of two configuration files, named tpm.cfg or idtel.cfg to determine:

The names of script files that define call flow and logic
Supported languages
Enrollment types
Audio file types
The play back volume adjustment
Dialogic® voice board setup:
- The number of lines supported on the boards
- The type of boards
- The number of boards installed
- Whether or not the boards use SCBus routing
- Any custom tones the boards support (if loop-current detection is not supported)
Dialogic® Host Media Processing Software setup:
- Playback volume levels
- The number of lines supported
- Audio file type
- Audio codec

When you install Phone Password Manager, the installer program automatically detects your IVR system configuration and creates this file in the \<instance>\service\ directory on the IVR server. The idtel.cfg file is only created when a Dialogic® Voice board, or Dialogic® PowerMedia Host Media Processing is detected. The idtel.cfg file is used in place of tpm.cfg to handle calls received from Dialogic® equipment.

You can modify idtel.cfg if your system configuration differs from what was auto-detected, or if you want to modify the default settings. The file includes instructions for modifying each setting in-line as comments.

There are settings within idtel.cfg that only apply to VoIP and softphone systems, which can be found under "VoIP Proxy Server Registration".

You must restart the Phone Password Manager service in order for your configuration changes to take effect.

If you are using a Dialogic® voice board and loop disconnect supervision is provided as a tone or cadence, you can configure Phone Password Manager to detect the condition of the calling party prematurely hanging up. This can be done either by defining the disconnect tone or cadence in idtel.cfg, or by creating a tsf file containing call progress tone information.

If loop disconnect supervision is provided with a loop current drop, it is not necessary to define this information, and the change in line status will be detected automatically if your voice board supports loop current supervision.

Editing the Asterisk® configuration file

Phone Password Manager uses the file asterisk.cfg to determine the following settings when interacting with an Asterisk® server:

The port used to listen for Asterisk® communication.
The IP range to listen for.
The number of channels upon which communication can be accepted.
The list of IP addresses with which communication is permitted.
The name of the Asterisk® server’s audio file directory
If Phone Password Manager should automatically upload files to the Asterisk® server.
Which folders to exclude if auto-uploading is enabled.
Whether or not to keep the temporary files created during auto-upload.
(Optional) Which call logic scripts to run when a call is received from an Asterisk® server.

Phone Password Manager automatically configures this file to the default settings when the Asterisk® module is installed, however you may use these options to restrict which communications your Phone Password Manager server accepts, for the sake of security.

Using 3CX PBX systems

Phone Password Manager is also capable of registering to a 3CX PBX system, in a manner similar to the Dialogic® configuration. To enable a 3CX configuration, alter the idtel.cfg file to include the following settings:

Registration "" = {
  Server = 10.0.1.1
  Realm  = "3CXPhoneSystem" // SIP only
  PhoneNumber = 333
  Password    = "333" // SIP only
}

Setting the Realm = "3CXPhoneSystem" value will enable Phone Password Manager to register a 3CX system when the next call is placed.

Defining disconnect tones in idtel.cfg

Disconnect tones can be explicitly defined within idtel.cfg. To do this:

Create a KVGroup in idtel.cfg with one of the following types, according to the example provided in idtel.cfg:

SingleTone
SingleCadenceTone
DualTone
DualCadenceTone

Populate the KVGroup with the tones, timings, and tolerances provided by the local loop on disconnect. The name of the KVGroup can be arbitrary.
Define the ToneType parameter and set it to the name of the KVGroup defining the tone or cadence.
Restart all the Phone Password Manager services.

Note

This method, called Global Tone Detection , is unreliable on many Dialogic® cards. It is strongly recommended that a tsf file be specified if possible.

Defining disconnect tones with a TSF file

Dialogic® cards can be configured to use a tsf file to recognize call progress tones, including loop disconnect. The contents of this file must be defined according to the environment providing the call progress tones to the voice board. To implement this:

Use the PBX Expert application provided as part of the Dialogic® drivers to discover the call progress tones. It is only necessary to discover the disconnect tones.
Before saving the TSF file, mark the discovered tone set for consolidation, consolidate it, compile it, and enable it. Save it under the Dialogic® data directory.
Use the Dialogic® Configuration Manager to enable tsf file support globally and set the TSF file name to the file you created.
Restart the Dialogic® card.
Restart all the Phone Password Manager services.

If this process was successful, when the Phone Password Manager service starts it will print an informational log message containing the text TSF has been loaded successfully . It will now treat the specified disconnect tones as a loop current off event.

Writing call logic scripts

The Phone Password Manager service uses scripts to determine the logic and flow of each call to the IVR system. These scripts are used to define the workflow of any call received, including which sound files to play to the user, what kind of user input to expect following a prompt, and what operations to perform based on that user input. Descriptions for each section of the script and instructions for customizing the file are included in-line as comments.

The call logic scripts are written in PSLang – a scripting language with a syntax much like C, but with a large set of built-in functions, some of which are specific to Phone Password Manager. The Phone Password Manager-specific functions can:

Interact with the Dialogic® voice boards and Dialogic® PowerMedia Host Media Processing Software.
Interact with the Bravura Pass remote API.
Perform voice print related operations.

Phone Password Manager is shipped with a default script, psynch.psl, that is configured to guide users through log in and authentication using their challenge-response questions stored in Bravura Pass . After login, the script offers users the option to perform password resets, account unlocks, and SecurID token management (If available).

Script files must be located in the \<instance>\script\ directory on the IVR server. If required, you can change the name of the script file or enable multiple script files by modifying idtel.cfg.

To use the VoiceVantage script instead of the DTMF script, rename the psynch.voiceprint.psl sample script to psynch.psl , and put it in the \<instance>\script\ directory.

There are several global variables which can be called from within a call logic script:

Table 1. call logic global variables

Variable	Description
$trunk	An integer representing the current line number for this call.
$lineMode	An integer representing the call mode. Values include: 0 - Auto-answer mode. (Default) 1 - Inbound mode. 2 - Outbound mode. See Call Modes for details.
$supportedLanguages	A space-delimited String containing the languages defined in the configuration file.
$enrollmentTypes	A space-delimited String containing the enrollment types defined in the configuration file.
$callerId	A string containing the caller’s phone number, or URI.
$callerName	A string containing the caller’s name, if available.
$calledId	A string containing the number or URI dialled by the caller.

See also

The PSLang Manual (pslang.pdf) for more information about the PSLang and its Phone Password Manager specific functions.
The Phone Password Manager samples directory for additional call logic scripts, including a script that contains voice-print related operations (psynch.voiceprint.psl).

Managing audio files

Phone Password Manager is shipped with most of the audio files necessary for complete operation in English, however you must provide and configure the audio files for:

Any additional questions that you will add for touch-tone authentication.
The names of any custom target systems available to IVR users..
Any modifications that you will make to the call logic scripts .

Adding custom authentication questions

In order to create custom questions with which to authenticate users of Phone Password Manager, you must configure the question definition on your Bravura Pass instance, and provide an audio file which Phone Password Manager will associate to that question.

Firstly, define your new authentication questions. See IVR with touch-tone authentication for more information on configuring question sets.

When you define the new question, the following conditions must be met:

The description field must be in the format: !!!DEFAULT_PREDEFQSET_<QID>_DESC
A KVG file has been configured in <Instance>\design\custom directory to translate the machine-readable question definition for each language you wish to support.
An audio file exists on your IVR server, in each <Instance>\audio\<Language> directory, titled QD-PREDEFINED_<QID>, that corresponds to the newly defined question.

To properly ID additional questions:

Modify en-us-errmsg.kvg, located in the <instance>\design\src\common directory, to include a new tag for the additional question.
Use the tag ID as the question description.
Generate and install the new skin files.

The vocal should prompt the user to type the answer the question followed by pound; for example, "Enter the year you graduated high school, followed by the pound key."

See User Authentication for details.

Defining custom target systems

You can define prompts for each target system that users can reset their passwords or unlock their accounts for.

These files must be named reset_<target ID>.wav and unlock_<target ID>.wav respectively.

The vocal should prompt the user to perform the action for the specific target system; for example, "To unlock your account on Windows" or "To reset your password on Unix".

Phone Password Manager is shipped with a set of files for these common target systems:

Microsoft Active Directory – reset_AD.wav, unlock_AD.wav
Novell Directory Services (NDS) – reset_NDS.wav, unlock_NDS.wav
Microsoft Windows server – reset_NT.wav, unlock_NT.wav

If you want to use these shipped files, simply rename each file so that the <target ID> portion matches your actual target IDs.

Defining custom target system groups

When a user has accounts in more than one target system group, Phone Password Manager offers them the ability to select those groups when initiating a password reset.

In order to provide the user with a menu from which to select target groups, Phone Password Manager will individually spell out each letter of the custom group’s ID value.

In order to configure a custom audio file to present these target groups to users, create a new audio recording of the target group’s name, and save it to the appropriate <Instance>\Audio\<Language code> directory, depending on the language the audio file will be used for. The name of this file should exactly mirror the target group’s ID value: <Group ID>.wav .

You will need to restart your Phone Password Manager Windows services for the changes to take effect. Additional steps for Asterisk® backends may be required. For more information, see Asterisk® audio files .

Supporting custom call logic

You will need to configure the audio files for any modifications that you will make to the call logic scripts .

If you are not using the default call script, or if you have modified it, ensure that you have appropriate audio files for each PlayFile() or PlayFileEx() function. See the PSLang Manual (pslang.pdf) for more details on these functions.

All audio files used for play back must be stored in the <instance>\audio\<lang>-<locale> directory on the Phone Password Manager server. The value of<lang>-<locale> refers to the language and locale of the user. For example, use en-us for United States (us) English (en).

Additionally, all audio files must be recorded in the format specified in the idtel.cfg file . The default is a MuLaw-encoded, PCM Wave file, with 8 bit sample size, 8kHz sample rate, and 64kbps bit rate. Audio files should always be recorded in monaural format.

Adding additional languages

To add a language:

Add a new Language key-value pair to the idtel.cfg file and restart the Phone Password Manager service.
For example, add the line:
```
Language = fr-ca
```
In psynch.psl, set the value:
```
$selectlang = 1;
```
This value enables the language select menu, which prompts users to select their language preference before entering the main menu.
Create a subdirectory in <instance>\audio\ that matches the language code (<lang>-<locale>) for the language you will be adding.
For example, create a directory named fr-ca, to handle files for Canadian French. This code must match the key-value pair configured in step 1.
Record a complete set of new vocals in the appropriate language, and save the files in the newly created directory. These new files should use the same names as their counterparts in the default en-us folder.
(Optional) Enable language support by extension. Uncomment the following code block in psynch.psl:
```
   // Extension to language mapping table: 
   var $langmapping[]; 
   //$langmapping["777"] = "en-us"; 
   //$langmapping["888"] = "fr-fr";
```
Enabling this code will configure Phone Password Manager to automatically provide service in an alternate language, depending on the phone extension used to dial in to the system.

Phone Password Manager can offer users any number of language options by default. However, if you wish to offer ten or more language options in the same menu, additional configuration is required to allow Phone Password Manager to prompt for, and accept two-button input in the language selection menu.

To help with translations, the vocal-script.txt file in the <instance>\audio\en-us\ directory contains a complete listing of all shipped English-language files and their transcriptions.

HDD Encryption Audio files

Phone Password Manager includes support for Hard Drive Encryption Systems connectors used by Bravura Pass , such as agtmcee6 for McAfee McAfee Endpoint Encryption 6.x.

To support these functions, Phone Password Manager requires the "HDD Encryption Audio files" package to be installed on the system.

The HDD Encryption package includes several audio files which allow Phone Password Manager to properly present to users the HDD Encryption functions.

If the HDD Encryption Audio files package is added to a running installation which uses the Asterisk® backend, a Phone Password Manager service restart is required to help propagate the new audio files to the Asterisk server.

No configuration is required for the HDD Encryption Audio files, as the Phone Password Manager will automatically recognize the relevant agent and play the corresponding audio when required.

Mapping user IDs to telephone keypads

Users identify themselves to the IVR system by typing their IVR IDs on telephone keypads. An IVR ID is the numeric representation of one of their Bravura Pass profile and request attributes. Therefore, each user that logs into the Phone Password Manager system must first exist in Bravura Pass .

You can change the profile and request attribute that is used as a source of users’ IVR IDs by using the TPM ID ATTR option. By default, profile IDs are used as the source of IVR IDs.

If users’ IVR IDs contain punctuation, they should be instructed to skip all punctuation, including # and ⋆, when entering their IDs for validation. For example, the IVR ID O’Hare should be entered as 64273.

Phone Password Manager assumes that telephone keypads are mapped according the current international standard (ITU E.161). If this is not the case at your organization, contact support@bravurasecurity.com for assistance. If Phone Password Manager discovers multiple matching usernames, then all matching users are listed with a maximum of 9 users per page. At the end of any page, you can:

Press 0 to go back and enter another Bravura Pass profile ID.
Press # to repeat the list of users, starting from the first page.

If no selection is made, the next page of users is played. At any time, you can:

Press * to skip all previously played users, and play the remaining users, with a maximum of 9 users per page.

Using multiple Bravura Pass instances with Phone Password Manager

You can use multiple Bravura Pass instances with a single Phone Password Manager server, by adding the LoadInstanceCFG function in the psynch.psl file ; for example:

LoadInstanceCfg("C:\\Program Files\\Bravura Security\\Telephone Password Manager\\My Instance\\script\\mypspushpass.cfg")

Multiple Bravura Pass instances require multiple phone lines or extensions.

In this section: