인증 설정

이 페이지의 설정에는 민감한 자격 증명이 포함되어 있으며 INI 형식의 파일에 저장됩니다. 이 파일들을 저장소에 커밋하지 마세요.

민감하지 않은 설정(프록시, SSL, 레지스트리 등)은 설정 (pnpm-workspace.yaml)을 참고하세요.

인증 파일 위치#

pnpm은 다음 파일에서 우선순위 순서(높은 순)로 인증 설정을 읽습니다:

<workspace root>/.npmrc — 프로젝트 수준 인증입니다. 이 파일은 .gitignore에 포함되어야 합니다.
<pnpm config>/auth.ini — 기본 사용자 수준 인증 파일입니다. pnpm login은 이 파일에 토큰을 기록합니다.
~/.npmrc — npm에서 쉽게 마이그레이션할 수 있도록 대체 파일로 읽습니다. 다른 파일을 지정하려면 npmrcAuthFile 설정을 사용하세요.

<pnpm config> 디렉터리는 다음과 같습니다:

$XDG_CONFIG_HOME 환경 변수가 설정된 경우: $XDG_CONFIG_HOME/pnpm/
Windows: ~/AppData/Local/pnpm/config/
macOS: ~/Library/Preferences/pnpm/
Linux: ~/.config/pnpm/

인증 설정의 환경 변수#

사용자 수준 인증 파일(<pnpm config>/auth.ini 및 사용자 .npmrc)의 값은 ${NAME} 구문을 사용하여 환경 변수를 참조할 수 있습니다:

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

v11.5.3부터 워크스페이스 루트의 프로젝트 수준 .npmrc에서는 다음 설정에 대해 환경 변수가 확장되지 않습니다:

레지스트리 및 프록시 URL(registry, @scope:registry, 프록시 설정);
URL 범위 키(//로 시작하는 키);
자격 증명 값(_authToken, _auth, _password, username, tokenHelper, cert, key).

이러한 위치 중 어디에든 ${...} 자리 표시자가 포함된 설정은 무시되며, pnpm은 경고를 출력합니다. 프로젝트 .npmrc는 저장소와 함께 체크아웃되므로, 여기서 환경 변수를 확장하면 악의적인 저장소가 설치 중에 사용자 환경의 비밀 정보(CI 토큰 등)를 공격자가 제어하는 레지스트리로 유출할 수 있습니다(GHSA-3qhv-2rgh-x77r).

프로젝트가 //registry.npmjs.org/:_authToken=${NPM_TOKEN}과 같은 줄이 포함된 커밋된 .npmrc에 의존했다면, 대신 토큰을 신뢰할 수 있는 위치로 옮기세요:

설치 전에 토큰을 사용자 수준 인증 파일에 기록하세요(예: CI 단계에서):
```
pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
```
pnpm config set은 기본적으로 프로젝트 .npmrc가 아닌 전역 위치(인증 설정의 경우 <pnpm config>/auth.ini)에 기록하므로, 토큰이 저장소에 들어가지 않습니다.
.npmrc 파일 없이 환경 변수를 통해 자격 증명을 설정하세요(v11.6부터). pnpm은 pnpm_config_//… 환경 변수에서 URL 범위 레지스트리 설정을 읽습니다:
```
env "pnpm_config_//registry.npmjs.org/:_authToken=$NPM_TOKEN" pnpm install
```
변수 이름에 /, :, .가 포함되어 있어, export와 NAME=value 셸 할당 구문에서는 유효하지 않은 식별자로 거부됩니다. 단일 명령에 전달하려면 env 유틸리티를 사용하거나(위 예시 참고), 임의의 변수 이름을 허용하는 도구를 통해 설정하세요(예: CI 제공업체의 환경 설정 또는 Node의 process.env).

이것은 커밋된 //registry.npmjs.org/:_authToken=${NPM_TOKEN} 줄을 파일 없이 대체하는 가장 직접적인 방법입니다. 자격 증명이 적용되는 레지스트리가 (신뢰할 수 있는) 변수 이름에 인코딩되어 있으므로, 악의적인 저장소가 이를 다른 호스트로 리디렉션할 수 없습니다. 이러한 환경 값은 프로젝트 .npmrc보다 우선하지만, 명령줄 옵션에 의해 재정의됩니다. tokenHelper 설정은 의도적으로 환경 변수에서 읽지 않습니다.
또는 ${NPM_TOKEN} 자리 표시자 줄을 유지하되, 저장소 대신 사용자 수준 ~/.npmrc(또는 npmrcAuthFile이 가리키는 파일)에 두세요.
GitHub Actions에서 registry-url 입력을 지정한 actions/setup-node는 인증 설정을 사용자 수준 .npmrc(pnpm이 인식하는 NPM_CONFIG_USERCONFIG 환경 변수가 가리키는 파일)에 기록하므로, NODE_AUTH_TOKEN 환경 변수를 통한 인증은 계속 작동합니다.
각 CI 파이프라인을 쉽게 수정할 수 없다면, CI 환경에서 환경 변수 하나를 설정하여 프로젝트 .npmrc를 신뢰할 수 있다고 선언할 수 있습니다(예: 조직 또는 워크스페이스 수준에서):
```
PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc
```
이것은 npmrcAuthFile 설정의 환경 변수 형태입니다. pnpm이 프로젝트의 .npmrc를 사용자 수준 인증 파일로 읽도록 하므로(상대 경로는 작업 디렉터리를 기준으로 해석됨), 파일 안의 환경 변수가 이전처럼 확장됩니다. 신뢰 선언은 저장소가 아닌 환경에서 오므로, 악의적인 저장소가 이를 대신 설정할 수 없습니다. npm 방식의 NPM_CONFIG_USERCONFIG 변수도 대체 수단으로 인식됩니다.

위험

신뢰할 수 있는 저장소만 빌드하는 환경에서만 사용하세요. 이 설정은 tokenHelper를 사용자 수준 설정에서만 지정할 수 있다는 제한을 포함하여, 체크아웃된 저장소에 대한 이 보호 기능을 완전히 비활성화합니다.

프로젝트 .npmrc의 레지스트리 및 프록시 URL(registry, @scope:registry, proxy, https-proxy, http-proxy)에도 같은 규칙이 적용됩니다. 환경 변수를 사용해 레지스트리 URL을 구성했다면, 설정을 신뢰할 수 있는 소스로 옮기세요 — 사용자 수준 ~/.npmrc 또는 pnpm config set "<key>" <value>. URL이 비밀이 아니라면, ${...} 자리 표시자만 무시되므로 확장된 값을 프로젝트 .npmrc에 직접 작성할 수도 있습니다. pnpm-workspace.yaml의 레지스트리 설정은 설정을 참고하세요.

인증 설정#

<URL>:_authToken#

지정된 레지스트리에 액세스할 때 사용할 인증 bearer 토큰을 정의합니다. 예시:

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

환경 변수를 사용할 수도 있습니다. 예시:

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

환경 변수는 사용자 수준 인증 파일에서만 확장되며, 프로젝트 수준 .npmrc에서는 확장되지 않습니다. 인증 설정의 환경 변수를 참고하세요.

스코프별 인증 토큰#

추가된 버전: v11.7.0

pnpm은 패키지 스코프가 같은 레지스트리 URL을 가리키더라도 스코프마다 다른 인증 토큰을 사용할 수 있습니다. 인증 키에서 레지스트리 URL 뒤에 패키지 스코프를 추가하세요:

@org-a:registry=https://npm.pkg.github.com/
@org-b:registry=https://npm.pkg.github.com/

//npm.pkg.github.com/:@org-a:_authToken=ORG_A_TOKEN
//npm.pkg.github.com/:@org-b:_authToken=ORG_B_TOKEN

//npm.pkg.github.com/:_authToken=FALLBACK_TOKEN

@org-a/*를 설치하거나 게시할 때 pnpm은 ORG_A_TOKEN을 사용하고, @org-b/*에는 ORG_B_TOKEN을 사용합니다. 선택적으로, 일치하는 스코프가 없는 패키지는 레지스트리 전체 토큰(위의 FALLBACK_TOKEN)이 제공된 경우 이를 대신 사용합니다.

pnpm login --registry=https://npm.pkg.github.com --scope=@org-a는 같은 스코프별 인증 키에 토큰을 기록합니다.

이는 조직별 또는 스코프별로 토큰을 발급하는 레지스트리(GitHub Packages 등)에 유용합니다. 이전에는 레지스트리 URL로만 인증이 선택되었기 때문에, 레지스트리를 공유하는 두 스코프는 토큰도 공유해야 했습니다.

<URL>:tokenHelper#

토큰 헬퍼는 인증 토큰을 출력하는 실행 파일입니다. 이것은 authToken이 상수 값이 아니라 정기적으로 새로 고쳐지는 상황에서 사용할 수 있습니다. 스크립트나 다른 도구가 기존 리프레시 토큰을 사용하여 새 액세스 토큰을 얻을 수 있습니다.

헬퍼에 대한 경로 구성은 인수가 없는 절대 경로여야 합니다. 보안을 위해 사용자 .npmrc에서만 이 값을 설정할 수 있습니다. 그렇지 않으면 프로젝트가 프로젝트의 로컬 .npmrc 에 값을 배치하고 임의의 실행 파일을 실행할 수 있습니다.

기본 레지스트리에 대한 토큰 헬퍼 설정:

tokenHelper=/home/ivan/token-generator

지정된 레지스트리에 대한 토큰 헬퍼 설정:

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

_auth#

추가된 버전: v11.10.0

레지스트리 URL을 키로 하는 하나의 구조화된 값으로 레지스트리 인증을 설정합니다. 이는 여러 개의 //host/:_authToken=… 항목을 대체하는 방법으로, URL 범위 형식(변수 이름에 /, :, .가 포함됨)을 일부 러너에서 환경 변수로 전달할 수 없는 CI를 위해 설계되었습니다.

_auth는 신뢰할 수 있는 두 위치에서만 인식됩니다:

전역 pnpm 설정(config.yaml);
pnpm_config__auth 환경 변수(CI용).

프로젝트의 pnpm-workspace.yaml이나 .npmrc에서는 무시되므로, 체크아웃된 저장소가 레지스트리 인증을 제공할 수 없습니다.

값의 키가 레지스트리 URL이므로, 각 비밀 정보는 이를 받을 수 있는 호스트에 명시적으로 연결됩니다. 레지스트리 URL 키는 http 또는 https를 사용해야 하며, 자격 증명, 쿼리 문자열, 프래그먼트를 포함해서는 안 됩니다. 각 레지스트리 URL 안에서 @는 레지스트리 전체(기본) 자격 증명을 의미하며, @org와 같은 패키지 스코프는 같은 호스트에서 해당 스코프에 자격 증명을 연결합니다. 지원되는 자격 증명 필드는 authToken뿐이며(_authToken / bearer 인증에 대응), 사용 중단된 basicAuth / username + password 형식과 tokenHelper는 여기서 허용되지 않습니다.

전역 config.yaml에서:

_auth:
  https://registry.npmjs.org:
    "@":
      authToken: npm-token
    "@org":
      authToken: org-token

동등한 환경 변수(JSON 문자열):

export pnpm_config__auth='{"https://registry.npmjs.org":{"@":{"authToken":"npm-token"},"@org":{"authToken":"org-token"}}}'

pnpm_config__auth(소문자)와 PNPM_CONFIG__AUTH(일부 CI 러너가 적용하는 관례인 대문자) 모두 인식됩니다. 둘 다 설정된 경우 소문자가 우선하며, 소문자 값이 비어 있으면 대문자가 사용됩니다.

각 항목은 신뢰할 수 있는 레지스트리 라우트도 추론합니다: @는 기본 레지스트리를 라우팅하고(pnpm add <pkg>도 그곳에서 해석됨), @org는 해당 스코프를 라우팅합니다. 자격 증명과 대상 호스트가 하나의 신뢰할 수 있는 값으로 전달되므로, 저장소가 제어하는 설정이 토큰을 다른 호스트로 리디렉션할 수 없습니다.

우선순위는 높은 순서대로 다음과 같습니다:

CLI 플래그(--registry, --@scope:registry)
pnpm_config__auth / PNPM_CONFIG__AUTH
전역 config.yaml _auth
pnpm-workspace.yaml

파싱은 엄격합니다: 잘못된 값(잘못된 JSON, 잘못된 구조, 유효하지 않은 레지스트리 URL 또는 스코프, 지원되지 않는 자격 증명 필드)은 조용히 무시되지 않고 즉시 오류와 함께 실패합니다.

인증서 설정#

ca#

기본값: npm CA 인증서
유형: String, Array 또는 null

레지스트리에 대한 SSL 연결을 위해 신뢰되는 인증 기관 서명 인증서입니다. 값은 PEM 형식("Base-64 encoded X.509 (.CER)"이라고도 함)이어야 합니다. 예시:

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

알려진 등록 기관만 허용하려면 null로 설정하고, 특정 서명 기관만 신뢰하려면 해당 CA 인증서로 설정하세요.

인증서 배열을 지정하여 여러 CA를 신뢰할 수 있습니다:

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

strictSsl 설정도 참고하세요.

cafile#

기본값: null
유형: path

하나 이상의 인증 기관 서명 인증서가 포함된 파일의 경로입니다. ca 설정과 비슷하지만, 여러 CA를 허용하며 CA 정보를 CLI로 지정하는 대신 파일에 저장할 수 있습니다.

<URL>:cafile#

지정한 레지스트리에 접근할 때 사용할 인증 기관 파일의 경로를 정의합니다. 예시:

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

<URL>:ca#

버전 10.25.0에서 추가됨

지정한 레지스트리에 대한 인라인 인증 기관 인증서를 정의합니다. 값은 전역 ca 설정과 마찬가지로 PEM으로 인코딩되어야 하지만, 일치하는 레지스트리 URL에만 적용됩니다.

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

cert#

기본값: null
유형: String

레지스트리에 접근할 때 전달할 클라이언트 인증서입니다. 값은 PEM 형식("Base-64 encoded X.509 (.CER)"이라고도 함)이어야 합니다. 예시:

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

인증서 파일의 경로가 아닙니다.

<URL>:cert#

버전 10.25.0에서 추가됨

지정한 레지스트리에 접근할 때 사용할 인라인 클라이언트 인증서를 정의합니다. 예시:

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

<URL>:certfile#

지정한 레지스트리에 접근할 때 사용할 인증서 파일의 경로를 정의합니다. 예시:

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

key#

기본값: null
유형: String

레지스트리에 접근할 때 전달할 클라이언트 키입니다. 값은 PEM 형식("Base-64 encoded X.509 (.CER)"이라고도 함)이어야 합니다. 예시:

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

키 파일의 경로가 아닙니다. 키를 인라인으로 넣는 대신 파일 시스템을 참조해야 한다면 <URL>:keyfile을 사용하세요.

이 설정에는 민감한 정보가 포함되어 있습니다. 저장소에 커밋되는 로컬 .npmrc 파일에 작성하지 마세요.

<URL>:key#

버전 10.25.0에서 추가됨

지정한 레지스트리 URL에 대한 인라인 클라이언트 키를 정의합니다.

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

<URL>:keyfile#

지정한 레지스트리에 접근할 때 사용할 클라이언트 키 파일의 경로를 정의합니다. 예시:

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