This article provides an explanation of how values in the RSA SecurID software token seed files are related to when tokens go into Next Tokencode Mode. It also explains why a token may be going into Next Tokencode Mode.
Tokens go into Next Tokencode Mode for one or more of the following reasons:
- The first time the token is used for authentication it may require resynchronization.
- The user has entered too many incorrect tokencodes or passcodes.
- The token presented to the RSA Authentication Manager server is outside of the automatic acceptance range. Typically, this would be the expected tokencode, +/- one tokencode from the current time.
- The tokencode that you sent is a correct code, but becomes decrypted incorrectly, and the Authentication Manager server treats it like a failed code. Some reasons for this may be:
- A node secret does not exist between a multihomed or NATed agent,
- A mismatched RADIUS shared secret,
- The authentication agent needs an IP address override configured to force the agent to encrypt traffic to the Authentication Manager server with a specific IP address.
The server request for the next tokencode can be due to a delay between when the user entered the passcode and when the Authentication Manager server received the passcode. For example,
- A user may be entering the passcode on a VPN client that is installed on their computer.
- The VPN client then communicates with a firewall.
- The firewall makes the authentication request on behalf of the user to the Authentication Manager server.
At any stage in this process, there can be a delay, so in order to explain why a token went into Next Tokencode Mode we need the following times:
- The specific time that the user entered the passcode into the VPN client, web page, or agent and pressed OK to send the passcode.
- An Authentication Activity report on the server which shows the timestamp when the server received the passcode.
The tolerances for the viable time windows when tokencodes are acceptable are defined in the token seed record when imported to the Authentication Manager server. They are based on the small, medium, and large windows defined in the token seed XML file.
These values cannot be modified in the xml file. Attempting to change them will cause the importing of the token file to fail.
If you look at the token seed file header, the following text is shown:
- The small window, in seconds, defines the range of codes that are accepted with automatic acceptance.
- The medium window, in seconds, defines the range of codes that force the token into Next Tokencode Mode.
- The large window is used in the following cases:
- This is the first authentication attempt (after a server start);
- The server has been restarted since the last login;
- The token is in New PIN Mode (only set for native PIN token);
- The token is in Next Tokencode Mode AND the client is a single-transaction client;
- The token is in Next Tokencode Mode AND is processing a normal authentication packet;
- This is the first authentication attempt with this token (can only be true for null pin token); or
- The user has entered too many incorrect passcodes. To see the value of this setting, login to the Security Console and browse to Authentication > Policies > Token Policies > Manage Existing. Select the correct policy, and choose Edit. Under Incorrect Passcodes, the value will be set to allow an unlimited number of incorrect passcodes or to require next tokencode after a defined number of incorrect passcodes.
For a SID800 token, the windows are typically defined as:
This corresponds to:
- An automatic acceptance range of +/- 1 minute,
- A Next Tokencode Mode range of [-3,-2 ] and [2,3]
- A large window of [-10, +10]
Software tokens also have these ranges that
are predefined, as in the examples below. The first allows the software token to behave like a hardware token.
In the example here, the predefined ranges are greatly increased. This allows for a device with a software token installed to have somewhat incorrect time.
- Check the version of the RSA Authentication Manager software that is installed on the primary instance and replica instance(s). All Authentication Manager instances should be using the same software version and the latest available software service packs and patches.
- Check replication status between the primary instance and each replica instance(s). Replication failing can cause a problem with end user authentications.
- Check the time difference between the primary instance and replica instance(s). There should not be a difference of more than one to two minutes between any Authentication Manager instances.
- When checking time, use command line and note there are three system clocks to check:
- date -u This checks UTC time and should always be actual UTC time, regardless of time zone. This is the most important clock.
- date This should report local time based on time zone, if a time zone is selected.
- hwclock hwclock should report the same as the date command [local time]. If not, it can be set using hwclock -w and checking again.
The command hwclock is used between replicas to verify the high watermark of tokencodes. In the past, on some earlier version of Authentication Manager 8.2.x, the system could set this incorrectly and you would sometimes see passcode already used errors. This issue was fixed in later Authentication Manager 8.2.x patches.
- Run an authentication activity report and check to see which end user(s) are constantly being prompted for a next tokencode.
- In the authentication activity report, also check which Authentication Manager server is processing end user authentications and which authentication device (RSA Authentication Agent or third-party device, such as Cisco AnyConnect, F5, Palo Alto, etc.) is sending the end user authentications to the servers. Should it be seen that most of the authentications are coming from one agent, a review of the agent configuration may be required, with further authentication testing.
End users entering incorrect passcodes
End users entering incorrect passcodes can invoke Next Tokencode Mode. Updating the Token Policy setting of Incorrect Passcodes
allows users to enter a limited or unlimited number of incorrect passcodes. When the limit is exceeded and
then followed by a correct passcode, users are prompted to enter the next tokencode that is displayed on their token. See Chapter 4 of the RSA Authentication Manager Administrator's Guide
for your version of the software for steps on how to update the Token Policy setting.
Understanding the token synchronization range
The token seed record XML defines the token range of the tokens in seconds. For example,
It is important to note that token seed XML files cannot be modified directly.
You can fine-tune Authentication Manager on the command line to change the acceptable window sizes that affect software tokens only
. These changes have no effect on hardware tokens. Hardware tokens will always use the values in the original seed record for that batch of tokens.
Token synchronization range table
|Token Type||Automatic Range||Accept with Next Tokencode||Maximum Limit|
(3 failures + next code)
|+/- 1 interval|
|+/- 3 interval|
|+/- 10 interval|
|PINPad Tokens||+/- 2 interval|
|+/- 4 interval|
|+/- 10 interval|
|RSA SecurID Software Tokens||+/- 10 interval|
|+/- 12 interval|
|+/- 70 interval|
|Resynchronization (any token)||----||----||+/- 12 hours|
First use of token uses the maximum limit for that type. Typical interval = 1 minute
Relationship between the token seed XML and the token synchronization range table
|<DefMediumWin>||Accept with Next Tokencode|
The DefSmallWin indicates the time interval when a user can successfully enter a tokencode without triggering next tokencode mode (+/- 1 interval or 3 codes). For example, shown here is the UTC time for seven minutes, with the tokencode associated to that minute:
Let us look at some examples. Here we are using the hardware token. The Authentication Manager server host time is 16:25, the server accepts
the three tokencodes for 16:24, 16:25 and 16:26, using the DefSmallWindow setting. The three interval window allows for the tokencode of the server's correct time (+/-0), as well as the correct time one minute ahead of the perfect minute and one minute behind the perfect minute.
Both the DefMediumWin and DefLargeWin indicate longer time intervals when a user will be prompted for the next tokencode (NTC). If the token XML defines the DefMediumWindow synchronization value, the seven tokencodes from 16:22 to 16:28 authenticate successfully. Using DefLargeWindow, all 21 tokencodes between 16:15 and 16:25 would be accepted for authentication. Any tokencode that is
outside of the DefLargeWin range fails
authentication. This has nothing to do with invalid passcodes entered
by the user.
Any tokencode submitted that is outside of the DefLargeWin fails authentication. This has nothing to do with invalid passcodes entered by the user.
Next tokencode and token resynchronization will update the token offset value that is stored in the token record to ensure that the token record remains in the Automatic Range (DefSmallWin) for subsequent authentications. Where the time has a difference of +/- 12 hours, the token offset cannot be updated and authentications fail.
RSA recommends the use of the Network Time Protocol (NTP) with Authentication Manager instances to ensure that the time remains stable. This is because clock changes can impact the token offset, meaning end users are likely to be prompted for next tokencode during an authentication. If there has been a significant clock change (placing the token outside of the maximum limit), then authentications can fail.
Keep in mind that if the Authentication Manager services are restarted, all tokens revert to the DefLargeWindow value for that token type on service restart. This means a token that was using the DefSmallWindow setting is set to DefLargeWindow, until the user first authenticates. Once the user authenticates, the setting returns to how it was configured.
To modify the window values, for software tokens only
, you can add or change values in the ims_config_value table in the database using a command-line utility.
This CLU can never increase the time windows beyond the seed record, they can only decrease or 'tighten up' the acceptable tokencode time windows. This CLU was developed because many years ago software tokens were running on more unreliable system clocks (old PC motherboards, systems without NTP. Smartphones did not exist with accurate clocks or there were other things in the network which could delay the tokencode from arriving at the RSA server, so RSA sometimes shipped out software token seed records with very large small-med-large windows that are no longer relevant if you have a network with accurate time. These large windows allow more successful authentications on unreliable system clocks or ones without NTP. By being able to override the acceptable tokencode windows, the system can be made more secure when you have accurate time on the Authentication Manager server and the user device running the software token, and do not require large default values.
A. Example of a seed record that has narrow timing
|<DefSmallWin>60</DefSmallWin>||120 seconds or 3 intervals|
|<DefMediumWin>120</DefMediumWin>||120 seconds or 3 intervals|
|<DefLargeWin>600</DefLargeWin>||600 seconds or 10 intervals|
B. Example of a seed record that has very wide timing (good for unreliable networks or very old systems with no NTP)
In particular, the CLU described below was designed to 'tighten up' seed values with large windows such as in example B. On reliable networks with reliable time, you may not need to have 72 or 80 possible tokencodes in order to get one valid code sent.
To edit time intervals for RSA SecurID software token seeds
- First load the tokens into the Authentication Manager server.
- SSH to the primary server and login as the rsaadmin user.
- Go to /opt/rsa/am/utils.
- Run one of the rsautil store command to either add or update the configuration; for example:
./rsautil store -a add_config auth_manager.authmethod.st_small_window INTERVAL Global 501
./rsautil store -a update_config auth_manager.authmethod.st_small_window INTERVAL Global 501
In the sample below, the small window value was changed from the default of 660 seconds (11 intervals) to 180 seconds (3 intervals). The INTERVAL value on command line is always the tokencode display interval, not actual seconds. We divided the number of seconds by 60 in the example to get 11 intervals as the maximum.
login as: rsaadmin
Using keyboard-interactive authentication.
Last login: Wed Jan 4 11:09:50 2017 from jumphost.vcloud.local
RSA Authentication Manager Installation Directory: /opt/rsa/am
rsaadmin@am82p:~> cd /opt/rsa/am/utils
rsaadmin@am82p:/opt/rsa/am/utils> ./rsautil store -a add_config auth_manager.authmethod.st_small_window 3 Global 501
Please enter OC Administrator username: <enter name of Operations Console administrator>
Please enter OC Administrator password: <enter password for the Operations Console administrator> psql.bin:/tmp/51e5e785-2ec3-4ed0-bd1f-20442fc0be901743519977922809669.sql:108: NOTICE: Added the new configuration parameter "auth_manager.authmethod.st_small_window" with the value "3"
To change the medium or large window, change the command accordingly, using the examples below.
Use one of the add_config commands below to create these for the first time, or update_config and you are updating the existing value. By default the database does not have windows predefined in the tables, it is based on original seed records imported.
./rsautil store -a update_config auth_manager.authmethod.st_small_window INTERVAL Global 501
./rsautil store -a update_config auth_manager.authmethod.st_medium_window INTERVAL Global 501
./rsautil store -a update_config auth_manager.authmethod.st_large_window INTERVAL Global 501
Regarding the INTERVAL value in the command above, do not use the same exact numbers as seen in the XML file. The number that you use for INTERVAL is relative to the tokencode display interval, not seconds. For example, if the command-line INTERVAL is 10, that means 600 seconds for a 60 seconds token (10 minutes, 10 codes), but 300 for a 30 seconds token (5 minutes, 10 codes). The 30/60 second tokencode display can be changed in some software token profiles before a software token is distributed. Divide the number of seconds from the seed record by 60 for a 1-minute interval token, or 30 for a 30-second interval token to determine how many total intervals exist (and these would be the maximum number interval that you can use on the command-line tool).
This CLU change only affects software tokens. Additionally, this will work only if the number of intervals picked is changed to one smaller than the default XML file intervals (that are contained within the seconds seen in a seed record). See Notes for more information about choosing correct interval numbers for the command-line tool. The tool can tighten up the acceptable codes it cannot increase them.
To undo changes in the database from the command-line utility and restore system defaults
- Access the postgres database command line (see 0000277335 - Connecting to or querying the database using pgSQL in RSA Authentication Manager 8.x for more information).
- You can delete changes using the commands below to restore settings to default:
DELETE FROM ims_config_value WHERE name LIKE '%auth_manager.authmethod.st_large_window%';
DELETE FROM ims_config_value WHERE name LIKE'%auth_manager.authmethod.st_medium_window%';
DELETE FROM ims_config_value WHERE name LIKE '%auth_manager.authmethod.st_small_window%';
DELETE FROM ims_config_metadata WHERE name LIKE '%auth_manager.authmethod.st_large_window%';
DELETE FROM ims_config_metadata WHERE name LIKE '%auth_manager.authmethod.st_medium_window%';
DELETE FROM ims_config_metadata WHERE name LIKE '%auth_manager.authmethod.st_small_window%';
Valid range for each interval value is:
Only a number changed to smaller than what is in the default XML file will work.
- auth_manager.authmethod.st_small_window: between 1 and the default INTERVAL value that is derived from token record seconds value
- auth_manager.authmethod.st_medium_window: between 10 and the default INTERVAL value that is derived from token record seconds value
- auth_manager.authmethod.st_large_window: between 10 and the default value INTERVAL value that is derived from token record seconds value
For example, if the seed for the software token has this in the XML file and the tokencode display interval is 60 seconds:
And you run this command:
./rsautil store -a update_config auth_manager.authmethod.st_small_window 12 Global 501
./rsautil store -a update_config auth_manager.authmethod.st_medium_window 20 Global 501
./rsautil store -a update_config auth_manager.authmethod.st_large_window 20 Global 501
Since 12 is greater than 3 (that is, 120 divided by 60 or 120/60), it uses 3 (120/60) for the authentication windows, not 12. Similarly, it uses 10 (600/60) for a medium window and 20 (1200/60) for a large window, not those you set in the configuration value.
Remember, this affects all software tokens, so if you have deployed 30-second interval tokens, they will behave differently to these interval numbers you choose, than a 60-second interval token.
When invalid values are set, it is adjusted based on following rules during authentication:
- If smaller than the minimum, use the minimum.
- If greater than the default value, use the default.
Warning messages are logged
in system audit log.