Azure DevOps NPM Authentication

0.10.2 · active · verified Wed Apr 22

The `ado-npm-auth` package is a command-line utility designed to streamline authentication for Node.js projects interacting with private npm registries hosted on Azure DevOps (ADO). It automates the process of fetching authentication tokens using the underlying `azureauth-cli` (wrapped via `node-azureauth`) and securely updates the user's `.npmrc` file. A key differentiator from its predecessor, `vsts-npm-auth`, is its cross-platform compatibility, leveraging the cross-platform nature of `azureauth-cli`. Currently at version 0.10.2, the package is under active development. Its primary use case involves integration into project lifecycle scripts, such as `preinstall`, to ensure continuous access to private ADO feeds without manual token management.

Common errors

```
npm ERR! 401 Unauthorized
```
cause The authentication token in your user's `~/.npmrc` or the project's `.npmrc` for the Azure DevOps feed has expired or is invalid, preventing access to private packages.

fix Run `npm exec ado-npm-auth` (or your configured `preinstall` script) to refresh the authentication token. Ensure the command is executed correctly, especially considering the 'chicken and egg' warning for `npm exec`.
```
npm ERR! command not found: ado-npm-auth
```
cause When `npm exec` or `npx` attempts to run `ado-npm-auth`, it cannot find the package, likely because your project's `.npmrc` points to an authenticated ADO feed, and `ado-npm-auth` itself cannot be fetched from that feed without a valid token.

fix Execute the command with a temporary public registry override: `npm_config_registry=https://registry.npmjs.org npm exec ado-npm-auth`. This ensures `ado-npm-auth` is fetched from the public npm registry before it can authenticate to your private ADO feed.
```
Error: Command failed: <path-to-node>/node_modules/ado-npm-auth/bin/ado-npm-auth.js
```
cause This generic error often indicates that the underlying `azureauth-cli` call failed, possibly due to environment issues, insufficient permissions, or an unexpected problem during token acquisition.

fix Check the detailed output (if available) for clues from `azureauth-cli`. Ensure you have appropriate permissions in Azure DevOps, and that your `azureauth-cli` installation (managed by `ado-npm-auth`'s dependency) is functional. Try running the command with increased verbosity if the tool supports it.

Warnings

gotcha When running `ado-npm-auth` via `npm exec` or `npx` within a project that already has its `.npmrc` configured to point to a private Azure DevOps feed, a 'chicken and egg problem' can occur. The package manager might attempt to resolve `ado-npm-auth` itself from the private registry before authentication has happened, leading to failures.
Fix: To resolve this, either explicitly pass the configuration file using `-c <path-to-.npmrc>` or, more commonly, prepend the `npm exec` command with `npm_config_registry=https://registry.npmjs.org` to ensure `ado-npm-auth` is fetched from the public npm registry. For example: `npm_config_registry=https://registry.npmjs.org npm exec ado-npm-auth`.
gotcha The `ado-npm-auth` tool relies on the `azureauth-cli` for token acquisition. While `ado-npm-auth` manages its dependency on the `azureauth` npm package, issues with the underlying `azureauth-cli` installation or environment configuration (e.g., path issues) could indirectly affect `ado-npm-auth`'s functionality.
Fix: Ensure your environment is correctly configured for the `azureauth-cli` if you encounter unexpected errors not related to npm registry access. Check the `azureauth` npm package documentation for specific system requirements or troubleshooting steps.

Install

npm install ado-npm-auth npm
yarn add ado-npm-auth yarn
pnpm add ado-npm-auth pnpm

Quickstart

Demonstrates how to integrate `ado-npm-auth` into a project's `package.json` `preinstall` script. This ensures that an authentication token is automatically fetched and updated in the `.npmrc` file before package installation, resolving the 'chicken and egg problem' by temporarily setting the registry to public npm for `ado-npm-auth` itself, and explicitly passing the project's `.npmrc`.

{
  "name": "my-ado-project",
  "version": "1.0.0",
  "description": "Example project using Azure DevOps npm feed.",
  "main": "index.js",
  "scripts": {
    "preinstall": "npm_config_registry=https://registry.npmjs.org npm exec ado-npm-auth -- -c ./.npmrc",
    "start": "node index.js"
  },
  "dependencies": {},
  "devDependencies": {},
  "repository": {
    "type": "git",
    "url": "git+https://github.com/microsoft/ado-npm-auth.git"
  },
  "author": ""
}
// Example .npmrc in project root
// registry=https://pkgs.dev.azure.com/your-org/your-project/_packaging/your-feed/npm/registry/
// always-auth=true

view raw JSON →