npm용 Artifact Registry에 대한 인증 구성

제3자 애플리케이션을 사용하여 저장소에 연결할 때는 Artifact Registry에 인증해야 합니다.

Cloud Build 또는 Google Kubernetes Engine 및 Cloud Run과 같은 Google Cloud 런타임 환경에 대한 인증을 구성할 필요는 없지만 필요한 권한이 구성되어 있는지 확인해야 합니다.

시작하기 전에

Google Cloud CLI를 설치한 후 다음 명령어를 실행하여 초기화합니다.
```
gcloud init
```
참고: gcloud CLI를 이전에 설치했으면 gcloud components update를 실행하여 최신 버전을 사용할 수 있는지 확인합니다.
(선택사항) cloud CLI 명령어의 기본값을 구성합니다.
Windows에서 저장소에 연결하는 경우 PowerShell을 설치합니다.
애플리케이션 대신 작동하도록 서비스 계정을 만듭니다.
npm을 처음 사용하는 경우 개요를 참조하여 범위가 지정된 패키지와 인증 설정의 구성 파일에 대해 알아보세요.

개요

Artifact Registry는 다음과 같은 인증 방법을 지원합니다.

사용자 인증 정보 도우미 사용: 이 옵션은 가장 유연성이 뛰어납니다. npm 구성에 도우미를 포함하면 Artifact Registry는 환경에서 서비스 계정 사용자 인증 정보를 검색합니다.
사용자 인증 정보로 서비스 계정 키 지정: 애플리케이션이 기본 애플리케이션 사용자 인증 정보를 지원하지 않지만 사용자 이름과 비밀번호로 인증을 지원하는 경우 이 옵션을 사용합니다.

사용자 인증 정보 도우미로 인증

google-artifactregistry-auth는 Artifact Registry 저장소의 사용자 인증 정보를 가져오는 클라이언트 라이브러리입니다.

Artifact Registry는 다음 순서로 사용자 인증 정보를 검색합니다.

애플리케이션 기본 사용자 인증 정보(ADC) - 다음 순서로 사용자 인증 정보를 찾는 전략
1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 정의된 사용자 인증 정보
2. Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine 또는 Cloud Functions의 기본 서비스 계정에서 제공하는 사용자 인증 정보
gcloud auth application-default login 명령어의 사용자 인증 정보를 포함한 Google Cloud CLI에서 제공하는 사용자 인증 정보

GOOGLE_APPLICATION_CREDENTIALS 변수를 사용하면 인증용 계정이 명시적으로 표시되어 문제 해결이 간편해집니다. 이 변수를 사용하지 않는 경우 ADC에서 사용할 수 있는 모든 계정에 필요한 권한이 있는지 확인합니다. 예를 들어 Compute Engine VM, Google Kubernetes Engine 노드, Cloud Run 버전의 기본 서비스 계정은 저장소에 대한 읽기 전용 액세스 권한이 있습니다. 기본 서비스 계정을 사용하여 이러한 환경에서 업로드하려면 권한을 수정해야 합니다.

서비스 계정을 만들고 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하려면 다음 안내를 따르세요.

애플리케이션 대신 작동하도록 서비스 계정을 만들거나 CI/CD 자동화에 사용할 기존 서비스 계정을 선택합니다.
저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.
저장소와 연결할 때 Artifact Registry 사용자 인증 정보 도우미가 키를 가져올 수 있도록 서비스 계정 키 파일 위치를 변수 GOOGLE_APPLICATION_CREDENTIALS에 할당합니다.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
여기서 KEY-FILE은 서비스 계정 키 파일의 경로입니다.

인증을 구성하려면 다음 안내를 따르세요.

다음 명령어를 실행하여 저장소 구성을 출력합니다.
```
gcloud artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] \
    [--location=LOCATION] \
    --scope=@SCOPE-NAME \
```
각 항목의 의미는 다음과 같습니다.
- PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
- REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
- LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
- SCOPE-NAME은 저장소와 연결할 npm 범위의 이름입니다.
  
  범위를 사용하면 항상 올바른 저장소에서 패키지를 게시하고 설치할 수 있습니다.
  
  범위가 지정되지 않은 패키지는 기본 npm 레지스트리와 연결됩니다(일반적으로 npm 공개 레지스트리). 범위를 지정하지 않으면 반환된 구성이 Artifact Registry 저장소를 기본 레지스트리로 설정합니다. Node.js 프로젝트가 공개 npm 레지스트리와 Artifact Registry 저장소 모두에서 패키지를 설치해야 하는 경우 문제가 발생할 수 있습니다.
Node.js 프로젝트의 .npmrc 구성 파일에 반환된 구성 설정을 추가합니다. 이 파일은 일반적으로 package.json과 동일한 디렉터리에 있습니다.

게시하는 패키지의 Node.js 프로젝트와 npm 저장소에서 종속 항목을 설치할 프로젝트에 이러한 설정을 포함해야 합니다.
연결할 다른 Node.js 저장소가 있는 경우 이전 단계를 반복하여 설정을 가져오고 적절한 .npmrc 파일에 추가합니다.
저장소를 연결할 준비가 되면 인증을 위한 액세스 토큰을 얻습니다.

각 Artifact Registry Node.js 패키지 저장소는 레지스트리 엔드포인트 https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY와 연결됩니다.

print-settings 명령어로 범위를 지정하지 않은 경우 다음 명령어를 실행하여 범위를 Artifact Registry 저장소와 연결할 수 있습니다.

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY/

액세스 토큰 가져오기

액세스 토큰은 60분 동안 유효합니다. 저장소와 상호작용하는 명령어를 실행하기 직전에 액세스 토큰을 생성합니다.

토큰을 받으려면 다음 옵션 중 하나를 사용합니다.

npx 명령어를 사용하여 액세스 토큰을 새로 고칩니다.
1. 공개 npm 레지스트리에 연결하기 위한 사용자 인증 정보가 사용자 npm 구성 파일 ~/.npmrc에 있는지 확인합니다.
2. Node.js 프로젝트 디렉터리에서 다음 명령어를 실행합니다.
```
npx google-artifactregistry-auth
```
  Artifact Registry 저장소가 전역 레지스트리로 설정되었고 패키지 범위가 지정되지 않은 경우, 대신 다음 명령어를 사용하여 명령어가 Artifact Registry 대신 공개 npm 레지스트리에서 사용자 인증 정보 도우미를 다운로드할 수 있게 하세요.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```
프로젝트의 package.json 파일에 스크립트를 추가합니다.
```
"scripts": {
 "artifactregistry-login": "npx google-artifactregistry-auth"
}
```
Node.js 프로젝트 디렉터리에서 스크립트를 실행합니다.
```
npm run artifactregistry-login
```

Artifact Registry는 프로젝트 .npmrc 파일의 Artifact Registry 저장소 설정을 읽고 이를 사용하여 사용자 .npmrc 파일에 토큰 사용자 인증 정보를 추가합니다. 사용자 .npmrc 파일에 토큰을 저장하면 사용자 인증 정보가 소스 코드 및 소스 제어 시스템으로부터 격리됩니다.

--repo-config는 저장소 설정이 포함된 .npmrc 파일입니다. 이 플래그를 지정하지 않은 경우 기본 위치는 현재 디렉터리입니다.
--credential-config는 액세스 토큰을 쓰려는 .npmrc 파일의 경로입니다. 기본값은 사용자 .npmrc 파일입니다.

비밀번호 인증 구성

Node.js 애플리케이션에서 지정된 사용자 이름과 비밀번호로 인증을 요구할 때 이 방법을 사용합니다.

서비스 계정 키는 장기 사용자 인증 정보입니다. 다음 가이드라인을 사용하여 저장소에 대한 액세스를 제한합니다.

저장소와 상호작용할 수 있도록 전용 서비스 계정을 사용하는 것이 좋습니다.
서비스 계정에 필요한 최소한의 Artifact Registry 역할을 부여합니다. 예를 들어 아티팩트만 다운로드하는 서비스 계정에 Artifact Registry 리더를 할당합니다.
조직의 그룹에 특정 저장소에 대한 여러 액세스 수준이 필요한 경우 프로젝트 수준이 아닌 저장소 수준에서 액세스 권한을 부여합니다.
사용자 인증 정보 관리 권장사항을 따릅니다.

서비스 계정을 만들고 인증을 구성하려면 다음 안내를 따르세요.

애플리케이션 대신 작동하도록 서비스 계정을 만들거나 자동화에 사용할 기존 서비스 계정을 선택합니다.

Artifact Registry로 인증을 설정하려면 서비스 계정 키 파일의 위치가 필요합니다. 기존 계정의 경우 서비스 계정 페이지에서 키를 보고 새 키를 만들 수 있습니다.

서비스 계정 페이지로 이동

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키와 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 보호해야 합니다. 서비스 계정 키를 만들 수 없는 경우 서비스 계정 키 생성이 조직에 중지될 수 있습니다. 자세한 내용은 보안 기반 조직 리소스 관리를 참조하세요.
저장소 액세스 권한을 부여하기 위해 서비스 계정에 적절한 Artifact Registry 역할을 부여합니다.
현재 gcloud CLI 세션에서 서비스 계정을 활성화하려면 다음 명령어를 실행합니다.
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
각 항목의 의미는 다음과 같습니다.
- ACCOUNT는 사용자 또는 서비스 계정입니다.
- KEY-FILE은 서비스 계정 JSON 키 파일의 경로입니다.
다음 명령어를 실행하여 저장소 구성을 출력합니다.
```
gcloud artifacts print-settings npm [--project=PROJECT] \
[--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --json-key=KEY-FILE
```
각 항목의 의미는 다음과 같습니다.
- PROJECT는 프로젝트 ID입니다. 이 플래그를 생략하면 현재 프로젝트 또는 기본 프로젝트가 사용됩니다.
- REPOSITORY는 저장소 ID입니다. 기본 Artifact Registry 저장소를 구성한 경우 이 플래그가 명령어에서 생략되었을 때 사용됩니다.
- LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
- SCOPE-NAME은 저장소와 연결할 npm 범위의 이름입니다.
  
  범위를 사용하면 항상 올바른 저장소에서 패키지를 게시하고 설치할 수 있습니다.
  
  범위가 지정되지 않은 패키지는 기본 npm 레지스트리와 연결됩니다(일반적으로 npm 공개 레지스트리). 범위를 지정하지 않으면 반환된 구성이 Artifact Registry 저장소를 기본 레지스트리로 설정합니다. Node.js 프로젝트가 공개 npm 레지스트리와 Artifact Registry 저장소 모두에서 패키지를 설치해야 하는 경우 문제가 발생할 수 있습니다.
- KEY-FILE은 서비스 계정 JSON 키 파일의 경로입니다.
참고: 반환된 구성 설정에는 자리표시자 이메일 주소가 포함되어 있습니다. npm 패키지를 게시하려면 이메일 주소가 npm 구성에 필요합니다. 자리표시자 이메일 주소는 Artifact Registry에서 인증에 사용되지 않습니다.
Node.js 프로젝트의 .npmrc 구성 파일에 반환된 구성 설정을 추가합니다. 이 파일은 일반적으로 package.json과 동일한 디렉터리에 있습니다. 게시하는 패키지의 Node.js 프로젝트와 npm 저장소에서 종속 항목을 설치할 프로젝트에 이러한 설정을 포함해야 합니다.
연결할 다른 Node.js 저장소가 있는 경우 이전 단계를 반복하여 설정을 가져오고 이를 .npmrc 파일에 추가합니다.