azdo-npm-auth

Azure DevOps npm auth

Simply set up user authentication to Azure DevOps npm feeds, optionally using the Azure CLI for Personal Access Token (PAT) acquisition.

Usage

There are three ways to use azdo-npm-auth.

parse mode

The simplest way to use azdo-npm-auth is to run it without any arguments. In this mode, azdo-npm-auth will parse the project .npmrc file in the current working directory and use the values it finds there to create a user .npmrc file. To get azdo-npm-auth to create the necessary user .npmrc file in parse mode, run the following command:

npx -y --registry https://registry.npmjs.org azdo-npm-auth

You might be wondering what the --registry https://registry.npmjs.org part is for. It is a way to ensure that the npx command uses the public npm registry to install azdo-npm-auth. Without this, you might encounter an error like below, as npx attempts to install azdo-npm-auth from the private Azure DevOps npm registry:

npm error code E401
npm error Unable to authenticate, your authentication token seems to be invalid.
npm error To correct this please try logging in again with:
npm error npm login

It is possible to use environment variables to control the registry setting as well; consider the following (non-Windows compatible) example:

npm_config_registry=https://registry.npmjs.org npx azdo-npm-auth

But passing the --registry flag directly is the recommended approach.

registry mode

The parse mode works by reading the registry value from the project .npmrc file. If you would like to manually supply the registry value, you can do so. In this mode of operation azdo-npm-auth will not attempt to parse the project .npmrc file, and will use the supplied registry value to build a user .npmrc file.

npx -y --registry https://registry.npmjs.org azdo-npm-auth --registry https://pkgs.dev.azure.com/johnnyreilly/_packaging/organization-feed-name/npm/registry/

There's two --registry values in the above command. The first is the public npm registry which is where we want to access azdo-npm-auth. The second is the registry to use to create the user .npmrc file. You will need to change this second value to match your private npm registry feed URL. (This can be found in Azure DevOps > Artifacts > Connect to feed > npm or in a local .npmrc file).

make mode

The make mode allows you to supply the the organization, feed and (optionally) project values to create a user .npmrc file. In this mode of operation azdo-npm-auth will not attempt to parse the project .npmrc file, and will use the supplied values to build a user .npmrc file.

If your feed is organization-scoped, you will not need to supply the project value:

npx -y --registry https://registry.npmjs.org azdo-npm-auth --organization johnnyreilly --feed organization-feed-name

If your feed is project-scoped, you will need to supply the project value:

npx -y --registry https://registry.npmjs.org azdo-npm-auth --organization johnnyreilly --project my-project --feed project-feed-name

Pre-requisites

If you would like azdo-npm-auth to acquire a token on your behalf, then it requires that your Azure DevOps organization is connected with your Azure account / Microsoft Entra ID. Then, assuming you are authenticated with Azure, it can acquire an Azure DevOps Personal Access Token on your behalf. To authenticate, run az login. If you need to install the Azure CLI, follow these instructions. It is not necessary to run az login if you are already authenticated with Azure.

If you would like to acquire a PAT token manually and supply it, there is a --pat option for that very need.

Integration with package.json

Custom npm script

We generally advise setting up a custom npm script like the one below:

"scripts": {
  "auth": "npx -y --registry https://registry.npmjs.org azdo-npm-auth"
},

Users should npm run auth when a npm error code E401 is encountered. We've called this script auth - you can choose any name you like.

You might be wondering why we do not recommend using a preinstall script. It's possible but there are gotchas. Read on.

preinstall script

First the bad news. The below won't work:

"scripts": {
  "preinstall": "npx -y --registry https://registry.npmjs.org azdo-npm-auth"
},

Alas, it is not possible to get the preinstall script to ignore the project .npmrc file when it runs. As a consequence the preinstall script results in a npm error code E401 and much sadness. Read more about E401s here.

It is still possible to integrate azdo-npm-auth in a preinstall script in your package.json:

"scripts": {
  "preinstall": "npx --yes azdo-npm-auth --config ./subdir-with-package-json/.npmrc"
},

However, as you're probably noticing, this approach requires having multiple package.jsons and only having the .npmrc file in the nested one. Assuming that works for you, brilliant. It may not.

The --yes flag above skips having npm challenge the user as to whether to download the package; useful in a CI environment.

What about CI?

You might be worried about azdo-npm-auth trying to create user .npmrc files when running CI builds. Happily this does not happen; it detects whether it is running in a CI environment and does not create a user .npmrc file in that case.

Why does Azure DevOps npm auth exist?

Azure DevOps provides a mechanism for publishing npm packages for private use. This package sets up the necessary authentication to access those packages; particularly for non Windows users.

Consider the onboarding process for a Windows user for consuming an Azure Artifact npm feed:

Now consider the onboarding process for a non Windows user:

As we can see, there is a significant difference in the onboarding experience between operating systems. Windows users can use a tool named vsts-npm-auth which automates onboarding. Non windows users have a longer road to follow. The instructions walk through manually creating an .npmrc file in a users home directory which contains information including a base 64 encoded Azure DevOps Personal Access Token with the Packaging read and write scopes. It is tedious to do.

azdo-npm-auth aims to automate the toil, and make the onboarding experience for non Windows users as simple as it is for Windows users.

There is an official package named ado-npm-auth. However, due to issues I experienced in using the ado-npm-auth package, I found myself creating azdo-npm-auth.

Options

Short	Long	Type	Description
-c	--config	string	The location of the .npmrc file. Defaults to current directory
-o	--organization	string	The Azure DevOps organization - only required if not parsing from the .npmrc file
-p	--project	string	The Azure DevOps project - only required if not parsing from the .npmrc file and the feed is project-scoped
-f	--feed	string	The Azure Artifacts feed - only required if not parsing from the .npmrc file
-r	--registry	string	The registry to use, eg 'https://pkgs.dev.azure.com/johnnyreilly/_packaging/organization-feed-name/npm/registry/' - only required if not parsing from the .npmrc file
-e	--email	string	Allows users to supply an explicit email - if not supplied, the example ADO value will be used
-d	--daysToExpiry	number	Allows users to supply an explicit number of days to expiry - if not supplied, then ADO will determine the expiry date
-t	--pat	string	Allows users to supply an explicit Personal Access Token (which must include the Packaging read and write scopes) - if not supplied, will be acquired from the Azure CLI
-w	--what-if		Do not write output to user .npmrc file; rather output to terminal
-h	--help		Show help
-v	--version		Show version

Help with npm error code E401

When you are attempting to install from private feeds, npm will commonly error out with some form of npm error code E401.

This section exists to list some classic errors you might encounter when you try to npm i. Regardless of the error, the remedy is generally:

npx -y --registry https://registry.npmjs.org azdo-npm-auth

User .npmrc not found

When you have no user .npmrc file you'll encounter an error like this:

npm error code E401
npm error Unable to authenticate, your authentication token seems to be invalid.
npm error To correct this please try logging in again with:
npm error npm login

You need to run npx -y --registry https://registry.npmjs.org azdo-npm-auth to create the user .npmrc file.

Token used in user .npmrc file is expired

When your token has expired in your user .npmrc file you'll encounter an error like this:

npm error code E401
npm error Incorrect or missing password.
npm error If you were trying to login, change your password, create an
npm error authentication token or enable two-factor authentication then
npm error that means you likely typed your password in incorrectly.
npm error Please try again, or recover your password at:
npm error https://www.npmjs.com/forgot
npm error
npm error If you were doing some other operation then your saved credentials are
npm error probably out of date. To correct this please try logging in again with:
npm error npm login

You need to run npx -y --registry https://registry.npmjs.org azdo-npm-auth to get a new PAT and recreate the user .npmrc file.

Credits

💙 This package was templated with create-typescript-app.