PassiveKey

This component is described in the overview section.

Installation Requirements

The following items are required on client workstations for the PassiveKey feature:

  • Windows XP SP3, Vista, Windows 7 or 8 operating system (32 or 64-bit)
  • The .NET Framework 2.0 or later must be installed on the machine
  • Installation must be performed by an administrator
  • Microsoft Internet Explorer 8 or higher (32-bit only)
  • Google Chrome or Mozilla Firefox are supported for “machine-wide” installs

PassiveKey fully supports roaming Active Directory users/profiles. Please note however, that enrollment that occurs on a secondary Windows machine will invalidate enrollment performed previously on any other machines. This will prevent PassiveKey from working on multiple workstations for the same user simultaneously unless the user’s profile data follows them from workstation to workstation.

Installation (Server)

Support for PassiveKey is installed with the base PortalGuard server, but it must be manually configured before it will function properly. The following steps must be performed on the PortalGuard server:

To enable transparent/Kerberos authentication for enrollment, the PortalGuard server must be configured to use Active Directory as its user repository -AND- the user must login to their workstation using an AD domain account. If these requirements are satisfied, then follow the numbered steps in this section.

Otherwise, the user must be prompted to manually enter their credentials when enrollment occurs. In this case, skip down to the steps in the Common Server Configuration section.

  1. Open the “C:\inetpub\PortalGuard” folder and move the “TTT” sub-folder to the “C:\inetpub” folder.
  1. Open “C:\inetpub\TTT\web.config” in a text editor. In line 6, change “deny” to “allow” and save the change. The resulting line should appear as below:

  1. Copy the Global.asax file from the “C:\inetpub\PortalGuard\” folder to the “C:\inetpub\TTT” folder.
  2. Launch the “Internet Information Services (IIS) Manager” from Administrative Tools, right-click the “Sites” node in the left-hand navigator and choose “Add Web Site…”:

  1. Set the following values in the “Add Web Site” dialog:
    1. Site name: TTTEnrollment
    2. Application pool: DefaultAppPool (or the same as the main PortalGuard website if the default was not used)
    3. Physical path: C:\inetpub\TTT
    4. Port: 81

NOTE: The port chosen should not conflict with any existing IIS websites on this server. A specific Host name could be used but that alias must be added to DNS so users can resolve it correctly. Futhermore, this alias must also be added as a servicePrincipalName to the IIS server’s machine account in AD to allow for seamless Kerberos SSO during the user enrollment process. Contact PortalGuard technical support for further information.

  1. In the Features view in the middle frame, double-click the Authentication icon in the “IIS” section:

  1. Disable “Anonymous Authentication” and enable both Basic and Windows authentication:

  1. In the PortalGuard Configuration Editor, edit the Repository document for your directory and open the Resolution tab (the last one on the right side).
  1. Kerberos SSO will result in an authenticated username in the format DOMAIN\username. The domain portion of this username must be removed or PortalGuard’s subsequent searches for the user in Active Directory will fail. Enter “YOUR_DOMAIN\” in the Username Prefix field and ensure the “Remove After Resolution” checkbox remains checked. The trailing backslash must be included at the end of this value to ensure it’s removed properly.

NOTE: Your “old-style” NetBIOS domain name must be used here. You can also add the DNS-style domain name in the Username Suffix field if the PortalGuard logging shows the user has been logged in as the userPrincipalName format (e.g. “@acme.com”).

  1. Save the change and apply it to the running PortalGuard configuration
  1. Continue with the steps in the Common Server Configuration section.

 

Common Server Configuration

  1. Launch the PortalGuard Configuration Editor (PG_Config.exe) and click the “Edit Bootstrap” button.
  1. Under the Policies tab, click the “Generate CA” button

  1. It should result in a “Successfully generated Root CA” message. OK that message, then click the Save button to save the change to the bootstrap configuration.
  1. In the main dialog of PG_Config.exe, click the “Security Policies” tab, then edit the policy for which you wish to enable PassiveKey authentication.
  1. On the policy’s Action -> Login tab, set the “PortalGuard Website Login” drop-down to “Two-factor (2FA)” then ensure “PassiveKey” is checked as an acceptable OTP method.

  1. On the Auth Methods -> PassiveKey tab, ensure “Allow PassiveKey” is checked

  1. Click the Save button to commit the changes.

Installation (Workstation)

The PortalGuard Desktop MSI must be installed on workstations where PassiveKey is to be leveraged. Enrollment in PassiveKey will occur automatically when users login to the workstation once the PortalGuard Desktop is installed.

There are various settings that affect how the PassiveKey enrollment occurs through the PortalGuard Desktop. The required settings are different based on the desired mode of authentication during enrollment.

The following tables show the PUBLIC properties that affect each supported authentication mode. Property values can be set using an MST or when launching the MSI from a command line as shown below:

Example 1

msiexec /i "PortalGuard Desktop.msi" PG_TTT_ENROLL_SERVER=http://islay:81

Example 2 (should be entered without line breaks)

msiexec /i "PortalGuard Desktop.msi" PG_TTT_ENROLL_SERVER=http://malt.pistolstar.com:81/_layouts/PG/PG.ashx PG_RBA_SERVERS=http://malt.pistolstar.com

All properties below are written to the following registry key as the String (REG_SZ) type unless otherwise noted. The registry values can be modified by hand after the install and they will take effect the next time enrollment is attempted.

32-bit or 64-bit OS: HKLM\SOFTWARE\Pistolstar\PortalGuard

For SPNEGO/Transparent Enrollment

Property

Required

Description

PG_TTT_ENROLL_SERVER

Yes

Registry Variable: TTTEnrollServer

The URL to the website that will perform PassiveKey enrollment. The format should be:

http[s]://server

The server name must be listed as a valid SPN in Active Directory -AND- be in either the Trusted Sites or Local Intranet zone in Internet Explorer to ensure SPNEGO succeeds.

PG_RBA_SERVERS

Yes

Registry Variable: RBA_Servers

This is a comma-separated list of the websites for which the PassiveKey cookie will be created and sent. This value can also be set using the CBS_Servers.reg file in the installation steps below.

The format should be:

http://pgdemo.portalguard.net,http://malt.pistolstar.com

IP addresses can also be used as “http://10.10.10.43”.

NOTE: If “https” is used as the protocol, the cookie will only be sent over HTTPS/SSL connections.

PG_TTT_ENROLL_CALLHD

No

Registry Variable: MsgEnrollmentGetOTPFromHD

The instructions displayed to the user if they need to call the Help Desk to obtain an OTP during PassiveKey enrollment.

NOTE: Only displayed if PassiveKey enrollment requires 2FA.

For Manual Login Prompt

Here is the default appearance of the manual login prompt. The text can be customized using properties listed below.

Property

Required

Description

PG_TTT_ENROLL_SERVER

Yes

Registry Variable: TTTEnrollServer

The full URL to the PG.ashx web handler on the standard PortalGuard server (a new website does not need to be created). The format should be:

https://pg.acme.com/_layouts/PG/PG.ashx

PG_RBA_SERVERS

Yes

Registry Variable: RBA_Servers

This is a comma-separated list of the websites for which the PassiveKey cookie will be created and sent. This value can also be set using the CBS_Servers.reg file in the installation steps below.

The format should be:

http://pgdemo.portalguard.net,http://malt.pistolstar.com

IP addresses can also be used as “http://10.10.10.43”.

NOTE: If “https” is used as the protocol, the cookie will only be sent over HTTPS/SSL connections.

PG_TTT_ENROLL_PROMPT

Yes

Registry Variable: LoginPrompt

Must be set to “on” to enable manual login. By default, this value is set to “on” in the MSI. SPNEGO authentication is used if this registry variable is missing or set to a different value.

PG_TTT_ENROLL_LOGGING

No

Registry Variable: EnrollmentLogging

Set to "on" to enable logging to "%APPDATA%\PortalGuard Desktop\TTT\enrollment.log".

PG_TTT_ENROLL_TITLE

No

Registry Variable: LoginPromptTitle

Custom title for login dialog

PG_TTT_ENROLL_INSTR

No

Registry Variable: LoginPromptInstructions

Custom instructions for login dialog. Newlines can be forced using "\n".

PG_TTT_ENROLL_LABELUSER

No

Registry Variable: LoginPromptLabelUser

Custom username label for login dialog

PG_TTT_ENROLL_LABELPW

No

Registry Variable: LoginPromptLabelPW

Custom password label for login dialog

PG_TTT_ENROLL_SUCCESSMSG

No

Registry Variable: LoginPromptSuccessMessage

Custom message displayed when enrollment succeeds

PG_TTT_ENROLL_CALLHD

No

Registry Variable: MsgEnrollmentGetOTPFromHD

The instructions displayed to the user if they need to call the Help Desk to obtain an OTP during PassiveKey enrollment.

NOTE: Only displayed if PassiveKey enrollment requires 2FA.

Common Workstation Configuration

  1. Launch the PortalGuard Desktop MSI as an administrator. Be sure to choose the 32 or 64-bit version depending on the operating system. If you wish to specify any custom values for the PUBLIC properties listed above, the msiexec.exe should be used from a command prompt as shown above or using an MST.
  1. On the Custom Setup dialog, be sure to enable/install the “PassiveKey” feature (it is disabled by default):

  1. If the PortalGuard Desktop feature (which provides account self-service from the Windows logon screen) is enabled, enter the main PortalGuard website name in the next dialog. This is NOT the server that will be used during enrollment. See step 1 above or step 5 below for details on setting that value.
  1. The PortalGuard MSI will attempt to detect if Mozilla Firefox or Google Chrome browsers are installed. If they are successfully detected, you can install the PassiveKey browser add-on for them by checking the appropriate boxes.
  1. Complete the install and prevent the requested reboot by clicking the “No” button on the “You must restart your system…” popup.

NOTE: If you specified the RBA servers and enrollment server with a MST or PUBLIC properties, then skip to step 11 below.

  1. Open the PG Desktop install folder in Windows Explorer (default: C:\Program Files\PistolStar\PortalGuard Desktop)
  1. Edit the “CBS_servers.reg” file in Notepad.

NOTE: This file is named “CBS_servers_x64.reg” on 64-bit systems

  1. Edit the “RBA_Servers” value and put in the main PortalGuard website name. Multiple values can be separated by commas. These are the websites for which the PassiveKey cookie will be created and sent.
  1. Edit the “TTTEnrollServer” value and set it to the IIS website created in step 5 of the Server installation steps above. There must be only a single value.  This step can be skipped if the enrollment server/URL was supplied to the MSI via MST or PUBLIC property. This is the website that will be used for PassiveKey enrollment.

  1. Save the changes and double-click the file as an administrator to merge it into the workstation’s registry.

NOTE: These registry changes can be pushed out automatically via Group Policy.

  1. Restart the workstation and login as the end-user
  1. PassiveKey enrollment should automatically occur when the user gets to their desktop.
  1. Launch a supported web browser and access the main PortalGuard website. The user should be able to login by just providing their username and password despite PortalGuard being configured to require two-factor authentication.

If the user is prompted to enroll a phone or enter an OTP, then either an unsupported browser is used or there was a problem during enrollment. See the PassiveKey section of Chapter 7 for troubleshooting information.

Help Desk Console

This component is described in the overview section.

Installation Requirements

The PortalGuard Help Desk Console (HD Console) runs on the following servers:

  • Microsoft IIS 6.0 or higher (Win2003 or higher)

IIS Installation

The files for the Help Desk Console are automatically installed by the PortalGuard server MSI. The default location is C:\InetPub\PortalGuard\PG_HelpDesk.

Authorize Users

  1. In the User Repository configuration in PG_Config.exe, go to the Help Desk tab. From here you can add usernames as “Global Admins” or create Help Desk regions that have limited visibility/authority within the directory. The value must be the username provided by the Help Desk user when they login to PortalGuard. If PortalGuard is configured to authenticate against Active Directory use the sAMAccountName here.
  2. Save the change to the User Repository – this will automatically update the proper web.config file so IIS allows the user.

Using the Help Desk Console

To access the PortalGuard Help Desk Console, simply open a browser and access the URL:

http://<your-portalguard-server>/PG_HelpDesk/HelpDesk.aspx

NOTE: Substitute the hostname or IP address of your PortalGuard server in the URL above.

  1. When prompted by the PortalGuard UI, log in with an account that was authorized in the Update web.config File section. The HD Console start page opens:

  1. Find the user or users to update. Type the user's last name or username in the Search field to automatically search your LDAP directory. You need to enter at least two characters before the automatic search occurs.
  2. Select the name from the blue box that appears to copy it to the Selected Users field.
  3. Continue this process until all target users are listed. To delete a user, highlight the name in Selected Users and click the Remove button.
  4. Click Next to advance the wizard
  5. Now choose the action you want to perform on the user(s). Only a single action can be performed at a time:

  1. Click Next to advance the wizard or Back to modify the user list
  2. Confirm the action and selected users on the last page. Click Back to modify the user list or action. Click Execute to make the requested changes.

  1. The last page shows the status of the action. Click the Return home link at the top to return to the initial start page.