main
@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 using a [security-key][webauthn]. |
| 8 | |
| 9 | <Note variant="warning"> |
| 10 | |
| 11 | **Important:** Publishing to npm requires either: |
| 12 | |
| 13 | - Two-factor authentication (2FA) enabled on your account, OR |
| 14 | - A granular access token with bypass 2FA enabled |
| 15 | |
| 16 | For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification). |
| 17 | |
| 18 | </Note> |
| 19 | |
| 20 | ## Prerequisites |
| 21 | |
| 22 | Before you enable 2FA on your npm user account, you must: |
| 23 | |
| 24 | - Update your npm client to version 5.5.1 or higher. |
| 25 | - 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]. |
| 26 | |
| 27 | For more information on supported 2FA methods, see "[About two-factor authentication][about-two-factor-authentication]". |
| 28 | |
| 29 | ## Configuring 2FA from the website |
| 30 | |
| 31 | ### Enabling 2FA |
| 32 | |
| 33 | 1. <>{shared['user-login'].text}</> |
| 34 | |
| 35 | <>{shared['user-login'].image}</> |
| 36 | |
| 37 | 2. <>{shared['account-settings'].text}</> |
| 38 | |
| 39 | <>{shared['account-settings'].image}</> |
| 40 | |
| 41 | 3. On the account settings page, under "Two-Factor Authentication", click **Enable 2FA**. |
| 42 | |
| 43 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-enable.png" alt="Screenshot showing Enable 2FA button" /> |
| 44 | |
| 45 | 4. When prompted provide your current account password and then click **Confirm password to continue**. |
| 46 | |
| 47 | 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]". |
| 48 | |
| 49 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/device-selection.png" alt="Screenshot showing 2FA types" /> |
| 50 | |
| 51 | 6. Configure your security-key: |
| 52 | - Provide a name for your security-key and click **Add security key**. Follow the browser specific steps to add your security-key. |
| 53 | |
| 54 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-add-security-key.png" alt="Screenshot showing security key setup" /> |
| 55 | |
| 56 | - Below is an example of configuration from Microsoft Edge running on a MacOS |
| 57 | |
| 58 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/touch-id-mac-edge.png" alt="Screenshot showing 2FA device selection" /> |
| 59 | |
| 60 | 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. |
| 61 | |
| 62 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/recovery-code.png" alt="Screenshot showing the Recovery Code page" /> |
| 63 | |
| 64 | _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]."_ |
| 65 | |
| 66 | 8. Click **Go back to settings** after confirming that you have saved your codes. |
| 67 | |
| 68 | ### Disabling 2FA |
| 69 | |
| 70 | If you have 2FA enabled, you can remove it from your account settings page. |
| 71 | |
| 72 | <Note> |
| 73 | |
| 74 | **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. |
| 75 | |
| 76 | </Note> |
| 77 | |
| 78 | 1. <>{shared['user-login'].text}</> |
| 79 | |
| 80 | <>{shared['user-login'].image}</> |
| 81 | |
| 82 | 2. <>{shared['account-settings'].text}</> |
| 83 | |
| 84 | <>{shared['account-settings'].image}</> |
| 85 | |
| 86 | 3. On the account settings page, under "Two-Factor Authentication", click **Modify 2FA**. |
| 87 | |
| 88 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-modify.png" alt="Screenshot showing Modify 2FA button" /> |
| 89 | |
| 90 | 4. Scroll to the bottom of the "Manage Two-Factor Authentication" page and click Disable 2FA. |
| 91 | |
| 92 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-disable.png" alt="Screenshot showing Disable 2FA button" /> |
| 93 | |
| 94 | 5. Agree to the prompt from the browser. |
| 95 | |
| 96 | ## Configuring 2FA from the command line |
| 97 | |
| 98 | ### Enabling 2FA from the command line |
| 99 | |
| 100 | Security-key with WebAuthn can be used for authentication from both the web and the command line, but it can only be configured from the web. |
| 101 | |
| 102 | <Note> |
| 103 | |
| 104 | **Note:** Settings you configure on the command line will also apply to your profile settings on the npm website. |
| 105 | |
| 106 | </Note> |
| 107 | |
| 108 | For the best security experience, we recommend configuring 2FA through the web interface where you can set up security-key authentication. |
| 109 | |
| 110 | If you need to enable 2FA from the command line: |
| 111 | |
| 112 | 1. If you are logged out on the command line, log in using `npm login` command. |
| 113 | |
| 114 | 2. On the command line, type the [`npm profile`](/cli/profile) command along with the option for the 2FA mode you want to enable: |
| 115 | - To enable 2FA for authorization and writes, type: |
| 116 | |
| 117 | ``` |
| 118 | npm profile enable-2fa auth-and-writes |
| 119 | ``` |
| 120 | |
| 121 | - To enable 2FA for authorization only, type: |
| 122 | |
| 123 | ``` |
| 124 | npm profile enable-2fa auth-only |
| 125 | ``` |
| 126 | |
| 127 | ### Using 2FA with commands |
| 128 | |
| 129 | If you have enabled 2FA auth-and-writes, authentication will be handled automatically when using security-keys. For commands that require 2FA, you will be prompted to authenticate with your configured 2FA method. |
| 130 | |
| 131 | ### Removing 2FA from the command line |
| 132 | |
| 133 | 1. If you are logged out on the command line, log in using `npm login` command. |
| 134 | |
| 135 | 2. On the command line, type the following command: |
| 136 | |
| 137 | ``` |
| 138 | npm profile disable-2fa |
| 139 | ``` |
| 140 | |
| 141 | 3. When prompted, enter your npm password: |
| 142 | |
| 143 | <Prompt>npm password:</Prompt> |
| 144 | |
| 145 | 4. You will be prompted to authenticate with your configured 2FA method to complete the removal. |
| 146 | |
| 147 | ## Configuring account recovery options |
| 148 | |
| 149 | When you enable 2FA on your npm user account, we strongly recommend you link your GitHub account to your npm user account. In the event you lose access to your 2FA device and recovery codes, this linked account can be used to verify your identity and expedite the recovery of your npm account. |
| 150 | |
| 151 | 1. <>{shared['user-login'].text}</> |
| 152 | |
| 153 | <>{shared['user-login'].image}</> |
| 154 | |
| 155 | 2. <>{shared['account-settings'].text}</> |
| 156 | |
| 157 | <>{shared['account-settings'].image}</> |
| 158 | |
| 159 | 3. To [link your GitHub][advanced-github-setup] account, on the account settings page, under "Linked Accounts & Recovery Option", click **Link with GitHub**. |
| 160 | |
| 161 | <Screenshot src="/getting-started/setting-up-your-npm-user-account/link-github-account.png" alt="Screenshot showing Link GitHub account button" /> |
| 162 | |
| 163 | 4. On the authorization page, verify all information looks correct. Then click **Authorize npm account link**. |
| 164 | |
| 165 | The GitHub account is now linked to your npm account. To remove the link, you can click the **Remove** button next to the account. |
| 166 | |
| 167 | [about-two-factor-authentication]: /about-two-factor-authentication |
| 168 | [authorization-and-writes]: /about-two-factor-authentication#authorization-and-writes |
| 169 | [login]: /cli/adduser |
| 170 | [recovering-your-2fa-enabled-account]: /recovering-your-2fa-enabled-account |
| 171 | [can-i-use]: https://caniuse.com/#search=webauthn |
| 172 | [viewing-and-regenerating-recovery-code]: /recovering-your-2fa-enabled-account#viewing-and-regenerating-recovery-code |
| 173 | [webauthn]: https://webauthn.guide/ |
| 174 | [creating-token]: /creating-and-viewing-access-tokens |
| 175 | [u2f]: https://en.wikipedia.org/wiki/Universal_2nd_Factor |
| 176 | [windows-hello]: https://support.microsoft.com/en-us/windows/learn-about-windows-hello-and-set-it-up-dae28983-8242-bb2a-d3d1-87c9d265a5f0 |
| 177 | [touch-id]: https://support.apple.com/en-gb/HT204587 |
| 178 | [face-id]: https://support.apple.com/en-us/HT208108 |
| 179 | [yubikey]: https://www.yubico.com/ |
| 180 | [thetis]: https://thetis.io/ |
| 181 | [feitian]: https://www.ftsafe.com/ |
| 182 | [configuring-account-recovery-options]: /configuring-two-factor-authentication#configuring-account-recovery-options |
| 183 | [advanced-github-setup]: managing-your-profile-settings#linking-your-npm-and-github-accounts |