Recent Changes - Search:

Categories

Batch Loading Users Into Portal Guard

Batch Loading users into PortalGuard

Problem: You are interested in batch importing your users into PortalGuard, but are unsure how to do so.


Solution: PortalGuard includes a tool called Batch Importer which can be used to automatically import data for your users such as enrolled phones, email addresses, linked accounts for password synchronization and challenge answers. Listed below are the installation requirements and usage instructions for this component.

Installation Requirements

The PortalGuard Batch Importer is a stand-alone executable that runs on the PortalGuard server. The “PG_BatchImport.exe” file is automatically installed in the “PortalGuard\bin” folder as part of the base installation.

Starting with version 4.0, the Batch Importer can be setup as a scheduled task in Windows for frequent imports. Since this new version is meant to be scriptable from console programs (e.g. adding info for a specific user), the behavior is different from previous versions such that if you double-click the EXE in Windows Explorer it will only allow you to edit the settings, not do an actual import:

Usage Instructions

PortalGuard Batch Importer works by importing your CSV files. A CSV file is simply a text file with .csv as the entension and comma separated values entered as a row in the file for each user.

Here are the supported command line switches:

1. (no switches, launched directly) – The application will launch with a full GUI for configuration. This mode is used to set the administrative credentials under which the actual import process will run. It includes fields for username & password like the previous PG_BatchImport.exe as well as the column headers associated with the fields to be imported. The password is encrypted in a new configuration file so these values can be accessed at run time programmatically during the actual import (HTTP requests are used similar to the previous Batch Import process).

The settings are persisted as “batchimport.settings.xml” in the same folder as the EXE. Similarly, all runtime and audit logs are created in a “Logs” sub-folder so the user identity that launches the import must have privileges to create the “Logs” directory and create new files therein.

The Batch Importer configuration requires the following inputs:

  • The PG server address, e.g. “https://pg.acme.com(approve sites)
  • The name of an administrative user who is allowed to perform batch imports

NOTE: This is controlled in the “Batch Importers” field on the “Policies” tab of the bootstrap configuration:

  • The password for the administrative user
  • The list of data headers that will be imported. Please see the “CSV Headers” section below for all the different CSV header names that correspond to the actual PG user profile fields.

2. –add “<comma-separated value>” – The comma-separated value will be added to a file-based queue for staging multiple imports. This method is preferable to directly updating a CSV file to prevent concurrency issues. The updates to the CSV file are performed using a mutex to ensure each is done atomically. The double-quotes are required if the value contains any spaces, otherwise they would be seen as separate parameters.

When you use the “-add” parameter, it will automatically create an “import.csv” file in the same folder if necessary so the same privilege requirements mentioned in the previous bullet are in effect here as well.

–run – This switch will actually start and run the import process (if creating a scheduled Windows Task, use this parameter as well). The exe uses the same mutex as above to read all import data into memory and clear the on-disk CSV file. The administrative credentials are pulled from the configuration file and all rows from the CSV file are iteratively imported via HTTP calls to the PortalGuard server. A run-time log is generated for each run of the Batch Importer. The level of detail written to the log is configured using the GUI.

–import “<comma-separated value>” – This switch will bypass the CSV file completely and directly import the provided parameter/data row into PortalGuard via a single HTTP call. A run-time log will be generated for this using the same settings as the batched run. The double-quotes are required if the value contains any spaces, otherwise they would be seen as separate parameters.

If you need to move the Batch Importer to other Windows servers you’ll only need to move the EXE – there’s no other file dependency other than the .NET runtime.

CSV Headers If a user does not have data for a specific column, that column should be blank. The list below shows the required fields for each data type. It is acceptable to import multiple data fields for each user (e.g. phones, challenge answers and email address).

NOTE: In the examples below, the 1st line contains all the header values that must be specified in the UI for the corresponding data.

All Data

• Username – The user’s name which must always be the first column and cannot be blank

Challenge Answers (Optional type)

• OptAns – The clear text answer for the question at that index

NOTE: Each field name must be suffixed with increasing numbers from 1 up to 15 Example: Username,OptAns1,OptAns2,OptAns3,OptAns4,OptAns5,OptAns6 user1,cake,green,123 Elm St,smith,celtics,lasagna

Challenge Answers (Mandatory type)

• MandAns – The clear text answer for the question at that index

NOTE: Field name must be suffixed with increasing numbers from 1 up to 5 Example: Username,MandAns1,MandAns2 user1,432,bigbossman

Help Desk/Verbal Authentication answers

• HDAnswer – The clear text answer for the question at that index NOTE: Field name must be suffixed with increasing numbers from 1 up to 5

Example: Username,HDAnswer1,HDAnswer2, user1,8,LDB

Primary Phone

•EnrolledPhone – The phone number. Any spaces or formatting characters will be automatically removed by the PG server

• EnrolledPhoneCanSMS – Set to “1” for mobile phones and “0” for land lines

• EnrolledPhoneCountry - The 2-letter country abbreviation

• EnrolledPhoneProvider – This field is only needed if Email-to-SMS delivery is enabled as the SMS delivery type. This is the telephone provider’s Email-toSMS gateway preceeded by “@”. For Verizon, this value should be “@vtext.com”. For AT&T, this value should be “@txt.att.net”. Example: Username,EnrolledPhone,EnrolledPhoneCanSMS,EnrolledPhoneCountry user1,555-123-4567,1,US

Backup Phone(s)

NOTE: All fields must be suffixed with "1", "2", etc for the additional phones

• BackupPhone – The phone number. Any spaces or formatting characters will be automatically removed by the PG server

• BackupPhoneCanSMS – Set to “1” for mobile phones and “0” for land lines

• BackupPhoneCountry - The 2-letter country abbreviation

• BackupPhoneProvider – This field is only needed if Email-to-SMS delivery is enabled as the SMS delivery type. This is the telephone provider’s Email-toSMS gateway preceeded by “@”. For Verizon, this value should be “@vtext.com”. For AT&T, this value should be “@txt.att.net”. Example: Username,BackupPhone1,BackupPhoneCanSMS1,BackupPhoneCountry1 user1,555-765-4321,0,US

Primary Email (for receiving reminders)

• Email – The full email address for the user Example: Username,Email, user1,user1@acme.com

Alternate Email (for receiving OTPs via Self Service)

• EnrolledEmail – The full alternate email address for the user Example: Username,EnrolledEmail,user1,userpersonal@gmail.com

Password Expiration Date

• ExpirationDate – The date the user’s password should expire. This value must be formatted as YYYY/MM/DD, e.g. 2010/04/01 Example: Username,ExpirationDate, user1,2010/07/07

Linked Accounts (for Password Synchronization)

• linkGUID – The GUID for the user repository from the “Resolution” tab of the PortalGuard “User Repository” configuration.

• linkUsername – The user’s account name in the secondary repository NOTE: This only allows a single repository to be linked per row per user. To link multiple secondary accounts for a single user, put additional repositories as additional lines in CSV file with same "username" value. Example: Username,linkGUID,linkUsername, user1,e2380c35-25ee-46fc-96f7-f37ddcdf8b0c,gxb, user1,735c55db-7db5-49d7-a153-c0ea071501a7,user.one

YubiKey

• YubiKeyName – The name/description for the token.

• YubiKeyID – The 12-character ID for the YubiKey token -OR- an OTP from it NOTE: This only allows a single YubiKey to be registered per row per user. To link multiple YubiKeys for a single user, put additional tokens as additional lines in CSV file with same "username" value. Example: Username,YubiKeyName,YubiKeyID User1,My Test YK, ccccccccccccldctulhghulljgigketlghtgtvfllleg

HMAC-based OTP Tokens

• HOTPLabel – A text description of the token (only shown in the Account Management and/or Administrator Dashboard user lookup)

• HOTPSeed – The base64-encoded secret on the token. Again, this value must be base64-encoded.

• HOTPCounter – The current counter value on the token Example:Username,HOTPLabel,HOTPSeed,HOTPCounter,user1,Token description,cWSfZVHWuTVnbw==,3335

Page last modified on February 03, 2016, at 10:41 AM