Azure DevOps NPM Authentication

0.10.2 verified Wed Apr 22 auth: no javascript

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

error 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.

error 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 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

yarn add ado-npm-auth

pnpm add ado-npm-auth

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