Configuring two-factor authentication

Table of contents

You can enable two-factor authentication (2FA) on your npm user account to protect against unauthorized access to your account and packages, either by using a security-key or time-based one-time password (TOTP) from a mobile app.

Prerequisites

Before you enable 2FA on your npm user account, you must:

Update your npm client to version 5.5.1 or higher.
To configure a security-key requires a modern browser that support WebAuthn. This will allow you to configure a biometric devices such as Apple Touch ID, Face ID, or Windows Hello as well as physical keys such as Yubikey, Thetis, or Feitian.
To configure TOTP you will need to install an authenticator application that can generate OTPs such as Authy, Google Authenticator, or Microsoft Authenticator on your mobile device.

For more information on supported 2FA methods, see "About two-factor authentication".

Note: npm does not accept SMS (text-to-phone) as a 2FA method.

Configuring 2FA from the website

Enabling 2FA

On the npm "Sign In" page, enter your account details and click Sign In.
In the upper right corner of the page, click your profile picture, then click Account.
On the account settings page, under "Two-Factor Authentication", click Enable 2FA.
When prompted provide your current account password and then click Confirm password to continue.
On the 2FA method page, select the method you would like to enable and click Continue. For more information on supported 2FA methods, see "About two-factor authentication".
Configure the 2FA method of your choice:
- When using a security-key, provide a name for it and click Add security key. Follow the browser specific steps to add your security-key.
- Below is an example of configuration from Microsoft Edge running on a MacOS
- When using an authenticator application on your phone, open it and scan the QR code on the two-step verification page. Enter the code generated by the app, then click Verify.
On the recovery code page, copy the recovery codes to your computer or other safe location that is not your second factor device. We recommend using a password manager.

Recovery codes are the only way to ensure you can recover your account if you lose access to your second factor device. Each code can be used only once. You can view and regenerate your recovery code from your 2FA settings page. For secondary account recovery options, see "Configuring account recovery options."
Click Go back to settings after confirming that you have saved your codes.

Disabling 2FA for writes

Check the Authorization and writes section for more information on different operations that requires 2FA when this mode is enabled.

Note: As a recommended setting, 2FA for write operations are automatically enabled when setting up 2FA. The following steps explain how to disable it.

On the npm "Sign In" page, enter your account details and click Sign In.
In the upper right corner of the page, click your profile picture, then click Account.
On the account settings page, under "Two-Factor Authentication", click Modify 2FA.
From the "Manage Two-Factor Authentication" navigate to "Additional Options" section
Clear the checkbox for "Require two-factor authentication for write actions" and click "Update Preferences"

Disabling 2FA

If you have 2FA enabled, you can remove it from your account settings page.

Note: You cannot remove 2FA if you are a member of an organization that enforces 2FA. You can view the list of organizations memberships from your profile page under the "Organizations" tab.

On the npm "Sign In" page, enter your account details and click Sign In.
In the upper right corner of the page, click your profile picture, then click Account.
On the account settings page, under "Two-Factor Authentication", click Modify 2FA.
Scroll to the bottom of the "Manage Two-Factor Authentication" page and click Disable 2FA.
Agree to the prompt from the browser.

Configuring 2FA from the command line

Enabling 2FA from the command line

Although security-key with WebAuthn can be used for authentication from both the web and the command line, it can only be configured from the web. When enabling 2FA from the command line, currently the only available option is to use an TOTP mobile app.

Note: Settings you configure on the command line will also apply to your profile settings on the npm website.

If you are logged out on the command line, log in using npm login command.
On the command line, type the npm profile command along with the option for the 2FA mode you want to enable:
- To enable 2FA for authorization and writes, type:
  npm profile enable-2fa auth-and-writes
- To enable 2FA for authorization only, type:
  npm profile enable-2fa auth-only
To add npm to your authenticator application, using the device with the app, you can either:
- Scan the QR code displayed on the command line.
- Type the number displayed below the QR code.
When prompted to add an OTP code from your authenticator, on the command line, enter a one-time password generated by your authenticator app.

Sending a one-time password from the command line

If you have enabled 2FA auth-and-writes, you will need to send the TOTP from the command line for certain commands to work. To do this, append --otp=123456 (where 123456 is the code generated by your authenticator) at the end of the command. Here are a few examples:

npm publish [<tarball>|<folder>][--tag <tag>] --otp=123456
npm owner add <user > --otp=123456
npm owner rm <user> --otp=123456
npm dist-tags add <pkg>@<version> [<tag>] --otp=123456
npm access edit [<package>) --otp=123456
npm unpublish [<@scope>/]<pkg>[@<version>] --otp=123456

Removing 2FA from the command line

If you are logged out on the command line, log in using npm login command.
On the command line, type the following command:
npm profile disable-2fa
When prompted, enter your npm password:
```
npm password:
```
When prompted for a one-time password, enter a password from your authenticator app:
```
Enter one-time password from your authenticator: 123456
```

Configuring account recovery options

When you enable 2FA on your npm user account, we strongly recommend you link your GitHub and/or Twitter accounts to your npm user account. In the event you lose access to your 2FA device and recovery codes, these linked accounts can be used to verify your identity and expedite the recovery of your npm account.

On the npm "Sign In" page, enter your account details and click Sign In.
In the upper right corner of the page, click your profile picture, then click Account.
To link your GitHub account, on the account settings page, under "Linked Accounts & Recovery Option", click Link with GitHub.
On the authorization page, verify all information looks correct. Then click Authorize npm account link.
To link your Twitter account, on the account settings page, under "Linked Accounts & Recovery Option", click Link with Twitter.
On the authorization page, verify all information looks correct. Then click Authorize app.

The Twitter or GitHub account is now linked to your npm account. To remove the link to either account, you can click the Remove button next to the account you want to remove from your npm account.

Resolving TOTP errors

If you are entering what seems to be a valid TOTP but you see an error, be sure that you are using the correct authenticator account. If you have multiple authenticator accounts, using an TOTP from the wrong account will cause an error.

Also, when you reset two-factor authentication after it has been disabled, the authenticator might create a second account with the same name. Please see the authenticator documentation to delete the old account.

Edit this page on GitHub

6 contributors

Last edited by lukekarrys on October 23, 2023