diff --git a/content/cli/v10/commands/npm-token.mdx b/content/cli/v10/commands/npm-token.mdx index 79029a79ebf..e1e5f95f60e 100644 --- a/content/cli/v10/commands/npm-token.mdx +++ b/content/cli/v10/commands/npm-token.mdx @@ -47,7 +47,7 @@ Publish token npm_… with id e0cf92 created 2017-10-02 - `npm token create [--read-only] [--cidr=]`: Create a new authentication token. It can be `--read-only`, or accept a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges with which to limit use of this token. This will prompt you for your password, and, if you have two-factor authentication enabled, an otp. - Currently, the cli can not generate automation tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens. + Currently, the cli can not generate automation tokens or granular access tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens and granular access tokens. ``` Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d diff --git a/content/cli/v11/commands/npm-token.mdx b/content/cli/v11/commands/npm-token.mdx index 7da0c9e70d5..9e06e5ff744 100644 --- a/content/cli/v11/commands/npm-token.mdx +++ b/content/cli/v11/commands/npm-token.mdx @@ -63,7 +63,7 @@ Publish token npm_… with id e0cf92 created 2017-10-02 - `npm token create [--read-only] [--cidr=]`: Create a new authentication token. It can be `--read-only`, or accept a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges with which to limit use of this token. This will prompt you for your password, and, if you have two-factor authentication enabled, an otp. - Currently, the cli can not generate automation tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens. + Currently, the cli can not generate automation tokens or granular access tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens and granular access tokens. ``` Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d diff --git a/content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx b/content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx index 58ba81093e8..6ac18a66dbe 100644 --- a/content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx +++ b/content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx @@ -44,6 +44,12 @@ By default, 2FA is enabled for authorization and writes. We will request a secon | Change user and team package access | [`npm access grant/revoke`][access] | | [Change package 2FA requirements][pkg-2fa] | [`npm access 2fa-required/2fa-not-required`][access] | + + +**Note:** [Granular access tokens][granular-tokens] can be configured to bypass 2FA requirements, making them ideal for CI/CD workflows and automation scenarios. When a granular access token is set to bypass 2FA, operations performed with that token will not require additional authentication factors. + + + ### Authorization only If you enable 2FA for authorization only. We will request a second form of authentication only for certain authorized actions. @@ -68,6 +74,7 @@ If you enable 2FA for authorization only. We will request a second form of authe [deprecate]: https://docs.npmjs.com/cli/deprecate [access]: https://docs.npmjs.com/cli/access [pkg-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification +[granular-tokens]: /integrations/integrating-npm-with-external-services/about-access-tokens#about-granular-access-tokens [authy]: https://authy.com/download/ [google-authenticator]: https://support.google.com/accounts/answer/1066447 [microsoft-authenticator]: https://www.microsoft.com/security/mobile-authenticator-app diff --git a/content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx b/content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx index aa174681a5d..7a68386c2fc 100644 --- a/content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx +++ b/content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx @@ -52,8 +52,11 @@ Granular access tokens allow you to restrict access provided to the token based - Set a token expiration date - Limit token access based on IP address ranges - Select between **read-only** or **read and write** access +- Configure whether the token can bypass two-factor authentication (2FA) requirements -You can create up to 1000 granular access tokens on your npm account. You can set how long your token is valid for, at least one day in the future. Each token can access up to 50 organizations, and up to either 50 packages, 50 scopes, or a combination of 50 packages and scopes. Access tokens are tied to users’ permission; hence it cannot have more permission than the user at any point in time. If a user has their access revoked from a package or an org., their granular access token also will have its access revoked from those packages or org. +You can create up to 1000 granular access tokens on your npm account. You can set how long your token is valid for, at least one day in the future. Each token can access up to 50 organizations, and up to either 50 packages, 50 scopes, or a combination of 50 packages and scopes. Access tokens are tied to users' permission; hence it cannot have more permission than the user at any point in time. If a user has their access revoked from a package or an org., their granular access token also will have its access revoked from those packages or org. + +Granular access tokens can be configured to bypass 2FA requirements, making them ideal for CI/CD workflows and automation scenarios where interactive 2FA prompts are not feasible. When a granular access token is set to bypass 2FA, it will not require additional authentication factors when performing operations on npm, similar to automation tokens. When you give a token access to an organization, the token can only be used for managing organization settings and teams or users associated with the organization. It does not give the token the right to publish packages managed by the organization. diff --git a/content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx b/content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx index c0104e03a54..da6b39149f2 100644 --- a/content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx +++ b/content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx @@ -75,11 +75,15 @@ You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) acc _**Note**: When you give a token access to an organization, the token can only be used for managing organization settings and teams or users associated with the organization. It does not give the token the right to publish packages managed by the organization._ -9. Review the token summary, then click **Generate Token**. +9. (Optional) In the **Two-Factor Authentication** section, configure whether the token can bypass 2FA requirements. + - Check **Bypass two-factor authentication** to allow the token to bypass 2FA requirements when performing operations on npm. This is ideal for CI/CD workflows and automation scenarios. + - Leave unchecked if you want the token to require 2FA for sensitive operations. + +10. Review the token summary, then click **Generate Token**. -10. Copy the token from the top of page. +11. Copy the token from the top of page. ### Creating tokens with the CLI diff --git a/content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx b/content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx index 808bf2ce1ae..6d64bcabb5a 100644 --- a/content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx +++ b/content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx @@ -24,7 +24,7 @@ For more information on creating access tokens, including CIDR-whitelisted token ### Continuous deployment -Since continuous deployment environments usually involve the creation of a deploy artifact, you may wish to create an [automation token][create-token] on the website. This will allow you to publish even if you have two-factor authentication enabled on your account. +Since continuous deployment environments usually involve the creation of a deploy artifact, you may wish to create an [automation token][create-token] or a [granular access token][create-token] configured to bypass 2FA on the website. This will allow you to publish even if you have two-factor authentication enabled on your account. ### Interactive workflows diff --git a/content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx b/content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx index 1e4d5a8ccce..f5f7895cfe3 100644 --- a/content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx +++ b/content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx @@ -6,7 +6,7 @@ import shared from '~/shared.js' To protect your packages, as a package publisher, you can require everyone who has write access to a package to have two-factor authentication (2FA) enabled. This will require that users provide 2FA credentials in addition to their login token when they publish the package. For more information, see "[Configuring two-factor authentication][config-2fa]". -You may also choose to allow publishing with either two-factor authentication _or_ with [automation tokens][creating-automation-token]. This lets you configure automation tokens in a CI/CD workflow, but requires two-factor authentication from interactive publishes. +You may also choose to allow publishing with either two-factor authentication _or_ with [automation tokens][creating-automation-token] or [granular access tokens][creating-granular-access-token] configured to bypass 2FA. This lets you configure tokens in a CI/CD workflow, but requires two-factor authentication from interactive publishes. ## Configuring two-factor authentication @@ -25,10 +25,10 @@ You may also choose to allow publishing with either two-factor authentication _o With this option, a maintainer can publish a package or change the package settings whether they have two-factor authentication enabled or not. This is the least secure setting. 2. **Require two-factor authentication or automation tokens or granular access token** - With this option, maintainers must have two-factor authentication enabled for their account. If they publish a package interactively, using the `npm publish` command, they will be required to enter 2FA credentials when they perform the publish. However, maintainers may also create an [automation token][creating-automation-token] or a [granular access token][creating-granular-access-token] and use that to publish. A second factor is _not_ required when using a token, making it useful for continuous integration and continuous deployment workflows. + With this option, maintainers must have two-factor authentication enabled for their account. If they publish a package interactively, using the `npm publish` command, they will be required to enter 2FA credentials when they perform the publish. However, maintainers may also create an [automation token][creating-automation-token] or a [granular access token][creating-granular-access-token] configured to bypass 2FA and use that to publish. A second factor is _not_ required when using a token configured to bypass 2FA, making it useful for continuous integration and continuous deployment workflows. 3. **Require two-factor authentication and disallow tokens** - With this option, a maintainer must have two-factor authentication enabled for their account, and they must publish interactively. Maintainers will be required to enter 2FA credentials when they perform the publish. Automation tokens and granular access tokens cannot be used to publish packages. + With this option, a maintainer must have two-factor authentication enabled for their account, and they must publish interactively. Maintainers will be required to enter 2FA credentials when they perform the publish. Automation tokens and granular access tokens configured to bypass 2FA cannot be used to publish packages.