Microsoft Windows Credential Provider Integration
From Swivel Knowledgebase Wiki
Introduction
Microsoft Windows Credential Provider is used in Vista, Win 7, Windows 2008 and Remote Desktop Gateway. For the user guide see Windows Credential Provider User Guide. For integration with the Windows GINA used in Windows 2000, 2003 and XP see Microsoft Windows GINA login
Users can authenticate using the PINsafe Credential Provider allowing 2FA (Two Factor Authentication), or strong authentication at the Windows Logon. Offline authentication is also supported for single Channel authentication, following at least one successful authentication against the PINsafe server with Third Party Authentication configured.
Prerequisites
PINsafe 3.x Server
Connectivity to PINsafe server during installation (with Third Party Authentication for GINA enabled)
Microsoft Windows Vista, 2008 Server or Win 7
PINsafe Windows Credential Provider 32 bit or
PINsafe Windows Credential Provider 64 bit
A separate PINsafe Credential Provider license is not required, but the users authenticating to PINsafe must be licensed.
Baseline
PINsafe 3.7
Windows 2008 Server R2
Architecture
PINsafe is installed as a Windows Credential Provider, and when a Windows login is made, the authentication is sent to the PINsafe server using XML authentication, or locally if offline authentication is enabled.
Offline Authentication
PINsafe allows offline authentication using single channel but not dual channel authentication. For offline authentication at least one successful authentication must be made against the PINsafe server Third Party Authentication. PINsafe caches a limited number of strings for authentication, and cycles through these so there is no limit on the number of authentications which can be made. PINsafe Account lockout is disabled for PINsafe offline authentication. ChangePIN will not function when the PINsafe server is not contactable.
PINsafe Integration Configuration
Configure a PINsafe Agent
1. On the PINsafe Management Console select Server/Agent
2. Enter a name for the Agent
3. Enter the Credential Provider IP address. You can limit the Agent IP to an IP address range like: 192.168.0.0/255.255.0.0 where the mask of 255 requires an exact match and 0 allows any value, so the previous example would allow any Agent in the range 192.168, or you can use an individual IP address for the Credential Provider.
4. Enter the shared secret used above on the GINA
5. Click on Apply to save changes
Configure Single Channel Access
1. On the PINsafe Management Console select Server/Single Channel
2. Ensure ‘Allow session request by username’ is set to YES
Create a Third Party Authentication
If offline authentication is to be allowed, a third party authentication must be created with an Identifier of WindowsGINA. (Even though the GINA is not part of Credential Provider the third party authentication module is still used and must be configured)
1. On the PINsafe Management Console select Server/Third Party Authentication
2. For the Identifier Name enter: WindowsGINA (Even though the GINA is not used, this must be entered as WindowsGINA)
3. For the Class enter: com.swiveltechnologies.pinsafe.server.thirdparty.WindowsGINA
4. For the License Key, leave this empty as it is not required
5. For the Group select a group of users
6. Click Apply to save the settings
To allow offline authentication to be made a successful authentication must be made with the third party authentication in place.
Microsoft Windows PINsafe Credential Provider Installation
Ensure that the correct PINsafe Windows Credential Provider is used: 32-bit or 64-bit.
On the Microsoft Windows PC or server run the PINsafe executable: PINsafeLogin.exe and click Next to start the install.
Select the required install location: the default install location is: C:\Program Files\Swivel Secure\PINsafe Credential Provider.
If you need to import custom settings, make sure that "Import Custom Settings" is checked, and that the appropriate LoginSettings.xml file is in the same folder as the installation executable. If you do not have custom settings, uncheck "Import Custom Settings". Click on next.
Select the required Start Menu short cut
Check the installation Summary to ensure details are correct, if they are correct click on next otherwise back and edit them.
If you receive a message regarding LoginSettings.xml does not exist. Continue?', then click on Yes.
When the install has completed, ensure tick box is checked for Launch configuration utility to configure the PINsafe instance then click on Finish. For information on the Import functionality see Import below.
Configure PINsafe with the appropriate settings.
If there is a dialogue box giving The settings file "LoginSettings.xml" cannot be found', click ok, the file should be created when the PINsafe Credentials Provider is configured.
Windows PINsafe Credential Provider configuration
The following options are available:
Server: The PINsafe appliance or server IP or hostname
Port: The PINsafe appliance or server port
Context: The PINsafe appliance or server installation instance
Secret: and Confirm Secret: A shared secret which must be entered onto the PINsafe appliance or server
Use SSL The PINsafe server or appliance uses SSL communications
Accept self signed SSL certificates The SSL communication will accept self signed certificates if this is enabled.
Authentication Mode, Always PINsafe authentication is required for remote and local logins
Authentication Mode, Remote Only PINsafe authentication is required for remote logins only
Authentication Mode, Never PINsafe authentication is not used
Show TURing images Show TURing images if requested
Show Request String Show the Request string image to allow the user to obtain a new security string by dual channel
Test Mode With test mode the user can switch user to a standard authentication, see below
Ignore Domain PINsafe will remove any domain prefix (domain\username) or suffix (username@domain) before matching username. This does not affect Windows authentication usernames.
Allow Unknown Users If the username is not recognised by PINsafe, the user can authenticate using Windows credentials only. Any PINsafe OTC entered will be ignored.
If PINsafe unavailable, Fail authentication If the PINsafe server cannot be contacted then authentication will fail
If PINsafe unavailable, Use local authentication If the PINsafe server cannot be contacted a locally generated Turing image can be used for authentication
If PINsafe unavailable, Use standard authentication If the PINsafe server is unavailable use standard authentication, the OTC field is displayed but ignored.
If PINsafe unavailable, Always use local auth A local Turing image is always used and the PINsafe server is not contacted
Test Connection Tests link to PINsafe server, see below for usage.
Export Export settings as an XML file, see Import below.
Verify the settings using the Test Connection Button. A correct configuration should produce a dialogue box with PINsafe Connection settings are correct.
Incorrect settings will produce a dialogue box with Either the PINsafe agent has not been defined, or the secret is wrong
Additional Installation Options
Manually configuring the PINsafe Login
It is recommended to use the PINsafe Login Configuration Tool where possible.
If it is not possible to use the configuration utility the PINsafe Login settings may be edited manually in the registry. The following values found within the "HKEY_LOCAL_MACHINE\SOFTWARE\Swivel Secure\PINsafeLogin" key are used by the Login:
PINsafeServer - The name or IP of the PINsafe server
PINsafePort - The PINsafe server port
PINsafeContext - The PINsafe server context
PINsafeSecret - The PINsafe agent secret
PINsafeProtocol - 1 for https, 0 for http
PINsafeLoginSelect - determines when PINsafe authentication is required: always, remote or disabled.
PINsafeShowTURing - 1 to show the TURing request link, 0 not to
PINsafeRequestString - 1 to show the request string link, 0 not to
PINsafeAllowDefaultLogin - 1 to allow default login if PINsafe unavailable, 0 not to
PINsafeUseLocalAuth - When to use local TURing authentication: always, fallback or never.
PINsafeAllowSelfCert - 1 to allow SSL requests to a PINsafe server with certificate errors, 0 not to
PINsafeDisableFilter - 1 to enable test mode, 0 to hide the standard authentication option
The following values may be seen in this registry key also, but should not be changed:
PINsafeBackgroundsFolder
PINsafeFontsFolder
PINsafeResourceDLL
Uninstaller
Version
Test Mode
In Test Mode the Windows Credential Provider has an additional login that can be used as a standard user login.
Importing Configurations
During installation the PINsafe Credential Provider looks for a file called LoginSettings.xml in the same directory as the installer executable. You can also import settings later by running PINsafeLoginConfig.exe with the full file name as the single parameter, i.e. PINsafeLoginConfig.exe LoginSettings.xml. The format of the settings file is as exported from the configuration app, so typically you would configure one client, export settings, and then keep that file with the installer.
Verifying the Installation
At the windows login a password and OTC login field should be available with Request Image and Request String options available.
If a Dual Channel login is made then the user should be able to enter their OTC. Note the Get Image should not be pressed, otherwise the log will be expecting a Single Channel login for the length of the session timeout (default 2 minutes).
Selecting the Request Image button should generate a Single channel Image for authentication. The PINsafe log should show a session request message: Session started for user: username.
A successful login should appear in the PINsafe log: Login successful for user: username
A failed login should not allow a login, and the following message should be displayed in the PINsafe log: Login failed for user: username
ChangePIN
A user is usually able to change the password by using the Ctrl-Alt-Del keys. With the Windows PINsafe Credential Provider installed, an additional option exists when the Change Password is selected, by clicking on the Other Credentials. This will not function for Offline authentication.
With PINsafe authentication a user never changes enters PIN and this is true for ChangePIN. A user enters their current OTC, and then enters an OTC for what they wish their new PIN to be. PIN enforcement may be in place to the PINsafe server to prevent the choosing of poor PIN numbers.
A user may use a single channel image or a dual channel security string to change their PIN.
A successful Change PIN will show the message Your PIN was changed successfully
The PINsafe server will also display in the logs a changePIN message Change PIN successful for user: username
Uninstalling the PINsafe Integration
Use the Uninstall option from the Program menu, right click on the Windows Credentials provider and click on Uninstall.
Troubleshooting
Test Mode enables you to login using the Standard Windows authentication and not PINsafe authentication. If you disable Test Mode the additional logon users disappear and the machine will then be purely using PINsafe.
If there is a problem then use Windows Safe Mode to login and enable Test Mode again. Safe Mode uses Standard Windows authentication.
To test connectivity to the PINsafe server, open a web browser on the PC or server where the Windows PINsafe Credentials Provider is being installed and attempt to generate a single channel image, a Session request should be seen in the PINsafe logs and a single channel image in the web browser:
Software only install: http://PINsafeserver_IP:8080/pinsafe/SCImage?username=test
Appliance: https://PINsafeserver_IP:8080/pinsafe/SCImage?username=test
PINsafe Login options not displayed
If the "Allow standard authentication" is enabled then PINsafe Login will only display the additional options if it is able to contact the PINsafe server. If PINsafe options are not displayed check the server settings and connectivity to the PINsafe server.
Pressing Ctrl+Alt+Del reverts user back to login screen
A normal login may be attempted after a short period. This can occur as the Windows login screen may appear before a network connection has been made during boot. To prevent the login screen from not being accessible, enable the option in group policy to Wait until network is ready before user logon.
Change Pin is displayed instead of the logon screen
This has been seen on Dell laptops that have the Dell Control Point Security Manager installed. Remove this prior to the Windows PINsafe Credential Provider installation.
FLUSHING_IMAGE_CACHE, ClientAbortException: java.net.SocketException: Connection reset
This error message can be seen in the PINsafe log when a Windows login is attempting to use an animated gif. Turn off animated gifs on PINsafe.
Double User Entry at login, enforced test mode when test mode is disabled
Some fingerprint scanning software may cause this issue, this has been seen on an IBM Thinkpad. Check in the registry under the following
\\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Authentication\Credential Provider Filters
look for keys which have values of: Fingerprint Logon Credential Provider Filter
and
\\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers
look for keys which have values of: Fingerprint Logon Credential Provider
To test if these are the cause, on a test system, either remove the fingerprint software (disabling may still leave the registry keys) or backup the keys by exporting them, then remove them.
Disabling the PINsafe Login
If the PINsafe Login fails to load correctly it can be disabled using the following process:
Using the F8 boot menu start Windows in safe mode
Either run the PINsafe Login Configuration and edit the settings or
Using regedit.exe remove the "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowNT\CurrentVersion\WinLogon\ginadll" registry value
Reboot Windows
Following this process the standard Windows Login should be restored allowing access.
Error Messages
Please enter a one-time code first
A One Time Code was not entered in the OTC field during login.
Either the PINsafe agent has not been defined, or the shared secret is wrong
AgentXML request failed, error: The agent is not authorised to access the server.
The credential Provider is not permitted to connect to the PINsafe server. Add an Agent for communication.
The user name or password is incorrect.
AgentXML request failed, error: No suitable authentication method for the user "Administrator" was found. The user may be missing from the user repository or a synchronisation has not yet occurred.
The user Administrator is not defined as a PINsafe user
Session start failed for user: x, error: No Data for user was found. or error: No data for the user was found
The requested user does not exist in the database. If the user does exist in the repository (e.g. Active Directory) then PINsafe needs to sync with that repository.
Dual channel message request failed, error: On-demand dual channel delivery is disabled.
A dual channel message request was made but the On-demand delivery is not enabled. If it should be enabled, on the PINsafe Administration console select Server/Dual Channel, then set On-demand delivery to Yes.
AgentXML request contained third party data for a third party class that does not exist. Third Party Class ID: WindowsGINA.
and
error: The third party class could not be found.
The Third Party Authentication class does not exist or has been created incorrectly. Create the class, see Create a Third Party Authentication
Failed to change PIN. Please check your credentials and try again.
The user has failed to change the PIN number. This could occur if the PINsafe server cannot be contacted.
Unhandled exception has occurred in your application. If you click Continue the application will ignore this error and attempt to continue. If you click Quit, the application will close immediately.
The remote Server returned an error: (502) Bad Gateway.
This error has been seen when a Test Connection is made from the Credential Provider and can be caused by being unable to connect to the PINsafe server. Check for network settings such as proxy settings on the local server, and if an SSL connection is required.
Known Issues and Limitations
The PINsafe Windows Credential Provider does not support the use of
- BUTton
- PATtern
- Animated gifs
for Single Channel authentication. If a PINsafe server has been configured with a Single Channel login configuration that is not viewable, the following options are available to recover access:
Login using dual channel
Login using an image generated elsewhere such as on the PINsafe Administration console or Taskbar on another server
Alter the settings on the PINsafe server to serve a permitted image
Login offline if permitted
Login to safe mode as described elsewhere
By default, the credential provider assumes that administrator is the local administrator, rather than the domain administrator, so you have to explicitly state the domain name to logon as domain administrator
Installing without Microsoft.Net Framework 3.5
The PINsafe Login itself does not require the .Net Framework - only the configuration utility. Therefore, if you are unwilling to install Microsoft.Net 3.5, you can ignore the warning about this being missing and install the application anyway. However, you will have to configure the application manually, see Manually configuring the PINsafe Login
