メインコンテンツまでスキップ
Version: 11.x

Authentication Settings

The settings on this page contain sensitive credentials and are stored in INI-formatted files. Do not commit these files to your repository.

For non-sensitive settings (proxy, SSL, registries, etc.), see Settings (pnpm-workspace.yaml).

Auth file locations​

pnpm reads authentication settings from the following files, in order of priority (highest first):

  1. <workspace root>/.npmrc — project-level auth. This file should be listed in .gitignore.
  2. <pnpm config>/auth.ini — the primary user-level auth file. pnpm login writes tokens here.
  3. ~/.npmrc — read as a fallback for easier migration from npm. Use the npmrcAuthFile setting to point to a different file.

The <pnpm config> directory is:

  • If the $XDG_CONFIG_HOME env variable is set: $XDG_CONFIG_HOME/pnpm/
  • On Windows: ~/AppData/Local/pnpm/config/
  • On macOS: ~/Library/Preferences/pnpm/
  • On Linux: ~/.config/pnpm/

Environment variables in auth settings​

Values in the user-level auth files (<pnpm config>/auth.ini and the user .npmrc) may reference environment variables using the ${NAME} syntax:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Since v11.5.3, environment variables are not expanded in the project-level .npmrc at the workspace root for the following settings:

  • registry and proxy URLs (registry, @scope:registry, proxy settings);
  • URL-scoped keys (keys starting with //);
  • credential values (_authToken, _auth, _password, username, tokenHelper, cert, key).

A setting that contains a ${...} placeholder in any of these positions is ignored, and pnpm prints a warning. The project .npmrc is checked out together with the repository, so expanding environment variables there would allow a malicious repository to exfiltrate secrets from your environment (such as CI tokens) to an attacker-controlled registry during installation (GHSA-3qhv-2rgh-x77r).

If your project relied on a committed .npmrc containing a line like //registry.npmjs.org/:_authToken=${NPM_TOKEN}, move the token to a trusted location instead:

  • Write the token to the user-level auth file before installing (for example, in a CI step):

    pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"

    pnpm config set writes to the global location by default (<pnpm config>/auth.ini for auth settings), not to the project .npmrc, so the token never ends up in the repository.

  • Set the credential through an environment variable, with no .npmrc file at all (since v11.6). pnpm reads URL-scoped registry settings from pnpm_config_//… environment variables:

    export "pnpm_config_//registry.npmjs.org/:_authToken=$NPM_TOKEN"

    This is the most direct, file-free replacement for a committed //registry.npmjs.org/:_authToken=${NPM_TOKEN} line. Because the registry the credential applies to is encoded in the (trusted) variable name, a malicious repository cannot redirect it to another host. Such an environment value overrides the project .npmrc but is itself overridden by a command-line option. The tokenHelper setting is intentionally not read from environment variables.

  • Or keep the ${NPM_TOKEN} placeholder line, but put it in the user-level ~/.npmrc (or the file referenced by npmrcAuthFile) instead of the repository.

  • In GitHub Actions, actions/setup-node with the registry-url input writes the auth setting to a user-level .npmrc (referenced by the NPM_CONFIG_USERCONFIG environment variable, which pnpm honors), so authentication via the NODE_AUTH_TOKEN environment variable continues to work.

  • If you cannot easily modify each CI pipeline, you may declare the project .npmrc trusted by setting a single environment variable in the CI environment (for example, at the organization or workspace level):

    PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc

    This is the env form of the npmrcAuthFile setting: it makes pnpm read the project's .npmrc as the user-level auth file (a relative path is resolved against the working directory), so environment variables in it are expanded as before. Because the trust declaration comes from the environment — not from the repository — a malicious repository cannot set it for you. The npm-style NPM_CONFIG_USERCONFIG variable is also honored as a fallback.

    危険

    Only use this in environments that exclusively build trusted repositories. It disables this protection entirely for the checked-out repository, including the restriction that tokenHelper may only be set in user-level config.

The same rule applies to registry and proxy URLs in a project .npmrc (registry, @scope:registry, proxy, https-proxy, http-proxy). If you used an environment variable to build a registry URL, move the setting to a trusted source — your user-level ~/.npmrc, or pnpm config set "<key>" <value>. If the URL is not secret, you can also write the resolved value directly in the project .npmrc, since only ${...} placeholders are ignored. For registry settings in pnpm-workspace.yaml, see Settings.

Authentication Settings​

<URL>:_authToken​

レジストリにアクセスするときに使用する認証用の Bearer トークンを指定します。 例:

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

環境変数を使用することもできます。 例:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Environment variables are only expanded in user-level auth files, not in the project-level .npmrc. See Environment variables in auth settings.

<URL>:tokenHelper​

tokenHelper とは、アクセストークンを出力する実行ファイルです。 これは、authToken が一定値ではなく定期的に更新されるような場合に使用します。 スクリプトやその他のツールが、既存のリフレッシュトークンを使って新しいアクセストークンを取得できるようになります。

helper へのパスの設定は、引数なしの絶対パスである必要があります。 In order to be secure, it is only permitted to set this value in the user .npmrc. Otherwise a project could place a value in a project's local .npmrc and run arbitrary executables.

デフォルトのレジストリに tokenHelper を設定します：

tokenHelper=/home/ivan/token-generator

指定されたレジストリに tokenHelper を設定します：

//registry.corp.com:tokenHelper=/home/ivan/token-generator

Certificate Settings​

ca​

  • Default: The npm CA certificate
  • Type: String, Array or null

レジストリへのSSL接続をするのに信用する署名用CA証明書を指定します。 値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。 例:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

Null に設定すると、既知の登録者のみを許可できます。もしくは、特定の CA 証明書の署名のみを信頼するように設定できます。

証明書の配列を指定することで、複数の信頼する CA を指定することもできます。

ca[]="..."
ca[]="..."

See also the strictSsl setting.

cafile​

  • Default: null
  • Type: path

ひとつ、もしくは複数のCA 署名用証明書を持つファイルへのパスを指定します。 Similar to the ca setting, but allows for multiple CAs, as well as for the CA information to be stored in a file instead of being specified via CLI.

<URL>:cafile​

Define the path to a Certificate Authority file to use when accessing the specified registry. 例:

//registry.npmjs.org/:cafile=ca-cert.pem

<URL>:ca​

Added in: v10.25.0

Define an inline Certificate Authority certificate for the specified registry. The value must be PEM-encoded, like the global ca setting, but it only applies to the matching registry URL.

//registry.example.com/:ca=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

cert​

  • Default: null
  • Type: String

レジストリにアクセスするときに渡すクライアント証明書。 値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。 例:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

It is not the path to a certificate file.

<URL>:cert​

Added in: v10.25.0

Define an inline client certificate to use when accessing the specified registry. 例:

//registry.example.com/:cert=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:certfile​

Define the path to a certificate file to use when accessing the specified registry. 例:

//registry.npmjs.org/:certfile=server-cert.pem

key​

  • Default: null
  • Type: String

レジストリにアクセスするときに渡すクライアントキー。 値は PEM フォーマット (Base64エンコードされた X.509 (.CER)) で指定します。 例:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

It is not the path to a key file. Use <URL>&#58;keyfile if you need to reference the file system instead of inlining the key.

この設定には機密情報が含まれています。 Don't write it to a local .npmrc file committed to the repository.

<URL>:key​

Added in: v10.25.0

Define an inline client key for the specified registry URL.

//registry.example.com/:key=-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----

<URL>:keyfile​

Define the path to a client key file to use when accessing the specified registry. 例:

//registry.npmjs.org/:keyfile=server-key.pem