py2fa-cli

Calculates and displays time-based one-time passwords (TOTP) for two-factor authentication:

$ py2fa pypi.org
One-time password: 123456 (valid for 13.7 seconds)

Installation

For typical use:

python3 -m pip install py2fa-cli

For development:

git clone https://github.com/arcctgx/py2fa-cli
cd py2fa-cli
python3 -m pip install --editable .

Dependencies

• pyotp
• pyxdg

These dependencies will be installed automatically when py2fa-cli is installed by pip.

Configuration

TOTP secrets are stored in user's XDG configuration directory. Unless you changed your XDG_CONFIG_HOME, that will be .config/py2fa/secrets.json in your $HOME. The secrets file must not be world-accessible (readable, writable or executable): in such case py2fa will refuse to load it.

The secrets file is a dictionary represented in JSON format, e.g.:

{
    "pypi.org": "MYPYPITOTPSECRET",
    "test.pypi.org": "MYTESTPYPITOTPSECRET",
    "example.com": "otpauth://totp/ExampleLLC:you@example.com?secret=HUNTER2&issuer=ExampleLLC&period=15"
}

The dictionary key is what you provide in the command-line, so just use any name that's convenient. The value is the shared TOTP secret in base32 format, or an otpauth:// URI.

A note for Microsoft Authenticator users

It is not possible to extract the shared secret from the Microsoft Authenticator application once it's been configured. You can only obtain the shared secret during the initial setup of the authenticator app.

When setting up 2FA and presented with a QR code, do not scan it directly with Microsoft Authenticator. Instead, use a generic QR code scanner app to retrieve the otpauth:// URI, which will look similar to the example shown above. Store this URI in your secrets.json file. Afterward, you can still scan the QR code with Microsoft Authenticator if desired - both py2fa and the app will generate the same TOTP codes.

A known issue with otpauth:// URIs generated by Microsoft MFA is that they may not fully comply with the URI specification: the issuer parameter may differ from the issuer label. To work around this, you can either manually align the issuer parameter with the issuer label in your configuration file, or simply remove the issuer parameter from the URI.

The example in the Configuration section above shows a compliant URI, where the issuer label (the part immediately following totp/ and before the colon) matches the value of the &issuer= parameter.