{"id":16764,"library":"azureauth","title":"Azure DevOps Authentication CLI Wrapper","description":"The `azureauth` package serves as a Node.js wrapper for the `microsoft-authentication-cli`, designed to streamline Azure Active Directory (AAD) authentication processes within Node.js applications and npm scripts. Its primary utility lies in automating the download and management of the underlying `azureauth` CLI executable, ensuring it's scoped locally to `./node_modules/.bin`. This unique approach allows for multiple versions of the AzureAuth CLI to coexist on a single machine, mitigating versioning conflicts. As of version 0.14.0, the package is in active pre-1.0 development, indicating an iterative release cadence with potential API changes. It is particularly useful for scenarios requiring Personal Access Token (PAT) generation for Azure DevOps (ADO) feeds, offering a cross-platform alternative to Windows-only tools like `vsts-npm-auth`. While `@azure/identity` provides a comprehensive SDK for general Azure authentication, `azureauth` specifically targets CLI-driven AAD authentication tasks.","status":"active","version":"0.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/microsoft/ado-npm-auth","tags":["javascript","node","azureauth","aad","azure active directory","authentication","typescript"],"install":[{"cmd":"npm install azureauth","lang":"bash","label":"npm"},{"cmd":"yarn add azureauth","lang":"bash","label":"yarn"},{"cmd":"pnpm add azureauth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { adoPat } = require('azureauth');","symbol":"adoPat","correct":"import { adoPat } from 'azureauth';"},{"note":"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.","wrong":"import { runAzureAuthCli } from 'azureauth';","symbol":"runAzureAuthCli","correct":"import { runAzureAuthCli } from 'azureauth/lib/cli';"},{"note":"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.","wrong":"import { AzureAuthOptions } from 'azureauth';","symbol":"AzureAuthOptions","correct":"import { type AzureAuthOptions } from 'azureauth';"}],"quickstart":{"code":"import { adoPat } from 'azureauth';\n\nasync function getAzureDevOpsPat() {\n  try {\n    const pat = await adoPat({\n      displayName: 'my-cli-auth-pat',\n      organization: process.env.AZDO_ORG_URL ?? 'https://dev.azure.com/myorganization',\n      promptHint: 'Please authenticate in your browser',\n      scope: ['vso.packaging_write'], // Example scope\n    });\n    console.log('Successfully generated ADO PAT.');\n    // In a real application, securely store or use the PAT\n    // console.log('PAT:', pat); // Do not log PAT to console in production!\n    return pat;\n  } catch (error) {\n    console.error('Failed to get ADO PAT:', error);\n    throw error;\n  }\n}\n\ngetAzureDevOpsPat()\n  .then(() => console.log('ADO PAT process completed.'))\n  .catch(() => console.error('Exiting due to PAT generation failure.'));","lang":"typescript","description":"This quickstart demonstrates how to programmatically obtain an Azure DevOps Personal Access Token using `adoPat`."},"warnings":[{"fix":"Refer to the GitHub repository's release notes for specific breaking changes in newer versions and update code accordingly.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<0.14.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","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.","error":"'azureauth' is not recognized as an internal or external command, operable program or batch file."},{"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`.","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.","error":"code E401 npm ERR! Unable to authenticate, need: Bearer authorization."},{"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.","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.","error":"Error: User canceled authentication or timed out."}],"ecosystem":"npm","meta_description":null}