애플리케이션 기본 사용자 인증 정보 설정

이 페이지에서는 다양한 환경에서 클라우드 클라이언트 라이브러리 및 Google API 클라이언트 라이브러리, REST 및 RPC API에 사용하기 위해 애플리케이션 기본 사용자 인증 정보(ADC)에 사용자 인증 정보를 설정하는 방법을 설명합니다. 코드가 실행되는 환경에서 ADC에 사용자 인증 정보를 제공하여 ADC를 설정합니다.

Application Default Credentials (ADC)는 애플리케이션 환경을 기준으로 사용자 인증 정보를 자동으로 검색하기 위해 Google 인증 라이브러리에 사용되는 전략입니다. 그런 다음 인증 라이브러리는 Cloud 클라이언트 라이브러리 및 Google API 클라이언트 라이브러리에 이러한 사용자 인증 정보를 제공합니다. ADC를 사용할 때는 Google Cloud 서비스 및 API에 대한 애플리케이션 인증 방법을 변경하지 않고 개발 또는 프로덕션 환경에서 코드를 실행할 수 있습니다.

ADC가 사용자 인증 정보를 찾는 위치와 순서에 대한 자세한 내용은 애플리케이션 기본 사용자 인증 정보 작동 방법을 참조하세요.

API 키를 사용하는 경우 ADC를 설정할 필요가 없습니다. 자세한 내용은 API 키 사용을 참조하세요.

ADC에 사용자 인증 정보를 제공하는 방법

코드가 실행되는 환경을 선택합니다.

• 로컬 개발 환경
• Cloud Shell 또는 기타 Google Cloud 클라우드 기반 개발 환경
• 서비스 계정 연결을 지원하는 Compute Engine 또는 기타 Google Cloud 서비스
• Google Kubernetes Engine 또는 GKE Enterprise
• 온프레미스 또는 다른 클라우드 제공업체

로컬 개발 환경

로컬 개발 환경에서 ADC에 사용자 인증 정보 또는 서비스 계정 사용자 인증 정보를 제공할 수 있습니다.

사용자 인증 정보

코드가 개발 워크스테이션과 같은 로컬 개발 환경에서 실행되는 경우 최고의 옵션은 사용자 계정과 연결된 사용자 인증 정보를 사용하는 것입니다.

로컬 ADC 파일을 만들기 위해 사용자 인증 정보를 제공할 때는 다음 사항에 유의해야 합니다.

• 추가 매개변수 또는 구성 없이는 사용자 인증 정보가 Cloud Translation API 또는 Cloud Vision API와 같은 일부 메서드 및 API에서 작동하지 않습니다. API가 프로젝트에서 사용 설정되지 않았거나 사용 가능한 할당량 프로젝트가 없다는 오류 메시지가 표시되면 ADC 설정 문제 해결을 참조하세요.

• 로컬 ADC에는 액세스 및 갱신 토큰이 포함되어 있습니다. 파일 시스템에 대해 액세스가 있는 모든 사용자가 이러한 사용자 인증 정보에 액세스할 수 있습니다. 이러한 로컬 사용자 인증 정보가 더 이상 필요하지 않으면 gcloud auth application-default revoke 명령어를 사용하여 취소할 수 있습니다.

• 사용자 계정에 프로젝트에 필요한 Identity and Access Management(IAM) 역할이 없으면 코드가 일부 리소스에 액세스하지 못할 수 있습니다. 이 경우 필요한 역할을 부여받아야 합니다.

• 로컬 ADC 파일은 gcloud CLI 구성이 아닌 사용자 계정과 연결됩니다. 다른 gcloud CLI 구성으로 변경해도 로컬 ADC 파일 또는 ADC에 제공된 사용자 인증 정보는 영향을 받지 않습니다.

ADC에 사용자 인증 정보를 제공하는 방법은 사용자 계정을 Google에서 관리하는지(Google 계정), 아니면 다른 ID 공급업체(IdP)에서 관리하고 직원 ID 제휴를 사용하여 제휴하는지에 따라 다릅니다.

Google 계정의 사용자 인증 정보 제공

Google 계정의 사용자 인증 정보를 ADC에 제공하려면 Google Cloud CLI를 사용합니다.

1. gcloud CLI를 설치하고 초기화합니다.

   gcloud CLI를 초기화할 때 애플리케이션에 필요한 리소스에 액세스할 수 있는 권한이 있는 Google Cloud 프로젝트를 지정해야 합니다.

2. 사용자 인증 정보 파일을 만듭니다.

   gcloud auth application-default login

   로그인 화면이 표시됩니다. 로그인 후 사용자 인증 정보는 ADC에 사용하는 로컬 사용자 인증 정보 파일에 저장됩니다.

외부 IdP에서 관리하는 계정의 사용자 인증 정보 제공

외부 IdP에서 관리하고 직원 ID 제휴를 사용하여 제휴하는 사용자 계정의 사용자 인증 정보를 제공하려면 직원 풀 공급업체 이름이 필요합니다. 관리자에게 이 정보를 받아야 합니다. 직원 풀 공급업체 이름 형식은 다음과 같습니다.

locations/global/workforcePools/POOL_ID/provider/PROVIDER_ID

제휴 사용자 계정의 사용자 인증 정보를 ADC에 제공합니다.

1. 로그인 구성 파일을 만들고 iam workforce-pools create-login-config 명령어를 사용하여 해당 위치를 가리키도록 gcloud CLI auth/login_config_file 속성을 설정합니다.

   gcloud iam workforce-pools create-login-config PROVIDER_ID \
   --output-file=LOGIN_CONFIG_FILE --activate
   

   다음을 바꿉니다.

   • PROVIDER_ID: 공급업체 ID
   • LOGIN_CONFIG_FILE: 지정하는 구성 파일의 경로(예: login.json)

   생성된 파일은 다음 예시와 유사합니다.

   {
   "type": "external_account_authorized_user_login_config",
   "audience": "//iam.googleapis.com/PROVIDER_ID",
   "auth_url": "https://auth.cloud.google/authorize",
   "token_url": "https://sts.googleapis.com/v1/oauthtoken",
   "token_info_url": "https://sts.googleapis.com/v1/introspect",
   }
   

   주의: 먼저 이 파일의 콘텐츠가 올바른지 확인한 다음 파일을 보호하는 것이 좋습니다. 예를 들어 파일을 읽기 전용으로 설정하고 ACL을 사용하여 액세스를 제한합니다. 파일이 검증되지 않으면 이 파일에 대해 쓰기 액세스 권한이 있는 악의적인 행위자가 엔드포인트를 변경하고 사용자 인증 정보를 가로챌 수 있습니다.

2. 로그인 파일을 사용하여 gcloud CLI에 로그인합니다.

   gcloud auth login
   

3. gcloud CLI를 초기화합니다.

   gcloud init
   

4. 로컬 ADC 파일을 만듭니다.

   gcloud auth application-default login
   

자세한 내용은 직원 ID 제휴를 참조하세요.

서비스 계정 사용자 인증 정보

서비스 계정 가장 기능 또는 서비스 계정 키를 사용하여 서비스 계정의 사용자 인증 정보로 ADC를 설정할 수 있습니다.

서비스 계정 가장

서비스 계정 가장을 사용하여 로컬 애플리케이션 기본 사용자 인증 정보(ADC) 파일을 설정할 수 있습니다. 가장을 지원하는 클라이언트 라이브러리는 이러한 사용자 인증 정보를 자동으로 사용할 수 있습니다. 가장을 사용하여 생성된 로컬 ADC 파일은 다음 언어에서 지원됩니다.

• C#
• Go
• Java
• Node.js
• Python

가장하려는 서비스 계정에 대한 서비스 계정 토큰 생성자(roles/iam.serviceAccountTokenCreator) IAM 역할이 있어야 합니다. 자세한 내용은 필수 역할을 참조하세요.

서비스 계정 가장을 사용하여 로컬 ADC 파일을 만듭니다.

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

서비스 계정 키

로컬 개발에 사용자 인증 정보 또는 서비스 계정 가장을 사용할 수 없으면 서비스 계정 키를 사용할 수 있습니다.

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키의 보안 및 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 사용자가 담당해야 합니다. 서비스 계정 키를 만들 수 없는 경우 조직의 서비스 계정 키 생성이 사용 중지될 수 있습니다. 자세한 내용은 기본 보안별 조직 리소스 관리를 참조하세요.

서비스 계정 키를 만들고 이를 ADC에 제공하려면 다음 안내를 따르세요.

1. 서비스 계정 키 만들기의 안내에 따라 애플리케이션에 필요한 역할, 서비스 계정에 대한 키를 사용하여 서비스 계정을 만듭니다.

2. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용자 인증 정보가 포함된 JSON 파일의 경로로 설정합니다. 이 변수는 현재 셸 세션에만 적용되므로 새 세션을 열면 변수를 다시 설정합니다.

   예: Linux 또는 macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH를 사용자 인증 정보가 포함된 JSON 파일의 경로로 바꿉니다.

   예를 들면 다음과 같습니다.

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   예: Windows

   PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH를 사용자 인증 정보가 포함된 JSON 파일의 경로로 바꿉니다.

   예를 들면 다음과 같습니다.

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   명령 프롬프트:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   KEY_PATH를 사용자 인증 정보가 포함된 JSON 파일의 경로로 바꿉니다.

참고: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하면 ADC가 이 위치를 먼저 확인한 후 필요한 경우에만 다른 위치를 확인합니다.

Google Cloud 클라우드 기반 개발 환경

Cloud Shell 또는 Cloud Code와 같은 Google Cloud 클라우드 기반 개발 환경을 사용할 때 이 도구는 사용자가 로그인할 때 제공한 사용자 인증 정보를 사용하고 필요한 승인을 관리합니다. 이러한 환경에서는 gcloud CLI를 사용하여 ADC에 사용자 인증 정보를 제공할 수 없습니다. ADC에 다른 사용자 계정을 제공하거나 서비스 계정을 사용하여 사용자 인증 정보를 제공해야 하는 경우 로컬 개발 환경 또는 Google Cloud 컴퓨팅 리소스를 개발 환경으로 사용합니다.

서비스 계정 연결을 지원하는 Google Cloud 서비스

Compute Engine, App Engine, Cloud Functions와 같은 일부 Google Cloud 서비스는 일부 유형의 리소스에 대한 사용자 관리 서비스 계정 연결을 지원합니다. 일반적으로 서비스 계정 연결은 해당 서비스의 리소스가 애플리케이션 코드를 실행하거나 포함할 수 있을 때 지원됩니다. 서비스 계정을 리소스에 연결할 때는 리소스에서 실행되는 코드가 이 서비스 계정을 해당 ID로 사용할 수 있습니다.

사용자 관리 서비스 계정 연결은 Google Cloud에서 실행되는 프로덕션 코드에 대해 ADC에 사용자 인증 정보를 제공하기 위해 선호되는 방법입니다.

참고: 또한 이러한 많은 Google Cloud 서비스에서 기본 서비스 계정이 제공됩니다. 기본적으로 기본 서비스 계정에는 최소 권한의 원칙을 위반하는 높은 권한이 부여되기 때문에 기본 서비스 계정 사용은 권장되지 않습니다.

서비스 계정에 제공해야 하는 역할 확인에 대한 자세한 내용은 사전 정의된 역할 선택을 참조하세요.

서비스 계정에 연결할 수 있는 리소스 및 리소스에 서비스 계정 연결에 대한 자세한 내용은 서비스 계정 연결에 대한 IAM 문서를 참조하세요.

인증을 설정합니다.

1. 서비스 계정을 만듭니다.

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   SERVICE_ACCOUNT_NAME을 서비스 계정 이름으로 바꿉니다.

2. 프로젝트 및 리소스에 대한 액세스 권한을 제공하려면 서비스 계정에 역할을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   다음을 바꿉니다.

   • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
   • PROJECT_ID: 서비스 계정을 만든 프로젝트 ID입니다.
   • ROLE: 부여할 역할입니다.
   참고: --role 플래그는 서비스 계정이 프로젝트에서 액세스할 수 있는 리소스에 영향을 줍니다. 이러한 역할을 취소하거나 나중에 추가 역할을 부여할 수 있습니다. 프로덕션 환경에서는 소유자, 편집자 또는 뷰어 역할을 부여하지 마세요. 대신 요구사항을 충족하는 사전 정의된 역할 또는 커스텀 역할을 부여합니다.
3. 서비스 계정에 다른 역할을 부여하려면 이전 단계에서 한 것처럼 명령어를 실행합니다.

4. Google 계정에 서비스 계정 역할을 사용하고 서비스 계정을 다른 리소스에 연결할 수 있게 해주는 역할을 부여합니다.

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   다음을 바꿉니다.

   • SERVICE_ACCOUNT_NAME: 서비스 계정의 이름입니다.
   • PROJECT_ID: 서비스 계정을 만든 프로젝트 ID입니다.
   • USER_EMAIL: Google 계정의 이메일 주소입니다.

GKE 또는 GKE Enterprise

GKE 또는 GKE Enterprise에서 실행되는 컨테이너화된 애플리케이션의 인증은 로컬 테스트 환경과 Google Cloud 환경 사이에 다르게 처리됩니다.

컨테이너화된 애플리케이션 로컬 테스트

로컬 워크스테이션에서 컨테이너화된 애플리케이션을 테스트하려면 로컬 사용자 인증 정보 파일로 인증하도록 컨테이너를 구성할 수 있습니다. 컨테이너를 테스트하려면 minikube 및 gcp-auth 부가기능과 같은 로컬 Kubernetes 구현을 사용합니다.

Google Cloud에서 컨테이너화된 애플리케이션 실행

컨텍스트에 따라 Google Cloud 컨테이너화된 환경의 인증을 다르게 설정합니다.

• GKE Enterprise의 경우 인증 개요 및 Fleet 워크로드 아이덴티티 사용을 참조하세요.
• GKE의 경우 GKE에 워크로드 아이덴티티 사용을 참조하세요.
• Cloud Run for Anthos의 경우 Cloud Run for Anthos에 워크로드 아이덴티티 사용을 참조하세요.

온프레미스 또는 다른 클라우드 제공업체

Google Cloud 외부에서 애플리케이션을 실행하는 경우 Google Cloud에서 인식된 사용자 인증 정보를 Google Cloud 서비스에 제공해야 합니다.

워크로드 아이덴티티 제휴

다른 IdP의 사용자 인증 정보를 사용하여 Google Cloud에 인증을 수행하기 위해 선호되는 방법은 워크로드 아이덴티티 제휴를 사용하는 것입니다. 사용자 인증 정보 구성 파일을 만들고 이를 가리키도록 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정합니다. 이 방법은 서비스 계정 키를 만드는 것보다 안전합니다.

ADC에 대해 워크로드 아이덴티티 제휴를 설정하는 방법은 워크로드 아이덴티티 제휴 구성 및 아이덴티티 제휴를 통해 단기 사용자 인증 정보 가져오기를 참조하세요.

서비스 계정 키

워크로드 아이덴티티 제휴를 구성할 수 없으면 서비스 계정을 만들고, 여기에 애플리케이션에 필요한 IAM 역할을 부여하고, 서비스 계정에 대해 키를 만들어야 합니다.

참고: 서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 가능한 한 서비스 계정 키보다 안전한 대안을 선택해야 합니다. 서비스 계정 키로 인증해야 하는 경우 비공개 키의 보안 및 서비스 계정 키 관리 권장사항에 설명된 기타 작업을 사용자가 담당해야 합니다. 서비스 계정 키를 만들 수 없는 경우 조직의 서비스 계정 키 생성이 사용 중지될 수 있습니다. 자세한 내용은 기본 보안별 조직 리소스 관리를 참조하세요.

서비스 계정 키를 만들고 이를 ADC에 제공하려면 다음 안내를 따르세요.

1. 서비스 계정 키 만들기의 안내에 따라 애플리케이션에 필요한 역할, 서비스 계정에 대한 키를 사용하여 서비스 계정을 만듭니다.

   GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용자 인증 정보가 포함된 JSON 파일의 경로로 설정합니다. 이 변수는 현재 셸 세션에만 적용되므로 새 세션을 열면 변수를 다시 설정합니다.

   예: Linux 또는 macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH를 사용자 인증 정보가 포함된 JSON 파일의 경로로 바꿉니다.

   예를 들면 다음과 같습니다.

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   예: Windows

   PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH를 사용자 인증 정보가 포함된 JSON 파일의 경로로 바꿉니다.

   예를 들면 다음과 같습니다.

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   명령 프롬프트:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   KEY_PATH를 사용자 인증 정보가 포함된 JSON 파일의 경로로 바꿉니다.

   참고: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하면 ADC가 이 위치를 먼저 확인한 후 필요한 경우에만 다른 위치를 확인합니다.

다음 단계

• ADC에서 사용자 인증 정보를 찾는 방법 자세히 알아보기
• Cloud 클라이언트 라이브러리 사용 인증하기
• Google에서 인증 살펴보기