Recent Changes - Search:

TurboVNC Home

About TurboVNC




Developer Info


Related Projects

Using TurboVNC with Time-Based One-Time Passwords (TOTP)

TOTP, as implemented in the OATH Toolkit, provides a means of adding two-factor authentication (2FA) support to the TurboVNC Server.


  1. Install the OATH PAM module:
    • Recent Fedora releases:

      sudo dnf install pam_oath

    • RHEL/CentOS 6 and newer:
      Install the EPEL repository, then

      sudo yum install pam_oath

    • Ubuntu 12.04 LTS and newer:

      sudo apt-get install libpam-oath
  2. RHEL/CentOS 6 only: Create a link for the OATH PAM module under /lib64/security:

    sudo ln -fs /usr/lib64/security/ /lib64/security/
  3. As root, edit /etc/pam.d/turbovnc and give it the following contents:
    • RHEL/Fedora:

      auth requisite usersfile=/etc/users.oath
      account include system-auth
      password include system-auth
      session include system-auth
    • Ubuntu:

      auth requisite usersfile=/etc/users.oath
  4. Set the permissions for /etc/pam.d/turbovnc appropriately.

    sudo chown root:root /etc/pam.d/turbovnc
    sudo chmod 644 /etc/pam.d/turbovnc
  5. For every user who needs to use TOTP, create a unique secret key for that user:

    head -10 /dev/urandom | md5sum | cut -b 1-30
  6. As root, edit /etc/users.oath and give it the following contents:

    HOTP/T30 {user1} - {secret1}
    HOTP/T30 {userN} - {secretN}

    where {secret1} through {secretN} are the per-user secret keys you generated above. Note that the "HOTP/T30" algorithm is appropriate for use with Google Authenticator. If using another TOTP application, then adjust the algorithm accordingly. Refer to this page for more information on the format of /etc/users.oath.
  7. Set the permissions for /etc/users.oath appropriately.

    sudo chown root:root /etc/users.oath
    sudo chmod 600 /etc/users.oath
  8. Install the TurboVNC Server.
  9. Grant setuid permissions to Xvnc (necessary so it can read /etc/users.oath.)

    sudo chmod u+s /opt/TurboVNC/bin/Xvnc
  10. For each user, determine the Base32 version of their secret key.

    oathtool --totp -v {secret}
  11. Instruct each user to create a new account in Google Authenticator using manual entry and to enter their Base32 secret key (from above) as the key for this new account.

That's it. Users should now be able to use Unix Login or VeNCrypt *Plain authentication with the TurboVNC Viewer and enter the token from Google Authenticator as their password.

Optional Refinements

  • To require TOTP for all TurboVNC sessions, adjust permitted-auth-methods (TurboVNC 2.0.x and earlier) or permitted-security-types (TurboVNC 2.1.x and later) in the TurboVNC security configuration file on the server (usually /etc/turbovncserver-security.conf) in order to allow only the pam-userpwd authentication method (TurboVNC 2.0.x and earlier) or only the *Plain and UnixLogin security types (TurboVNC 2.1.x and later.)
  • To require SSH tunneling, add/uncomment no-remote-connections in the TurboVNC security configuration file.
  • To require built-in encryption, specify only the TLSPlain and X509Plain security types in permitted-security-types in the TurboVNC security configuration file (TurboVNC 2.1.x and later only.)
  • To disable reverse connections, add/uncomment no-reverse-connections in the TurboVNC security configuration file. This prevents users from making outbound connections from the server to a listening VNC viewer, which could circumvent the security/authentication restrictions configured on the server.
  • To enable multi-user collaboration using TOTP, add/uncomment enable-user-acl in the TurboVNC security configuration file. Users will now be able to run /opt/TurboVNC/bin/vncpasswd -a {other_user} to grant {other_user} temporary access to their session (authenticated via {other_user}'s TOTP.) /opt/TurboVNC/bin/vncpasswd -r {other_user} can be used to revoke that access.

Creative Commons LicenseAll content on this web site is licensed under the Creative Commons Attribution 2.5 License. Any works containing material derived from this web site must cite The VirtualGL Project as the source of the material and list the current URL for the TurboVNC web site.

Edit - History - Print - Recent Changes - Search
Page last modified on August 01, 2016, at 09:14 AM