Sentry PIN Management


This document describes the software provided by Swivel Secure in order to manage PIN expiry for Sentry users.


The tools provided assume that Sentry version 4.1.3 is currently being used, which is the version understood to be in use currently at Archer. However, it should work with earlier versions of 4.1. It will also work with version 4.2.x with one change described below.

It should be noted that Sentry does not currently support custom PIN expiry for individual users or groups of users. The PIN expiry duration is fixed for all users, with the proviso that individual users can be made exempt from PIN expiry (“PIN Never Expires”). It is proposed, therefore, that PIN expiry is managed by examining the current ages of PINs for users and setting the PIN expiry so that those users with the oldest PINs can be required to change them, given sufficient warning. So that the number of expiring PINs can be managed, the “PIN Never Expires” policy can be set for some of these users, to exempt them temporarily.

Tools Provided

There are two items provided to manage this process:

PIN Management Software

This is a custom-built Windows program that can monitor users’ PIN age and selectively set or reset the PIN Never Expires flag for users in bulk. This will be described in more detail below.

PIN Change Report

The above software relies on the output from a Sentry report. This report will be described below.

Preparation on Sentry

In order to prepare for this process, the following will need to be done:

  • Create an Agent for the Windows computer that will run the custom software. This needs the IP address of the computer, and a pre-defined secret, which needs to be entered both in Sentry and the application. If the software needs to be run on several computers, this can be managed with a single Agent provided all computers share a common netmask. Otherwise, multiple Agents will need to be created. Agents are managed under Server -> Agents.
  • Check the PIN expiry policies under Policy -> PIN and OTC. In particular, “PIN expiry (days)”, “PIN expiry after auto/admin reset (days)” and “PIN expiry warning (days)”. The software assumes that PIN expiry after admin reset is the same as after user reset, so if you prefer these to be different, this will need to be changed once the policy is fully in place. Otherwise, leave this at zero, which means the same as user reset. PIN expiry warning should be set to, for example, 7 days, to give users time to reset their PIN. PIN expiry shouldn’t be changed yet, until the user data is examined.
  • Archer have requested that the user portal link is included in the PIN expiry warning message. Swivel Secure can work with Archer IT management to change the email template for this.
  • The PIN change report needs to be installed. This is described next.

The PIN Change Report

The following is the report that needs to be inserted:

<report name="pinchangedates">
             <title>All users with last PIN change dates</title>
             <description>Lists all users with the created, last PIN change, last PIN reset, last admin reset and PIN never expires flag</description>
             <fields>U.H, A1.D, A2.D, A3.D, A4.D, S.B</fields>
             <tables>PINSAFEJ U join PINSAFEN A1 on U.G=A1.A and A1.C=3 left outer join PINSAFEN A2 on U.G=A2.A and A2.C=1 left outer join PINSAFEN A3 on U.G=A3.A and A3.C=2 left outer join PINSAFEN A4 on U.G=A4.A and A4.C=6 join PINSAFEC S on U.G=S.C and S.B=3</tables>

To insert this, you need to edit the following file: /home/swivel/.swivel/conf/reports.xml

You can either edit this file from the appliance command line (if you have the password), or using WinSCP or a similar tool. Go to the bottom of the file and insert the above lines just before the closing “</reports>” tag.

NOTE: for version 4.2 the <tables> element is slightly different:

<tables>PINSAFEJ U join PINSAFEN A1 on U.G=A1.A and A1.C=3 left outer join PINSAFEN A2 on U.G=A2.A and A2.C=1 left outer join PINSAFEN A3 on U.G=A3.A and A3.C=2 left outer join PINSAFEN A4 on U.G=A4.A and A4.C=6 join PINSAFES S on U.G=S.A</tables>

It is not necessary to restart Tomcat to enable this report. Once the report has been inserted, go to Reporting -> Instant and you should find this report at the bottom of the list.

To prepare the Windows application, you need to select this report, then Run it using the “Run Report” button.

Once the report has been run, select the “Export as XML” button. The report will be downloaded as “reporting.xml”, or if this file already exists in your Downloads folder, as reporting (1).xml. Copy the file to a convenient location to be read by the application, as described next.

The PIN Change Management Application

This is a relatively simple Windows application that summarises the PIN ages for all users and allows you to set or reset PIN Never Expires for a selection of users. The program is named “PINChangeManagement.exe”. [Insert installation process here].

The first time you run the program, you will first need to configure the Sentry settings using the following dialog:


Set the Sentry server name, port etc. as required, plus the Agent secret you used earlier. You can test if the settings are correct using the “Test” button. Note that “Test” also saves the settings, as does “Close”. The difference is that “Close” also closes the settings dialog. “Cancel” closes the settings dialog without making any changes.

The PIN expiry and warning settings do not relate directly to the Sentry settings. You can set these as you wish, and the displays will indicate which users would have expired based on the chosen settings. Setting PIN expiry to 0 disables this feature.

The next step is to import the report output you generated above. Browse to the location you stored it in and select it.

Once you have completed these steps the first time, you will not be prompted for them automatically, but you can change the settings if required, and you will need to import new reports as users start to reset their PINs.

The main form of the program looks like this:


It displays a list of ranges indicating the PIN ages and the number of users with ages in that range.

The ranges are set automatically, depending on the maximum PIN age:

  • If the maximum age is less than 50, ranges will be multiples of 5 days
  • If the maximum age is less than 200, ranges will be multiples of 10 days
  • If the maximum age is less than 1000, ranges will be multiples of 50
  • If the maximum age is 1000 or higher, ranges will be multiples of 100

Note that if no users are within a particular range, that range will not be shown.

If you set PIN expiry, the display will change. For example, if you set PIN expiry to 800 and Warning to 7, you will see this.

  • A white line (blue if selected) indicates that all users in this range have PINs that are OK.
  • A yellow line indicates that some users in this range may be in the warning range
  • An orange line indicates that some users in this range may have expired
  • A red line indicates that all users in this range have expired

The menu items are as follows:

Sentry -> Reload Summary: reloads the report from the stored one.

Sentry -> Import Summary: prompts for a file name to import a new report to replace the existing one

Sentry -> Include PIN Never Expires: this is a toggle option. By default, users that have “PIN Never Expires” are excluded from the summary, but enabling this option will include them in the counts.

Settings -> Edit Settings: displays the settings dialog to enable you to change them

When you click on the Count item for any range, a new dialog will appear showing the users within this range:


You can select any number of these users and click “Enable Expires” or “Never Expires” to turn “PIN Never Expires” off or on. Buttons are provided to allow you to select all or none of the users, and to invert the selection. Note that this change affects the Sentry users as well as the local status in the offline report.

If PIN Expiry is set, users are coloured to indicate their status:

  • Users that have not expired are shown in White, or Blue if selected
  • Users that are in the warning period are in Yellow, or Brown if selected
  • Users that are beyond the expiry time are in Red, or Purple if selected
  • Users that have PIN Never Expires set are in Light Green, or Dark Green if selected