Azure DevOps Authentication CLI Wrapper

Common errors

• 'azureauth' is not recognized as an internal or external command, operable program or batch file.

  cause The `azureauth` CLI executable is typically installed into `node_modules/.bin`. This error occurs when attempting to run it directly from the system PATH without using `npm exec`, `npx`, or npm scripts.
  fix Always execute the `azureauth` CLI wrapper via `npx azureauth`, `npm exec azureauth`, or by defining it in your `package.json` scripts (e.g., `"scripts": { "authcli": "azureauth --version" }` and then `npm run authcli`).

• code E401 npm ERR! Unable to authenticate, need: Bearer authorization.

  cause This error commonly occurs when attempting to access private npm feeds (e.g., Azure Artifacts) without a valid or current authentication token. The existing token in your `.npmrc` might be expired or invalid.
  fix Run `ado-npm-auth` (which uses `azureauth` internally) or use the `adoPat` function programmatically to refresh your `.npmrc` credentials. For `ado-npm-auth`, you might run `npx ado-npm-auth` or specify a config file: `npx ado-npm-auth -c .npmrc`.

• Error: User canceled authentication or timed out.

  cause During an interactive authentication flow initiated by `adoPat` or the CLI, the user either closed the browser window/dialog without completing authentication or failed to authenticate within the allotted time.
  fix Ensure the user is ready to complete the authentication prompt in their browser promptly. Check network connectivity and proxy settings that might interfere with the browser redirect or token exchange. Increase `timeout` if available in the API options for slower environments.

Warnings

• breaking As a pre-1.0 package (v0.14.0), API surfaces may change frequently without adhering to strict semantic versioning, potentially introducing breaking changes in minor releases.
  Fix: Refer to the GitHub repository's release notes for specific breaking changes in newer versions and update code accordingly.
• gotcha The package wraps an external CLI executable. Ensure the host system's environment allows execution of downloaded binaries, especially in restricted CI/CD environments or hardened systems. Issues can arise from proxy settings or security policies blocking downloads/execution.
  Fix: Verify network access for downloading the CLI and ensure execution permissions. For CI/CD, review security policies and consider pre-installing the `microsoft-authentication-cli` if persistent issues occur.
• gotcha Azure authentication, especially for Azure DevOps, often involves Multi-Factor Authentication (MFA) or Conditional Access policies. Non-interactive logins may fail with errors like '50126' or '53003' if MFA is required but cannot be performed.
  Fix: For interactive flows, ensure browser prompts are handled. For CI/CD, use service principals or managed identities configured to bypass interactive MFA, or use a PAT generated with appropriate scopes that does not require interactive MFA. Consult Azure AD/DevOps administrators for Conditional Access policies.
• deprecated The underlying `microsoft-authentication-cli` and related Azure authentication mechanisms are continuously updated. Older token types (e.g., 'classic tokens') may be deprecated, and more granular, time-limited tokens with 2FA requirements are becoming standard.
  Fix: Upgrade to the latest `azureauth` version to leverage updated CLI versions that support current security best practices, such as granular tokens and adherence to 2FA policies. Regularly review Azure AD security guidelines.

Install

• npm install azureauth npm
• yarn add azureauth yarn
• pnpm add azureauth pnpm

Imports

• adoPat
  wrong:

  const { adoPat } = require('azureauth');

  correct:

  import { adoPat } from 'azureauth';

  The library primarily uses ES modules. While CommonJS might work with transpilation, direct ESM import is recommended. `adoPat` is a named export for generating Azure DevOps Personal Access Tokens.
• runAzureAuthCli
  wrong:

  import { runAzureAuthCli } from 'azureauth';

  correct:

  import { runAzureAuthCli } from 'azureauth/lib/cli';

  For direct programmatic execution of the underlying CLI, rather than high-level functions like `adoPat`, import `runAzureAuthCli` from the specific CLI entry point. This provides more granular control over CLI arguments.
• AzureAuthOptions
  wrong:

  import { AzureAuthOptions } from 'azureauth';

  correct:

  import { type AzureAuthOptions } from 'azureauth';

  This package ships TypeScript types. When importing only types, use `import type` for clarity and to ensure the import is stripped from the JavaScript output.

Quickstart

This quickstart demonstrates how to programmatically obtain an Azure DevOps Personal Access Token using `adoPat`.

import { adoPat } from 'azureauth';

async function getAzureDevOpsPat() {
  try {
    const pat = await adoPat({
      displayName: 'my-cli-auth-pat',
      organization: process.env.AZDO_ORG_URL ?? 'https://dev.azure.com/myorganization',
      promptHint: 'Please authenticate in your browser',
      scope: ['vso.packaging_write'], // Example scope
    });
    console.log('Successfully generated ADO PAT.');
    // In a real application, securely store or use the PAT
    // console.log('PAT:', pat); // Do not log PAT to console in production!
    return pat;
  } catch (error) {
    console.error('Failed to get ADO PAT:', error);
    throw error;
  }
}

getAzureDevOpsPat()
  .then(() => console.log('ADO PAT process completed.'))
  .catch(() => console.error('Exiting due to PAT generation failure.'));