Print

Book Contents

Book Index

OATH Tokens

Support for OATH token authentication is available for the web application and management console. No further infrastructure is required for support of this two-factor authentication method when using TOTP tokens; HOTP may require additional elements.

Support for the web application requires that the OATH tokens are configured in the management console (Delegation | Token Configuration...), the web application options to support it are turned on, and that the identity that should require has the option selected in the global delegations (Delegation | Web Application Global Delegation Rules...).

[Enterprise] Random Password Manager provides support for seven different OATH token types:

  • OATH HOTP 6 Digit SHA1
  • OATH HOTP 8 Digit SHA1
  • Prefixed OATH HOTP 6 Digit SHA1
  • Prefixed OATH HOTP 8 Digit SHA1
  • OATH TOTP 6 Digit SHA1
  • OATH TOTP 8 Digit SHA1
  • Yubico OTP

The one-time-password, or OTP, authentication method can be divided into two sub-types. Time-based methods rely on the transformation of a shared secret and a time value that is synchronized between the server and the client. Event-based methods rely on the transformation of a shared secret and an event count that is synchronized between the server and the client. Typically, the event that is counted is the pressing of a button on the token. HOTP Tokens rely on the event driven model. For example, a user with a key-fob or soft-element on their smart-phone presses a button. That device or software is in sync with the OATH server (ERPM/RPM) such that when they press the button, the code generated is the same code that ERPM/RPM comes up with. TOTP tokens rely on a time driven model and are most comparable to RSA tokens where if a physical/or soft device is used, its code is on-screen and changing periodically.

Following is a description of the token assignment dialog and its fields.

OATHEdit01

Select the appropriate token type to use; see the top of this section, OATH Token, for descriptions of each token type. The token type that is selected will determine which options are available. The following text will describe each token option. Once a token is configured and assigned, click Save.

OATH Token Properties

Token Type - Select the token type and number of digits for the token. Both OATH and Yubico formats are supported. OATH tokens come in an event based version known as HOTP and a time based version known as a TOTP. Yubico tokens only come in an HOTP version.

Token ID - This is an 8 digit code that must be unique between tokens. This value is frequently auto-generated by token manufacturers to identify one token from another.

Customer prefix (8 bits) - This is a single byte value that allows token vendors to further qualify tokens by customer. Note that some tokens have the ability to transmit their Token ID and Customer Prefix as well as the token code itself as a long string of digits (i.e. Yubico). In this case, the program will attempt to verify not only the token code (6/8 digits), but also the Token ID and Customer Prefix value. If using a token that only presents 6 or 8 digits (non USB device), then the preceding two fields are not verified and are used for internal accounting only.

Token Key - The Token Key field is used to provide either a 160-bit key for OATH tokens or 128-bit key for Yubico tokens. The field uses decimal encoding where each two digits represent a byte (8-bits) as two hexadecimal digits (00-ff). For an OATH token of 160 bit, this is represented by 40 digits (20 bytes x 8 bits). The OATH token is a random number seed feed into the SHA1 algorithm defined by OATH. Yubico tokens place an AES 128-bit key in this field. This key is unique to each key and is used to decrypt the payload of the Yubico token. Yubico does not present a token value per se, instead it encrypts a token USB insertion count (Session Count) and a key press count during the current session. Note that Yubico has additional user fields for verification. Since the token cannot be decrypted with the wrong AES key, the token is secure. Note that Yubico is an event token only (HOTP).

RFC4226 Button - Pressing this button creates a special test Token Key that is used to confirm the OATH compatibility of HOTP tokens:

"3132333435363738393031323334353637383930"

The seed created is nothing more than the byte equivalence of the ASCII character sequence of "12345678901234567890". In practice, the first few token values for this test token are well known and can be used to make sure that hardware or software is creating the correct token code sequences.

Example: 6 digit RFC4226 sequences:

755224
287082
359152

Example: 8 digit RFC4226 sequences:

84755224
94287082
37359152

Generate Random Key button - This button generates a series of random numbers to create either a 160-bit seed for OATH format tokens, or a 128-bit crypto key for Yubico tokens. When creating tokens for production use, always use the Generate Random Key option or use import seed files generated by a reliable source. Do not create seeds manually by hand as it is essential that the values be completely random.

Token Secret Encoding Type - Encoding type used for the seed.  Valid values are decimal or base64.

Moving Factor Seed - When an OATH HOTP is first programmed, the first token code generally assumed start from zero offset in the SHA1 cryptographic sequence. Some vendors of tokens will start the token off with a random number of initial key press clicks. The thought is that if someone were to get the seed for a token, they would not know where the sequence began (if other than zero). Some token customers feel more comfortable starting tokens at random points in the random sequence generator, so we provide support for the function even it does not provide any significant improvement in security. Generally it is assumed that OATH seeds are secure and there is no need to start the token off at a random starting point in its key press history (the first key press is offset or moving factor = 0).

Last Authentication Check - the last time the user attempted authentication using their token.

Last Authentication Success - the last time the user successfully authenticated using their token.

Last Configuration Time - Last time the token configuration was updated.

Token Unlock Time - if the user has locked themselves out due to failed login times, this is the time at which time they will be unlocked. To unlock the user now, click the Unlock button.

Number of Bad Auth Attempts - the number of times a user can fail authentication before being locked out. A value of 0 means lockout immediately.

Current Sequence Number - This is the current number of key presses recorded against this event token (HOTP). This number starts at zero with a new token and is updated to reflect the last matched key press sequence number. As an example: a brand new token will start with a sequence number of zero. If a user presses the button four (4) times to play around with the token, if they then log in with the fifth (5th) key press on the token, the program will detect that the fifth token code was detected and to expect and accept only token code number six (6) and later. The Current Sequence Number is required to make sure that a user does not reuse an old or previous token code.

Moving Window - Given that a user may inadvertently press the token code, the software needs to account for this and look forward from the last token code. In the default case, the program will accept up to the next 10 token codes from the last one that it successfully authenticated against. In the case of time based tokens (TOTP), this value is split in half to look for tokens 5 steps back in time and 5 steps forward in time, where time is the current time. Note that the program is smart enough to know to not allow the use of time token code values older than the last one correctly authenticated.

Configuration Password - Yubico specific token configuration password to protect token reconfiguration.

Generate Token - button to test token creation and login.

Yubico OTP Properties

Yubico tokens support both the open OATH standard as well as its own proprietary standard called Yubico OTP. This section maintains the current status information if the user has selected and configured a Yubico OTP token. The Yubico native format passes a long stream of encoded characters (called modhex) that contain token identification information, number of times plugged in and the number of times the button was pressed in the current plugged in session.

When using Yubico OTP, all of the token configuration information must match what is stored within this program. Each time the token is used, the data stream is decoded and the token spills the beans on its token identification, number of times the unit has been plugged in, and how many times the button has been pressed. This program checks to make sure that the token information is correct for the current user and the user has not tried to replay a previous string of digits.

Yubico tokens can be delivered fully programmed from Yubico with a seed file ready for import into this program, or blank Yubico tokens can be programmed as OATH or Yubico OTP format.

Session Counter - Last count received from token indicating how many times the token has been plugged into a USB port. The device accumulates an internal counter of how many times it has been plugged into a USB port. For a new token this value will be zero. When the Yubico OTP authenticates successfully against this system, this internal information is decoded, stored and displayed.

User for Session Counter - This is the count of the number of times the button on the Yubico token was last pressed when plugged in and it authenticated with this application. Both of the two previous parameters are normally set to zero for a new token. Once a token has been decoded for the first time, the above two parameters will be set to the discovered values. Only tokens with values of the previous that are greater than the previous usage are accepted. Note that neither of these values can be determined if this program does not have the correct AES key for the token. The encryption key should be different between tokens.

Private Token ID - The string of digits returned contains both clear text and encrypted data. When the token information is decrypted the token ID field identifies the token with an 8 digit number. This field may be pre-configured by the manufacturer, or may be set by the customer when programming blank tokens in the Yubico OTP standard format.

Token Assignment Properties

One easy and quick way to deploy multi-factor authentication is to forgo the use of physical tokens and send users the current token value using an out-of-band communication channel such as email or SMS/text messaging. With this option it is possible to use either the Active Directory email address or pager information for a user to implement multi-factor authentication to send a time based token value that has a limited lifetime of usage (defaulted to 15 minutes to use the token before it expires).

The prerequisites to using this feature:

  1. Configure user tokens for TOTP 6 or 8 digits, generate a random seed, and properly associate the account and its type to the token.
  2. Configure the option to send either email or SMS tokens
  3. Email account must be defined in Active Directory or Active Directory has defined the Pager field for a user to contain the email alias for their SMS/text messaging device. Most pagers and cell phone providers provide an email alias for all phones on their network. The format is generally: PhoneNumber@CarrierGateway.com. See Wikipedia for SMS Gateways to get an updated list of email gateways for carriers worldwide. These user parameters can be set manually using Active Directory administration tools for Users and Computers.
  4. If sending email to a domain outside of the corporate network, it may be required to configure the program’s email configuration to use authenticated email access (to enable email relay). Alternatively, install our standalone email server: SMTP Express (available free from our web site for use with our products) and configure this program’s email configuration to use SMTP Express as a local email gateway to relay email and SMS messages.

Associated User - the user name (login name) that will be used to enter the ERPM/RPM website. If using an explicit ERPM/RPM account, enter the name as UserName. If entering a domain or directory user, enter the name as DirectoryName\UserName.

User Login Format - if the associated user is an explicit account (entered as UserName), the select Username Only. If the associated user is a user from a directory (entered as DirectoryName\UserName), select Username and Authenticator.

Token Comment - a comment for the user/token

Email options - HOTP tokens have nothing to email users as they rely on an external mechanism that is kept in sync with the ERPM/RPM server. TOTP token users must be sent their token. This can happen via an email or SMS message using attributes as found in Active Directory.

Top of Page Print