ResetPIN How To Guide
From Swivel Knowledgebase Wiki
Contents |
Overview
For the ResetPIN user guide see ResetPIN User Guide For information on the AGENT-XML ResetPIN see AuthenticationAPI#Reset and the Helpdesk AGENT-XML HelpdeskAPI#Reset
The ResetPIN utility version 4038 includes a Mobile Provision Code utility. For information and using and configuring this see: Mobile Re-Provision How to Guide. Appliances 2.0.12 and earlier include the old version of ResetPIN, see below for upgrade information.
ResetPIN may be used by a user to receive a new PIN. The user is directed to a web page where they enter their username and click on request code. They are sent to their mobile phone a request code which they enter into the web page. If this is correctly entered the user is sent a new PIN number to their transport. It is not possible to perform a self reset if the user is locked. If a user has been locked out due to too many incorrect logins, they must contact the helpdesk to be unlocked. Self reset can be used if the user has forgotten their PIN, but has not tried too many times to authenticate. For security reasons the PIN Reset Application does not tell a user their current PIN number.
ResetPIN can be used with dual channel (SMS or email) authentication.
ResetPIN uses XML authentication not RADIUS to authenticate to the PINsafe server.
ResetPIN uses session ID rather than username for authentication, so Allow session request by username is not required.
Changes to the ResetPIN application may be applied by restarting Tomcat.
Additionally there is a IIS version of the ResetPIN application.
ResetPIN has a timeout value and is located under Server -> Jobs -> Session Cleanup (this value also sets the the validity of single channel images and dual channel On Demand security strings).
ResetPIN software
The ResetPIN software can be downloaded from here
To upgrade the ResetPIN software see ResetPIN upgrade for PINsafe 3.8 How To Guide
Installing ResetPIN
ResetPIN is already installed on the Appliances in the webapps2 folder
To install extract from the zip file and copy the resetpin.war file to the webapps folder. It will automatically deploy when Tomcat is running.
Connecting to ResetPIN
Appliance: https://IP:8443/resetpin
software install: http://IP:8080/resetpin
or for the new version
Appliance: https://IP:8443/reset
software install: http://IP:8080/reset
Configuring PINsafe to allow ResetPIN
PINsafe must be configured to allow the ResetPIN utility. On the PINsafe Administration console select Policy/Self-Reset and set the Allow user self-reset to Yes.
Default Configuration files
On an appliance the file is located at:
/usr/local/apache-tomcat-5.5.20/webapps2/resetpin/WEB-INF/settings.xml
The configuration of ResetPIN is in the file settings.xml with the following default values
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <entry key="ssl">false</entry> <entry key="server">localhost</entry> <entry key="port">8181</entry> <entry key="context">pinsafe</entry> <entry key="secret">secret</entry> <entry key="redirect">http://www.swivelsecure.com</entry> </properties>
ResetPIN options explained
ssl: true/false, for communication between ResetPIN and the PINsafe server
server: the PINsafe server hostname for IP address, for communication between ResetPIN and the PINsafe server
port: the port used to communicate with the PINsafe server for IP address, for communication between ResetPIN and the PINsafe server. For a PINsafe appliance this should be 8181, for a software install it should be 8080
context: the install name of the PINsafe application, usually pinsafe for IP address, for communication between ResetPIN and the PINsafe server
secret: the shared secret, must also be entered under Server/Agent on the PINsafe console for IP address, for communication between ResetPIN and the PINsafe server
redirect: redirects on completion of ResetPIN, remove the line for no redirect, this must be an address uses can get to
Additionally the ResetPIN has a limited time in which the Reset Code must be entered. By default this is two minutes, but can be changed the the required value on the PINsafe administration console by selecting Server/Jobs, and setting the Session Cleanup value.
ResetPIN Sample
Entering the ResetPIN request Page
ResetPIN request
ResetPIN Code sent
ResetPIN request Successful
Bulk ResetPIN
It is possible to change large number of users PIN numbers using a list of usernames that you wish to reset in bulk and prepare some XML for the Admin API. Please see the following article section:
http://kb.swivelsecure.com/wiki/index.php/AdminAPI#Reset
Known Issues
If self-reset is enabled, then users who fail the requisite number of login tries are not actually marked as locked, although they are not permitted to log in, so are effectively locked. The reason for this is so that they can use self-reset to unlock themselves.
Unfortunately, because they are not marked as locked, they don't get a message telling them that they have failed login too many times.
Note that users who were locked BEFORE reset pin was enabled WILL be marked as locked, and so won't be able to use reset pin.
If resetPIN is enabled then the automated time based automated account unlock will be disabled.
Troubleshooting ResetPIN
Check the PINsafe logs
If the resetPIN fails when installed on an appliance when using a self signed certificate, verify the port used is 8181 and not 8080.
ResetPIN will not function for PINless users as they have no PIN.
ResetPIN log messages
PINsafe ResetPIN Code sent to user
Message sent to user: graham, destination:
ResetPIN incorrect code entered
Self-reset failed for user: graham.
ResetPIN entered correctly
Self-reset code request successful for user: graham
User requests a ResetPIN code
Self-reset code created for user: graham
ResetPIN correcly entered ans a new PIN has been generated for the user
PIN created for user: graham
ResetPIN error messages
Reset code failed Connection refused: connect
Note: The resetPIN error message given is Reset code failedConnection refused: connect
Incorrectly configured ResetPIN due to wrong PINsafe IP or port
Reset Failed
Incorrect code entered
Reset code failed AGENT_ERROR_RESET_DISABLED
Self-reset code request failed for user: graham, error: User self-reset is disabled.
reset pin has not been enabled. To enable the reset pin on the PINsafe Administration console select reset pin and change Allow user self-reset: to Yes.
Reset Failed AGENT_ERROR_SESSION
Self-reset failed for user: graham, error: A valid session could not be loaded or created for the user.
Note: The resetPIN error message given is Reset FailedAGENT_ERROR_SESSION
The reset pin value has time out. User must use the Reset Code within the session cleanup time. For further information see Session Cleanup
Reset code failed AGENT_ERROR_USER_LOCKED
Self-reset code request failed for user: graham, error: The user account is locked
Note: The resetPIN error message given is Reset code failedAGENT_ERROR_USER_LOCKED
The user account has been locked and a reset pin cannot be performed until the account has been unlocked.
Reset code failed AGENT_ERROR_USER_DISABLED
Self-reset code request failed for user: graham, error: The user account is disabled.
Note: The resetPIN error message given is Reset code failedAGENT_ERROR_USER_DISABLED
The user account has been disabled and a reset pin cannot be performed until the account has been enabled.
