kartykp/upgrade-path-to-regex
@reggi/path-to-regexp
dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2
dependabot/npm_and_yarn/main/eslint-10.4.0
dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0
dependabot/npm_and_yarn/main/proc-log-7.0.0
dependabot/npm_and_yarn/npm_and_yarn-826852524d
dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2
deprecate-totp-2fa
dhei/classic-tokens
gat-bypass-2fa-docs
jpg619/fix-accessibility-content-flow
jpg619/version-bump-tar-2
kartykp/gat-bypass-2fa-docs
kartykp/upgrade-path-to-regex
main
maitxn/version-bump-tar
patch-1
reggi/cache-based-on-version
reggi/dev-engines
reggi/fix-transform-prettier
reggi/overrides
update-search-sensitivity
| 1 | --- |
| 2 | title: Configuring two-factor authentication |
| 3 | --- |
| 4 | |
| 5 | import shared from '~/shared.js' |
| 6 | |
| 7 | 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][webauthn] or [time-based one-time password (TOTP)][totp] from a mobile app. |
| 8 | |
| 9 | ## Prerequisites |
| 10 | |
| 11 | Before you enable 2FA on your npm user account, you must: |
| 12 | |
| 13 | - Update your npm client to version 5.5.1 or higher. |
| 14 | - To configure a security-key requires a modern browser that support [WebAuthn][can-i-use]. This will allow you to configure a biometric devices featuring Apple [Touch ID][touch-id], [Face ID][face-id], or [Windows Hello][windows-hello] as well as physical keys such as [Yubikey][yubikey], [Thetis][thetis], or [Feitian][feitian]. |
| 15 | - To configure TOTP you will need to install an authenticator application that can generate OTPs such as [Authy][authy], [Google Authenticator][google-authenticator], or [Microsoft Authenticator][microsoft-authenticator] on your mobile device. |
| 16 | |
| 17 | For more information on supported 2FA methods, see "[About two-factor authentication][about-two-factor-authentication]". |
| 18 | |
| 19 | <Note> |
| 20 | |
| 21 | **Note:** npm does not accept SMS (text-to-phone) as a 2FA method. |
| 22 | |
| 23 | </Note> |
| 24 | |
| 25 | ## Configuring 2FA from the website |
| 26 | |
| 27 | ### Enabling 2FA |
| 28 | |
| 29 | 1. <>{shared['user-login'].text}</> |
| 30 | |
| 31 | <>{shared['user-login'].image}</> |
| 32 | |
| 33 | 2. <>{shared['account-settings'].text}</> |
| 34 | |
| 35 | <>{shared['account-settings'].image}</> |
| 36 | |
| 37 | 3. On the account settings page, under "Two-Factor Authentication", click **Enable 2FA**. |
| 38 | |
| 39 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-enable.png" alt="Screenshot showing Enable 2FA button" /> |
| 40 | |
| 41 | 4. When prompted provide your current account password and then click **Confirm password to continue**. |
| 42 | |
| 43 | 5. 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][about-two-factor-authentication]". |
| 44 | |
| 45 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/device-selection.png" alt="Screenshot showing 2FA types" /> |
| 46 | |
| 47 | 6. Configure the 2FA method of your choice: |
| 48 | |
| 49 | - 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. |
| 50 | |
| 51 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-add-security-key.png" alt="Screenshot showing security key setup" /> |
| 52 | |
| 53 | - Below is an example of configuration from Microsoft Edge running on a MacOS |
| 54 | |
| 55 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/touch-id-mac-edge.png" alt="Screenshot showing 2FA device selection" /> |
| 56 | |
| 57 | - 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**. |
| 58 | |
| 59 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-verify.png" alt="Screenshot showing 2FA device selection" /> |
| 60 | |
| 61 | 7. 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. |
| 62 | |
| 63 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/recovery-code.png" alt="Screenshot showing the Recovery Code page" /> |
| 64 | |
| 65 | _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][viewing-and-regenerating-recovery-code] from your 2FA settings page. For secondary account recovery options, see "[Configuring account recovery options][configuring-account-recovery-options]."_ |
| 66 | |
| 67 | 8. Click **Go back to settings** after confirming that you have saved your codes. |
| 68 | |
| 69 | ### Disabling 2FA for writes |
| 70 | |
| 71 | Check the [Authorization and writes][authorization-and-writes] section for more information on different operations that requires 2FA when this mode is enabled. |
| 72 | |
| 73 | <Note> |
| 74 | |
| 75 | **Note**: As a recommended setting, 2FA for write operations are _automatically enabled_ when setting up 2FA. The following steps explain how to disable it. |
| 76 | |
| 77 | </Note> |
| 78 | |
| 79 | 1. <>{shared['user-login'].text}</> |
| 80 | |
| 81 | <>{shared['user-login'].image}</> |
| 82 | |
| 83 | 2. <>{shared['account-settings'].text}</> |
| 84 | |
| 85 | <>{shared['account-settings'].image}</> |
| 86 | |
| 87 | 3. On the account settings page, under "Two-Factor Authentication", click **Modify 2FA**. |
| 88 | |
| 89 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-modify.png" alt="Screenshot showing Modify 2FA button" /> |
| 90 | |
| 91 | 4. From the "Manage Two-Factor Authentication" navigate to "Additional Options" section |
| 92 | |
| 93 | 5. Clear the checkbox for "Require two-factor authentication for write actions" and click "Update Preferences" |
| 94 | |
| 95 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/disable-2fa-button.png" alt="Screenshot showing a cleared check box to disable 2fa under Addition options" /> |
| 96 | |
| 97 | ### Disabling 2FA |
| 98 | |
| 99 | If you have 2FA enabled, you can remove it from your account settings page. |
| 100 | |
| 101 | <Note> |
| 102 | |
| 103 | **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. |
| 104 | |
| 105 | </Note> |
| 106 | |
| 107 | 1. <>{shared['user-login'].text}</> |
| 108 | |
| 109 | <>{shared['user-login'].image}</> |
| 110 | |
| 111 | 2. <>{shared['account-settings'].text}</> |
| 112 | |
| 113 | <>{shared['account-settings'].image}</> |
| 114 | |
| 115 | 3. On the account settings page, under "Two-Factor Authentication", click **Modify 2FA**. |
| 116 | |
| 117 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-modify.png" alt="Screenshot showing Modify 2FA button" /> |
| 118 | |
| 119 | 4. Scroll to the bottom of the "Manage Two-Factor Authentication" page and click Disable 2FA. |
| 120 | |
| 121 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-disable.png" alt="Screenshot showing Disable 2FA button" /> |
| 122 | |
| 123 | 5. Agree to the prompt from the browser. |
| 124 | |
| 125 | ## Configuring 2FA from the command line |
| 126 | |
| 127 | ### Enabling 2FA from the command line |
| 128 | |
| 129 | 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. |
| 130 | |
| 131 | <Note> |
| 132 | |
| 133 | **Note:** Settings you configure on the command line will also apply to your profile settings on the npm website. |
| 134 | |
| 135 | </Note> |
| 136 | |
| 137 | 1. If you are logged out on the command line, log in using `npm login` command. |
| 138 | |
| 139 | 2. On the command line, type the [`npm profile`](/cli/profile) command along with the option for the 2FA mode you want to enable: |
| 140 | |
| 141 | - To enable 2FA for authorization and writes, type: |
| 142 | |
| 143 | ``` |
| 144 | npm profile enable-2fa auth-and-writes |
| 145 | ``` |
| 146 | |
| 147 | - To enable 2FA for authorization only, type: |
| 148 | |
| 149 | ``` |
| 150 | npm profile enable-2fa auth-only |
| 151 | ``` |
| 152 | |
| 153 | 3. To add npm to your authenticator application, using the device with the app, you can either: |
| 154 | |
| 155 | - Scan the QR code displayed on the command line. |
| 156 | - Type the number displayed below the QR code. |
| 157 | |
| 158 | 4. When prompted to add an OTP code from your authenticator, on the command line, enter a one-time password generated by your authenticator app. |
| 159 | |
| 160 | ### Sending a one-time password from the command line |
| 161 | |
| 162 | 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: |
| 163 | |
| 164 | ``` |
| 165 | npm publish [<tarball>|<folder>][--tag <tag>] --otp=123456 |
| 166 | npm owner add <user > --otp=123456 |
| 167 | npm owner rm <user> --otp=123456 |
| 168 | npm dist-tags add <pkg>@<version> [<tag>] --otp=123456 |
| 169 | npm access edit [<package>) --otp=123456 |
| 170 | npm unpublish [<@scope>/]<pkg>[@<version>] --otp=123456 |
| 171 | ``` |
| 172 | |
| 173 | ### Removing 2FA from the command line |
| 174 | |
| 175 | 1. If you are logged out on the command line, log in using `npm login` command. |
| 176 | |
| 177 | 2. On the command line, type the following command: |
| 178 | |
| 179 | ``` |
| 180 | npm profile disable-2fa |
| 181 | ``` |
| 182 | |
| 183 | 3. When prompted, enter your npm password: |
| 184 | |
| 185 | <Prompt>npm password:</Prompt> |
| 186 | |
| 187 | 4. When prompted for a one-time password, enter a password from your authenticator app: |
| 188 | |
| 189 | <Prompt>Enter one-time password from your authenticator: <strong>123456</strong></Prompt> |
| 190 | |
| 191 | ## Configuring account recovery options |
| 192 | |
| 193 | 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. |
| 194 | |
| 195 | 1. <>{shared['user-login'].text}</> |
| 196 | |
| 197 | <>{shared['user-login'].image}</> |
| 198 | |
| 199 | 2. <>{shared['account-settings'].text}</> |
| 200 | |
| 201 | <>{shared['account-settings'].image}</> |
| 202 | |
| 203 | 3. To [link your GitHub][advanced-github-setup] account, on the account settings page, under "Linked Accounts & Recovery Option", click **Link with GitHub**. |
| 204 | |
| 205 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/link-github-account.png" alt="Screenshot showing Link GitHub account button" /> |
| 206 | |
| 207 | 4. On the authorization page, verify all information looks correct. Then click **Authorize npm account link**. |
| 208 | 5. To [link your Twitter][advanced-twitter-setup] account, on the account settings page, under "Linked Accounts & Recovery Option", click **Link with Twitter**. |
| 209 | |
| 210 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/link-twitter-account.png" alt="Screenshot showing Link Twitter account button" /> |
| 211 | |
| 212 | 6. On the authorization page, verify all information looks correct. Then click **Authorize app**. |
| 213 | |
| 214 | 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. |
| 215 | |
| 216 | ## Resolving TOTP errors |
| 217 | |
| 218 | If you are entering what seems to be a valid [TOTP][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. |
| 219 | |
| 220 | 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. |
| 221 | |
| 222 | [about-two-factor-authentication]: /about-two-factor-authentication |
| 223 | [authorization-and-writes]: /about-two-factor-authentication#authorization-and-writes |
| 224 | [login]: /cli/adduser |
| 225 | [recovering-your-2fa-enabled-account]: /recovering-your-2fa-enabled-account |
| 226 | [can-i-use]: https://caniuse.com/#search=webauthn |
| 227 | [viewing-and-regenerating-recovery-code]: /recovering-your-2fa-enabled-account#viewing-and-regenerating-recovery-code |
| 228 | [totp]: https://en.wikipedia.org/wiki/Time-based_one-time_password |
| 229 | [authy]: https://authy.com/download/ |
| 230 | [google-authenticator]: https://support.google.com/accounts/answer/1066447 |
| 231 | [microsoft-authenticator]: https://www.microsoft.com/security/mobile-authenticator-app |
| 232 | [webauthn]: https://webauthn.guide/ |
| 233 | [u2f]: https://en.wikipedia.org/wiki/Universal_2nd_Factor |
| 234 | [windows-hello]: https://support.microsoft.com/en-us/windows/learn-about-windows-hello-and-set-it-up-dae28983-8242-bb2a-d3d1-87c9d265a5f0 |
| 235 | [touch-id]: https://support.apple.com/en-gb/HT204587 |
| 236 | [face-id]: https://support.apple.com/en-us/HT208108 |
| 237 | [yubikey]: https://www.yubico.com/ |
| 238 | [thetis]: https://thetis.io/ |
| 239 | [feitian]: https://www.ftsafe.com/ |
| 240 | [configuring-account-recovery-options]: /configuring-two-factor-authentication#configuring-account-recovery-options |
| 241 | [advanced-github-setup]: managing-your-profile-settings#linking-your-npm-and-github-accounts |
| 242 | [advanced-twitter-setup]: /managing-your-profile-settings#linking-your-npm-and-twitter-accounts |