Difference between revisions of "ResetPIN How To Guide"
m (1 revision imported) |
|
(No difference)
| |
Latest revision as of 12:52, 11 May 2017
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. Virtual or hardware 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, the Reset code and PIN is sent to the users Alert Channel, see Transport Configuration.
- ResetPIN uses XML authentication not RADIUS to authenticate to the Swivel 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 and Password
ResetPIN will also reset a users Swivel password to a blank value. It will not reset a users AD or LDAP password.
ResetPIN software
The ResetPIN software can be downloaded from the Software download page
To upgrade the ResetPIN software see ResetPIN upgrade for PINsafe 3.8 How To Guide
Installing ResetPIN
Virtual or hardware appliances: ResetPIN is already installed on the Appliances in the webapps2 folder
Software Install (Non Appliances): To install extract from the zip file and copy the resetpin.war file to the <path to Tomccat>/webapps folder. It will automatically deploy when Tomcat is running.
Connecting to ResetPIN
Virtual or hardware appliance: https://IP:8443/resetpin
software install: http://IP:8080/resetpin
or for the new version
Virtual or hardware appliance: https://IP:8443/reset
software install: http://IP:8080/reset
Configuring Swivel to allow ResetPIN
Swivel must be configured to allow the ResetPIN utility. On the Swivel Administration console select Policy/Self-Reset and set the Allow user self-reset to Yes.
Send reset code as security string: Yes/No. If set to Yes, then the users reset code will be sent by their security string transport instead of their Alert transport.
Default Configuration files
The configuration file settings.xml file located at:
Virtual or hardware appliance: /usr/local/apache-tomcat-5.5.20/webapps2/resetpin/WEB-INF/settings.xml
Windows Software <path to Tomcat>/webapps/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 version 4038 path is reset/WEB-INF/settings.xml and has the following default configuration file:
<?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">8080</entry> <entry key="context">pinsafe</entry> <entry key="secret">secret</entry> <entry key="redirect">http://www.google.com</entry> </properties>
ResetPIN options explained
ssl: true/false, for communication between ResetPIN and the Swivel server
server: the Swivel server hostname for IP address, for communication between ResetPIN and the Swivel server
port: the port used to communicate with the Swivel server for IP address, for communication between ResetPIN and the Swivel server. For a Swivel virtual or hardware appliance this should be 8181, for a software install it should be 8080
context: the install name of the Swivel application, usually Swivel for IP address, for communication between ResetPIN and the Swivel server
secret: the shared secret, must also be entered under Server/Agent on the Swivel console for IP address, for communication between ResetPIN and the Swivel 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 Swivel 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 Swivel logs
If the resetPIN fails when installed on a virtual or hardware 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
Swivel 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 Swivel 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 Swivel 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.
