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

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

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

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

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

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

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

로컬 개발 환경

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

사용자 인증 정보

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

사용자 계정으로 ADC를 구성할 때는 다음 사항에 유의해야 합니다.

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

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

  • 로컬 ADC 파일은 gcloud CLI 구성이 아닌 사용자 계정과 연결됩니다. 다른 gcloud CLI 구성으로 변경하면 gcloud CLI에서 사용되는 ID가 변경될 수 있지만 로컬 ADC 파일 또는 ADC 구성에 영향을 주지 않습니다.

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

Google 계정으로 ADC 구성

Google 계정으로 ADC를 구성하려면 Google Cloud CLI를 사용합니다.

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

  2. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

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

외부 IdP에서 관리되는 계정을 사용하여 ADC 구성

외부 IdP에서 관리하고 직원 ID 제휴를 사용하여 제휴된 사용자 계정에 대해 ADC를 구성하려면 다음을 수행합니다.

  1. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command: 

    gcloud init

  2. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

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

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

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

서비스 계정 가장

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

  • C#
  • Go
  • 자바
  • Node.js
  • Python

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

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

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

이제 사용자 인증 정보로 로컬 ADC 파일을 설정한 후와 동일한 방식으로 지원되는 언어를 사용하여 클라이언트 라이브러리를 사용할 수 있습니다. 사용자 인증 정보는 인증 라이브러리에서 자동으로 찾습니다. 자세한 내용은 클라이언트 라이브러리 사용을 위한 인증을 참조하세요.

서비스 계정 키

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

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

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

    Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

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

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

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

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

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

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

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

Set up authentication:

  1. Create the service account: 

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Replace SERVICE_ACCOUNT_NAME with a name for the service account.

  2. To provide access to your project and your resources, grant a role to the service account: 

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

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • ROLE: the role to grant
  3. To grant another role to the service account, run the command as you did in the previous step.

  4. Grant the required role to the principal that will attach the service account to other resources. 

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

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • USER_EMAIL: the email address for a Google Account

GKE

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

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

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

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

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

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

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

워크로드 아이덴티티 제휴

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

ADC용 워크로드 아이덴티티 제휴 설정에 대한 도움말은 다른 클라우드와의 워크로드 아이덴티티 제휴를 참조하세요.

서비스 계정 키

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

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

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

    Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

다음 단계