Npm Auth

Authentication with npm is essential for publishing packages and accessing private packages. This guide explains how to authenticate with npm and manage your authentication credentials securely.

Logging in to npm

To authenticate with npm, you need to log in using the npm CLI:

npm login

You'll be prompted to enter your username, password, and email address. If you have two-factor authentication enabled, you'll also need to provide an OTP (One-Time Password).

Verifying Login Status

To check if you're logged in and see your current npm user:

npm whoami

If you're not logged in, this command will return an error.

Two-Factor Authentication

Two-factor authentication (2FA) adds an extra layer of security to your npm account. It requires a second form of authentication in addition to your password.

Enabling 2FA

You can enable 2FA from the command line:

# Enable 2FA for authentication only
npm profile enable-2fa auth-only

# Enable 2FA for authentication and publishing
npm profile enable-2fa auth-and-writes

You'll need an authenticator app that supports TOTP (Time-based One-Time Password) such as Google Authenticator, Authy, or Microsoft Authenticator.

Using 2FA

When 2FA is enabled, you'll need to provide an OTP when:

• Logging in to npm
• Publishing packages (if you enabled 2FA for writes)
• Managing tokens and organization members

Disabling 2FA

If you need to disable 2FA:

npm profile disable-2fa

npm Tokens

npm tokens allow you to authenticate without using your username and password. They are especially useful for CI/CD pipelines and automated processes.

Creating Tokens

To create a new token:

npm token create

You can specify the token's permissions and expiration:

# Create a read-only token
npm token create --read-only

# Create a token with an expiration date
npm token create --cidr=192.168.1.0/24 --readonly --cidr=::1/128

Listing Tokens

To list your existing tokens:

npm token list

Revoking Tokens

To revoke a token:

# Get the token ID from npm token list
npm token revoke <token_id>

Using Tokens in CI/CD

For automated publishing in CI/CD pipelines, you can use npm tokens instead of your credentials:

Setting Up .npmrc

Create or edit the .npmrc file:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Then set the NPM_TOKEN environment variable in your CI/CD system with your npm token.

GitHub Actions Example

# .github/workflows/publish.yml
name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
          registry-url: 'https://registry.npmjs.org/'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Authentication for Scoped Packages

Scoped packages (e.g., @username/package-name) can be private or public. Private packages require authentication to access.

Accessing Private Scoped Packages

To authenticate for a specific scope, add the following to your .npmrc file:

@scope:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Organization Scopes

For npm organizations, you need to be a member of the organization to access private packages:

# Log in with your npm account
npm login

# Install a private package from your organization
npm install @your-org/private-package

Troubleshooting Authentication Issues

Common Issues

401 Unauthorized

If you see a 401 Unauthorized error:

• Check if you're logged in with npm whoami
• Try logging in again with npm login
• Verify that your token has the correct permissions
• Check if your token has expired

403 Forbidden

If you see a 403 Forbidden error:

• Verify that you have access to the package or organization
• Check if your subscription is active (for paid organizations)
• Ensure you're using the correct registry URL

Clearing npm Cache

Sometimes, clearing the npm cache can resolve authentication issues:

npm cache clean --force

Checking .npmrc Files

npm reads configuration from multiple .npmrc files:

• Project-level: ./project/.npmrc
• User-level: ~/.npmrc
• Global: /etc/npmrc or %APPDATA%/npm/etc/npmrc

Check these files for conflicting configurations.

Security Best Practices

• Enable 2FA: Always use two-factor authentication for your npm account
• Use tokens with limited scope: Create tokens with the minimum required permissions
• Set token expiration: Use tokens with expiration dates for temporary access
• Rotate tokens regularly: Create new tokens and revoke old ones periodically
• Use environment variables: Store tokens in environment variables, not in code
• Audit access regularly: Review who has access to your packages and organizations