Azure Artifacts npm Authentication Helper (Windows Only)

0.43.0 · deprecated · verified Wed Apr 22

`vsts-npm-auth` is a command-line tool designed to assist Windows users in authenticating with private npm feeds hosted in Azure Artifacts. Its primary function is to acquire and manage authentication tokens, writing them to the user's `.npmrc` file to enable seamless package installation and publication to Azure DevOps feeds. The package's current stable version is 0.43.0, last published in May 2023. This tool is notably Windows-only and has critical limitations regarding cross-platform support and token management. Community consensus and various reports strongly advise against its use due to its closed-source nature, lack of transparency regarding contributors, and security concerns. Newer, cross-platform alternatives like `ado-npm-auth` or `azure-devops-npm-auth`, along with direct Personal Access Token (PAT) configuration, are generally recommended for more robust and secure authentication with Azure Artifacts. The official documentation also outlines manual PAT setup for non-Windows environments.

Common errors

```
Couldn't get an authentication token for https://pkgs.dev.azure.com/<org>/_packaging/<feed>/npm/registry/.
```
cause Usually an expired Personal Access Token (PAT) or an issue with the cached credentials.

fix Re-run the authentication command with the force flag: `vsts-npm-auth -config .npmrc -F`. This forces the tool to acquire a new token.
```
E401 - Unable to authenticate, your authentication token seems to be invalid.
```
cause The authentication token in the `.npmrc` is invalid, expired, or the registry URL in the `.npmrc` is malformed (e.g., missing `/registry` segment).

fix Ensure the registry URL in your `.npmrc` file ends with `/npm/registry/`. If it's correct, re-run `vsts-npm-auth -config .npmrc -F` to refresh the token. For CI, ensure `-N` is used.
```
vsts-npm-auth is not recognized as the name of a cmdlet, function, script file, or operable program.
```
cause The `vsts-npm-auth` command is not found in the system's PATH, typically meaning it was not installed globally or the installation path is not correctly configured.

fix Ensure `vsts-npm-auth` is installed globally: `npm install -g vsts-npm-auth`. If it is, check your system's PATH environment variable to ensure the npm global bin directory is included.
```
The prompt option is invalid because the process is not interactive. This could be caused by the build agent does not run in interactive mode.
```
cause The `vsts-npm-auth` tool attempted to open an interactive browser window for authentication in a non-interactive environment (e.g., CI/CD pipeline).

fix When running in CI/CD or other non-interactive contexts, always include the `-N` flag: `vsts-npm-auth -config .npmrc -N -F`. Consider if PATs or other dedicated CI/CD authentication methods are more suitable.

Warnings

breaking The `vsts-npm-auth` tool is explicitly for Windows operating systems only. It does not function on macOS or Linux, where users must manually configure Personal Access Tokens (PATs) or use alternative cross-platform tools.
Fix: For non-Windows environments, use Azure DevOps Personal Access Tokens (PATs) configured directly in `.npmrc`, or consider cross-platform alternatives like `ado-npm-auth` or `azure-devops-npm-auth`.
breaking This package is considered problematic and potentially insecure by community members. It is closed-source, lacks transparent contributor information, and has not seen updates since May 2023. Relying on it may introduce supply chain security risks.
Fix: Microsoft's current documentation for Azure Artifacts npm feeds suggests alternatives. Where possible, migrate to official PAT-based authentication or open-source, community-maintained alternatives such as `ado-npm-auth` or `azure-devops-npm-auth`.
gotcha The tool does not automatically renew authentication tokens in your `.npmrc` file upon expiration by default. If you encounter authentication failures, it's often due to an expired token.
Fix: Always run `vsts-npm-auth` with the `-F` (force) flag to ensure tokens are refreshed if they are expired or nearing expiration: `vsts-npm-auth -config .npmrc -F`.
gotcha Running `vsts-npm-auth` in non-interactive environments (e.g., CI/CD pipelines, SSH sessions) without the `-N` flag will cause the process to hang or fail, as it attempts to open an interactive browser window for authentication.
Fix: When using `vsts-npm-auth` in CI/CD or other non-interactive contexts, ensure you include the `-N` (NonInteractive) flag: `vsts-npm-auth -config .npmrc -N -F`.
gotcha On Windows systems where the user's home directory (`%USERPROFILE%`) is mapped to a network drive, `vsts-npm-auth` might write the `.npmrc` file to an incorrect location that `npm` cannot find, leading to authentication issues.
Fix: Verify that your npm configuration is pointing to the correct user configuration file location by running `npm config get userconfig`. Ensure `vsts-npm-auth` writes to this expected location, or manually move the generated `.npmrc` content. Consider using a project-level `.npmrc` and pointing to it explicitly with `-config`.

Install

npm install vsts-npm-auth npm
yarn add vsts-npm-auth yarn
pnpm add vsts-npm-auth pnpm

Imports

vsts-npm-auth
wrong:
```
import vstsNpmAuth from 'vsts-npm-auth'
```
correct:
```
npm install -g vsts-npm-auth
```
This package is a command-line tool and is not intended for library-style import. It should be installed globally or executed via `npx` (though global is common for auth helpers).
Execution (configure .npmrc)
wrong:
```
vsts-npm-auth
```
correct:
```
vsts-npm-auth -config .npmrc -F
```
Always use `-F` (force) to ensure tokens are refreshed, especially after expiration. The `-config` flag specifies the path to your project's .npmrc file containing the feed URL.
Execution (non-interactive)
wrong:
```
vsts-npm-auth -config .npmrc
```
correct:
```
vsts-npm-auth -config .npmrc -N -F
```
For CI/CD pipelines or non-interactive environments, the `-N` (NonInteractive) flag is crucial to prevent the tool from attempting to prompt for credentials, which would cause the process to hang or fail.

Quickstart

Demonstrates the installation of `vsts-npm-auth` globally on Windows, configuring a project-level `.npmrc` file, and running the authentication helper to enable `npm install` from an Azure Artifacts private feed.

# 1. Install the tool globally (Windows only)
npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false

# 2. Navigate to your project directory
cd my-azure-devops-project

# 3. Create a .npmrc file in your project root with your feed URL
#    (Replace <your-organization> and <your-feed-name>)
#    Example: @my-scope:registry=https://pkgs.dev.azure.com/<your-organization>/_packaging/<your-feed-name>/npm/registry/
#    You can get the exact content from Azure Artifacts 'Connect to feed' instructions.

echo "@my-scope:registry=https://pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/" > .npmrc

# 4. Run the auth helper to acquire and store credentials.
#    The -F (force) flag ensures tokens are always refreshed if needed.
vsts-npm-auth -config .npmrc -F

# 5. Now you can install packages from your private feed
npm install @my-scope/my-package

view raw JSON →