One-Time Passwords

A one-time password (OTP) is an automatically generated numeric string of characters used in two-factor authentication for a login session, valid only for one login session. Since version 10.135.236, Team Password Manager can generate time based one-time passwords (TOTP).

You can use Team Password Manager as an authenticator for websites and applications that require two-factor authentication.

This document explains how you can create and use one-time passwords in Team Password Manager:

• How to create a one-time password to set up two-factor authentication for a web app
• How to use a one-time password
• API
• Troubleshooting
• Some links

How to create a one-time password to set up two-factor authentication for a web app

To create a one-time password for a web app (or website), do this:

1. Locate the password in Team Password Manager where you want to create the OTP.
2. Go to "Custom Fields". You need Manage permission on the password to do it.
   
3. In a free custom field, enter any label you want (usually the account you're setting up 2FA for) and select "One-Time Password" in the Type field. Then save:
   
4. Go to the web app or website instructions to set up two-factor authentication. You'll be given a QR code and a Secret Key. For now, Team Password Manager cannot use QR codes to create one-time passwords, but you can do it with the Secret Key, which is a string similar to this one: "LKYZEJSPGWE655IL".
5. Edit the password and enter the Secret Key into the custom field you previously set up. Then save:
   
   Note that when if you later edit the password, the Secret Key is shown masked (since v. 10.138.240).
6. Afer saving you'll be taken to the "Data" tab of the password, where you'll see the one-time password you've just created with the icon. Note that a one-time password changes every 30 seconds, with a circle indicating this period:
   
7. Some web apps also provide scratch codes or backup codes in case you can't use the one-time password. You can store these codes in a custom field in the same password entry.

How to use a one-time password

You use a one-time password when you log into a website or web app for which you've previously set up two-factor authentication for. When logging in, after entering the username and password, you're presented with a screen where you need to enter the 2FA code. To do it, go to the password in Team Password Manager where you created the one-time password for the web app and simply copy the code to clipboard using the "Copy to clipboard" button. Then paste it into the web app 2FA form field:

API

Full support for one-time passwords in the API begins with API version 5:

• Show a password (GET /passwords/ID.json): since v. 10.138.240, custom fields of type "One Time Password" return the OTP value at the time of the request in the "data" field:

  "custom_field1": {
      "type": "One Time Password",
      "label": "Ferran's account",
      "data": "267327"
  }

  Note that in v. 10.135.236 custom fields of type "One Time Password" return the secret key in the "data" field and the OTP value at the time of the request in the "otp_value" field.
• Create a password (POST /passwords.json) and update a password (PUT /passwords/ID.json): the data for custom data fields of type "One Time Password" must be the secret key.
• Update custom fields definitions of a password (PUT /passwords/ID/custom_fields.json): the type for one-time passwords is "One Time Password" or "OTP".

In API version 4:

• Show a password (GET /passwords/ID.json): since v. 10.138.240, custom fields of type "One Time Password" return the OTP value at the time of request in the "data" field. Note that in v. 10.135.235 custom fields of type "One Time Password" return the secret key in the "data" field, but they don't return the OTP value.
• Create a password (POST /passwords.json) and update a password (PUT /passwords/ID.json): the data for custom data fields of type "One Time Password" must be the secret key.
• Update custom fields definitions of a password (PUT /passwords/ID/custom_fields.json): the type for one-time passwords is not supported.

Troubleshooting

The most common issue with one-time passwords is that the generated one-time password is incorrect. Normally this is because the server where you're hosting Team Password Manager and/or the client computer from which you're accessing it have the clock out of sync.

Both systems need to get the time automatically from Internet servers for one-time passwords to be generated correctly. So, first you need to make sure that the time settings are set up like this. In the server, you'll probably need to configure ntp (Network Time Protocol) or a similar system. In the client computer check the date and time settings. Second, you need to make sure that both systems (server and client) can reach the external time servers by checking the networking system, firewalls, etc.

Some links

Wikipedia entry for one-time password

Directory of websites and whether or not they support 2FA

2FA in Team Password Manager

Setting up 2FA in Team Password Manager for users

Custom fields in Team Password Manager