Two Factor Authentication

We always work to provide the most secure services possible. We're pleased to offer user-initiated Two Factor Authentication to our SSH, SCP, and SFTP users. This service is OPTIONAL, and can be added or removed as you like. Note that this is considered an advanced feature, so please don't configure it without fully understanding the potential impacts.

Background

Two-factor authentication (2FA) is an authentication mechanism that requires information from a physical token of some kind in addition to your password before granting access. This means that successful 2FA requires both "something you know" (password) and "something you have" (the token). When using 2FA, if your account password is compromised, your account is still protected because it must be used with the token. Conversely, if your token is lost, your password presumably remains secure in your head.

identityVector has evaluated several 2FA solutions, and selected Google Authenticator for our systems. With the Google Authenticator 2FA system, you can use an iOS, Android, Windows, or Blackberry device as a token, as well as several others. Google uses a six-digit code as the token. This token value changes every 30 seconds, based on a mathematical formula.

• For more information on 2FA in general, consult the Wikipedia page at http://en.wikipedia.org/wiki/Two-factor_authentication
• For more information on the Google Authenticator solution, consult the Wikipedia page at http://en.wikipedia.org/wiki/Google_Authenticator
• The code used for our Google Authenticator 2FA can be reviewed at http://code.google.com/p/google-authenticator/

Caveats

• Currently, key-based authentication overrides 2FA on our systems. If you have a valid SSH key authorized for your IVS SSH account, 2FA is ignored entirely.
• Our 2FA configuration is enabled for SSH, SCP, and SFTP access only. No other services have been configured to support 2FA at this time.
• Client-specific notes will be added to this page as they are discovered. If you find a particular client is not working, but one of our supported clients works with 2FA, please let us know the name of the client software.
• The setup process will generate emergency scratch codes that will allow you to access IVS servers without the token. These should be maintained in a safe place. They may only be used once each. If you exhaust your emergency scratch codes, just re-accomplish the setup process.

Escape Clauses

• If you wish to stop using 2FA with your IVS account, simply remove the "~/.google_authenticator" file at any time. Use one of your emergency scratch codes to access the system if needed. If you don't have access to the emergency scratch codes, contact us for help. Be advised that we'll need to authenticate you via phone or other similar means before disabling 2FA for your account. This may take several hours.
• To start over, just remove the "~/.google_authenticator" file and re-accomplish the setup steps detailed below.

Setup Process

To enable 2FA for SSH access to the IVS system, follow these steps:

• SSH to the identityVector system:

Philip-Hagens-iMac:~ phil$ ssh phil@sftp.identityvector.com
This is a private computer system.  Unauthorized users are hereby notified that
there is no expectation of privacy for their actions on this system, and
authorize the system administrators to record all unauthorized traffic for the
purposes of subsequent law enforcement actions.
                                           -IdentityVector Solutions, LLC
Last login: Sat May  5 15:18:03 2012 from c-98-252-9-205.hsd1.de.comcast.net
[phil@quaff ~]$

• Run the "google-authenticator" utility. You'll be asked several questions - the following indicates our supported configuration. You can select any options you like, but you're on your own.

[phil@quaff ~]$ google-authenticator 

Do you want authentication tokens to be time-based (y/n) y
https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth://totp/phil@quaff.identityvector.com%3Fsecret%3D<redacted2>
Your new secret key is: <redacted1>
Your verification code is <redacted2>
Your emergency scratch codes are:
  <code1>
  <code2>
  <code3>
  <code4>
  <code5>

Do you want me to update your "/home/phil/.google_authenticator" file (y/n) y

Do you want to disallow multiple uses of the same authentication
token? This restricts you to one login about every 30s, but it increases
your chances to notice or even prevent man-in-the-middle attacks (y/n) n

By default, tokens are good for 30 seconds and in order to compensate for
possible time-skew between the client and the server, we allow an extra
token before and after the current time. If you experience problems with poor
time synchronization, you can increase the window from its default
size of 1:30min to about 4min. Do you want to do so (y/n) n

If the computer that you are logging into isn't hardened against brute-force
login attempts, you can enable rate-limiting for the authentication module.
By default, this limits attackers to no more than 3 login attempts every 30s.
Do you want to enable rate-limiting (y/n) n

• Save this output - you'll need it to set up the token on your mobile device. Emergency scratch codes should be kept in a safe place in case you lose access to your token and need to access the IVS systems.

• KEEP THIS SSH SESSION OPEN! You'll need it in case something goes wrong. Your failsafe is to remove the "~/.google_authenticator" file from this original SSH session.

• (Optional) Copy the Google URL from the "google-authenticator" command and paste it into a web browser. You'll see a two-dimensional barcode like this:

• Install the Google Authenticator application to your mobile device. Consult your device's App Store for full details. Note that these applications are not provided by IVS - we provide the links strictly as a convenience.
  • Apple iTunes App Store: http://itunes.apple.com/us/app/google-authenticator/id388497605?mt=8
  • Google Play: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
  • Windows Phone 7: http://www.windowsphone.com/en-US/apps/021dd79f-0598-e011-986b-78e7d1fa76f8

• Open the Google Authenticator application on your mobile device and add a new token. The screenshots below are from an iOS device, so your screens may differ.

• Either scan the two-dimensional barcode from your web browser, or enter the account name (free-form text) and Secret Key from the "google-authenticator" command. At this point, you'll see a new 6-digit token on your mobile device's screen. Note the "countdown timer", which indicates how much longer the displayed token is valid. In some software, the token value will turn red or another distinguishing color as it nears expiration.

• From a separate session on your local machine, open another SSH to the IVS system. You'll be asked for a "Verification code" before a "Password". The verification code is your six-digit token, your password is your system account's normal password. After entering both values correctly, you'll be granted shell access as usual.

Philip-Hagens-iMac:~ phil$ ssh phil@sftp.identityvector.com
This is a private computer system.  Unauthorized users are hereby notified that
there is no expectation of privacy for their actions on this system, and
authorize the system administrators to record all unauthorized traffic for the
purposes of subsequent law enforcement actions.
                                           -IdentityVector Solutions, LLC
Verification code: <not echoed>
Password: <not echoed>
Last login: Sat May  5 15:24:27 2012 from c-98-252-9-205.hsd1.de.comcast.net
[phil@quaff ~]$

Troubleshooting and FAQs

• Q: When SSH'ing to the server, I'm not being asked for a "Verification code".
  • A: This most often occurs when you still have public key authentication enabled. Verify that your "~/.ssh/authorized_keys2" file does not contain the public key that corresponds to a private key from your local system account.
• Q: No matter what, I can't authenticate with the token value from my mobile device.
  • A: Check the time settings on your mobile device. Inaccurate clocks will prevent the 2FA process from properly occurring.
• Q: My mobile device's clock is correct and I still cannot authenticate.
  • A: Use one of your emergency scratch codes to authenticate (these are not subject to clock problems), then remove your "~/.google_authenticator" file. Consider re-running the setup process, but answer "N" when asked if you want a time-based authentication token. Please let us know if this happens to you.

Client-Specific Notes

• SSH, SCP, SFTP from command line
  • Any recent version of these utilities should always work, provided the configuration is correct. If you experience any problems with other client software, please attempt to access the server with one of these utilities before contacting us for support.
• Cyberduck GUI SFTP access
  • The "code" and "password" values that Cyberduck asks for are reversed. Enter your six-digit 2FA code in the "password" field, then your normal account password in the "One-time passcode" field on the second dialog box.
• Coda software development
  • Not compatible at this time

Configuration File Syntax

The full documentation for the 2FA code and its documentation can be found on the project page. However, the below section is a comment-documented configuration file that you may find helpful. The contents of the file you generate will be different, and not all options will be listed, and the list shown below is not exhausted.

4THISISNOTREAL2    # Your secret key
" TOTP_AUTH        # option: Use time-based authentication tokens
" RATE_LIMIT 3 30  # option: Limit logins to limit brute-force attacks.  (Not present by default.)
                   # In this case, the same token can be used three times within 30 seconds.
                   # NOTE: identityVector systems already monitor and protect against brute-force
                   #       attacks against SSH and other services. This option is unnecessary.
" WINDOW_SIZE 17   # option: Expand the time window for valid tokens.  (Not present by default.)
                   # In this case, allow tokens from +/-4 minutes (8 prior, 1 current, 8 in future).
" DISALLOW_REUSE   # option: Ensure each token can not be re-used.  (Not present by default.)
                   # This effectively limits logins to once every 30 seconds.
11111111           # the list of emergency scratch codes displayed during initialization
22222222
33333333
44444444
55555555