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

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

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

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

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

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

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

ADC에 사용자 인증 정보를 제공하는 방법은 코드가 실행되는 위치에 따라 달라집니다.

로컬 개발 환경

사용자 인증 정보

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

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

  1. 아직 수행하지 않았으면 gcloud CLI를 설치하고 초기화합니다.

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

    gcloud auth application-default login

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

gcloud CLI를 사용하여 ADC에 사용자 인증 정보를 제공하는 데에는 다음과 같은 제한사항이 있습니다.

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

  • 이 메서드는 파일 시스템의 파일에 사용자 인증 정보를 저장합니다. 파일 시스템에 대해 액세스가 있는 모든 사용자가 이러한 사용자 인증 정보에 액세스할 수 있습니다. 이러한 사용자 인증 정보가 더 이상 필요하지 않으면 이를 취소할 수 있습니다.

    gcloud auth application-default revoke

  • Google 계정에 프로젝트에 필요한 Identity and Access Management(IAM) 역할이 없으면 코드가 일부 리소스에 액세스하지 못할 수 있습니다. 이 경우 보안 관리자에게 필요한 역할을 부여하도록 요청하세요.

ADC 사용자 인증 정보 및 gcloud 사용자 인증 정보

gcloud CLI에 로그인할 때 gcloud auth login 명령어를 사용하여 사용자 인증 정보를 제공합니다. 이 gcloud CLI는 이 정보를 인증 및 승인에 사용하여 Google Cloud 리소스 및 서비스를 관리합니다. 또는 --impersonate-service-account 플래그 또는 auth/impersonate_service_account 속성을 사용하여 서비스 계정을 가장할 수 있습니다. 이러한 사용자 인증 정보는 gcloud 사용자 인증 정보입니다.

gcloud CLI를 사용하여 ADC에 사용자 인증 정보를 제공하는 경우 gcloud auth application-default login 명령어를 사용합니다. 이 명령어는 로컬 개발 환경에서 ADC에 사용하기 위해 사용자 인증 정보를 잘 알려진 위치에 배치합니다. 로컬 ADC 사용자 인증 정보입니다.

로컬 ADC 사용자 인증 정보는 gcloud CLI에서 사용되지 않으며 gcloud 사용자 인증 정보는 ADC에서 사용되지 않습니다. 두 가지 고유한 사용자 인증 정보 집합입니다.

다음 표에서는 두 명령어와 기능을 보여줍니다.

명령어 설명
gcloud auth login

Google Cloud 서비스 액세스를 인증하고 승인하는 데 사용되는 사용자 인증 정보를 허용합니다.

gcloud auth application-default login

로컬 개발 환경에서 사용할 수 있도록 애플리케이션 기본 사용자 인증 정보에 제공되는 사용자 인증 정보를 허용합니다.

일반적으로 동일한 계정을 사용하여 gcloud CLI에 로그인하고 ADC에 사용자 인증 정보를 제공하지만 필요에 따라 다른 계정을 사용할 수 있습니다.

gcloud CLI에 로그인하는 방법은 gcloud CLI 초기화를 참조하세요.

서비스 계정 키

로컬 개발에 사용자 인증 정보를 사용할 수 없으면 서비스 계정 키를 사용할 수 있습니다. 서비스 계정 키는 불필요한 위험을 초래하므로 가능하면 피해야 합니다.

조직 정책에 서비스 계정 만들기를 방해하는 제약조건이 있으면 이 메서드를 사용할 수 없습니다.

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

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

  2. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키가 포함된 JSON 파일의 경로로 설정합니다. 이 변수는 현재 셸 세션에만 적용되므로, 새 세션을 열 경우, 변수를 다시 설정합니다.

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

Cloud Shell 또는 Cloud Code와 같은 Google Cloud 클라우드 기반 개발 환경을 사용할 때 이 도구는 사용자가 로그인할 때 제공한 사용자 인증 정보를 사용하고 필요한 승인을 관리합니다.

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

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

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

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

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

조직 정책에 서비스 계정 만들기를 제한하는 제약조건이 있으면 이 메서드를 사용하여 ADC에 대해 사용자 인증 정보를 제공할 수 없습니다.

Google Cloud 컨테이너화된 환경

컨테이너화된 환경 인증은 개발 환경과 프로덕션 환경 간에 다르게 처리됩니다.

컨테이너화된 환경을 위한 개발

Google Kubernetes Engine 또는 Anthos를 사용하여 애플리케이션을 컨테이너화하려면 gcloud CLI를 사용하여 로컬 개발에 ADC를 사용하거나 로컬 컨테이너를 사용할 수 있습니다.

로컬 컨테이너를 개발 환경으로 사용하는 경우 개인 사용자 인증 정보 파일을 컨테이너에 제공해야 합니다. GCP 인증 minikube 부가기능은 이를 수행하기 위한 한 가지 방법입니다.

컨테이너화된 프로덕션 환경

Google Cloud 컨테이너화된 환경 인증을 설정하는 방법은 사용 중인 환경에 따라 달라집니다.

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

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

워크로드 아이덴티티 제휴

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

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

서비스 계정 키

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

조직 정책에 서비스 계정 만들기를 방해하는 제약조건이 있으면 이 메서드를 사용할 수 없습니다.

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

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

  2. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키가 포함된 JSON 파일의 경로로 설정합니다. 이 변수는 현재 셸 세션에만 적용되므로, 새 세션을 열 경우, 변수를 다시 설정합니다.

ADC 설정 문제 해결

ADC를 사용할 때 발생할 수 있는 몇 가지 일반적인 문제에는 다음과 같은 상황이 포함됩니다.

사용자 인증 정보가 작동하지 않음

API 요청이 이 API에서 지원되지 않는 최종 사용자 인증 정보, 프로젝트에 사용 설정되지 않은 API, 설정 중인 할당량 프로젝트 없음에 대한 오류 메시지가 반환되면 다음 정보를 검토합니다.

두 가지 유형의 Google Cloud API가 있습니다.

  • 리소스 기반 API는 결제 및 할당을 위해 액세스되는 리소스와 연결된 프로젝트를 사용합니다.

  • 클라이언트 기반 API는 결제 및 할당을 위해 리소스에 액세스 중인 계정과 연결된 프로젝트를 사용합니다.

Google 계정 사용자 인증 정보를 클라우드 기반 API에 사용할 경우 계정과 연결된 기본 프로젝트를 결제 목적에 사용할 수 없습니다.

이 문제를 해결하려면 다음 중 한 가지를 따르세요.

  1. 다른 프로젝트를 결제 프로젝트로 사용하도록 ADC를 업데이트합니다.

    gcloud auth application-default set-quota-project YOUR_PROJECT

  2. REST 또는 RPC API를 직접 호출하는 경우 x-goog-user-project HTTP 헤더를 사용하여 각 요청에 결제 프로젝트를 지정합니다. 자세한 내용은 REST 요청을 사용하여 할당량 프로젝트 설정을 참조하세요.

결제 프로젝트로 지정할 수 있으려면 결제 프로젝트에 대해 serviceusage.services.use IAM 권한이 있어야 합니다. serviceusage.services.use 권한은 Service Usage Consumer IAM 역할에 포함되어 있습니다. 프로젝트에 대해 serviceusage.services.use 권한이 없으면 보안 관리자 또는 프로젝트에서 서비스 사용 소비자 역할을 부여할 수 있는 프로젝트 소유자에게 문의하세요.

잘못된 사용자 인증 정보

사용자 인증 정보가 필요한 액세스를 제공하는 것으로 확인되지 않거나 보이지 않으면 ADC가 사용자 인증 정보를 조회하는 순서에 따라 ADC에 제공된 사용자 인증 정보에서 잘못되었을 수 있는 것을 확인합니다. 확인할 몇 가지 항목은 다음과 같습니다.

  • gcloud CLI를 사용하여 Google Cloud에 액세스하는 경우 ADC에 제공된 사용자 인증 정보가 사용되지 않습니다. 대신 gcloud auth login 명령어를 사용하여 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다. 이 두 사용자 인증 정보 집합에 대한 자세한 내용은 ADC 사용자 인증 정보 및 gcloud 사용자 인증 정보를 참조하세요.

  • 서비스 계정 키 또는 다른 JSON 파일을 ADC에 사용하는 경우에만 GOOGLE_APPLICATION_CREDENTIALS 환경 변수가 설정되어 있는지 확인합니다. 환경 변수가 가리키는 사용자 인증 정보가 워크로드 아이덴티티를 포함하여 다른 사용자 인증 정보보다 우선합니다.

  • 요청을 수행하는 주 구성원에게 필요한 IAM 역할이 있는지 확인합니다. 사용자 인증 정보를 사용하는 경우 Google 계정과 관련된 이메일 주소에 역할을 부여해야 합니다. 서비스 계정을 사용하는 경우 서비스 계정에 필요한 역할이 있어야 합니다.

  • API 요청에 API 키를 제공하는 경우 API 키가 다른 위치의 ADC보다 우선합니다. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정했고 API 키를 사용하는 경우 API에서 사용자가 ADC에 제공된 사용자 인증 정보가 무시된다는 경고가 반환될 수 있습니다. 경고를 중지하려면 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정 해제합니다.

인식할 수 없는 사용자 인증 정보 유형

API 요청으로 'JSON에서 사용자 인증 정보를 만드는 중 오류가 발생했습니다. 인식할 수 없는 사용자 인증 정보 유형' 오류가 반환되면 유효한 사용자 인증 정보를 사용 중인지 확인합니다. 클라이언트 ID 파일은 ADC에 대한 사용자 인증 정보를 제공하는 데 지원되지 않습니다.

다음 단계