ResetPIN How To Guide

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.