REST 사용을 위한 인증

이 페이지에서는 Google API에 REST 요청을 보낼 때의 인증 방법을 설명합니다.

Google 클라이언트 라이브러리를 사용할 때 인증하는 방법에 대한 자세한 내용은 클라이언트 라이브러리를 사용하여 인증을 참조하세요.

시작하기 전에

이 페이지의 샘플을 실행하려면 다음 단계를 완료합니다.

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

gcloud CLI를 사용하지 않으려면 이 단계를 건너뛰고 서비스 계정 명의 도용 또는 메타데이터 서버를 사용하여 토큰을 생성할 수 있습니다.

사용자 인증 정보 유형

다음 유형의 사용자 인증 정보를 사용하여 REST 호출을 인증할 수 있습니다.

• gcloud CLI 사용자 인증 정보

  이 접근 방법은 로컬 개발 환경에서 REST 메서드에 사용자 인증 정보를 제공하는 가장 쉽고 안전한 방법입니다. 사용자 계정에 호출하려는 메서드에 필요한 Identity and Access Management(IAM) 권한이 있으면 이 방법을 사용하는 것이 좋습니다.

  gcloud 사용자 인증 정보는 gcloud CLI를 사용하여 ADC에 제공하는 사용자 인증 정보와 동일하지 않습니다. 자세한 내용은 gcloud CLI 인증 구성 및 ADC 구성을 참조하세요.

• 애플리케이션 기본 사용자 인증 정보(ADC)에 제공되는 사용자 인증 정보

  이 방법은 ADC가 코드가 실행되는 리소스(예: Compute Engine 가상 머신)에서 사용자 인증 정보를 찾으므로 프로덕션 환경에서 REST 호출을 인증하는 데 선호되는 옵션입니다. 또한 ADC를 사용하여 로컬 개발 환경에서 인증할 수 있습니다. 이 시나리오에서 gcloud CLI는 로컬 파일 시스템에 사용자 인증 정보가 포함된 파일을 만듭니다.

• 서비스 계정을 가장하여 제공하는 사용자 인증 정보

  이 방법을 사용하려면 추가 설정이 필요합니다. 로컬에서 서비스 계정으로 테스트하거나 임시 승격된 권한을 요청하는 등 기존 사용자 인증 정보를 사용하여 다른 서비스 계정에서 단기 사용자 인증 정보를 얻으려는 경우 이 방법을 사용합니다.

• 메타데이터 서버에서 반환된 사용자 인증 정보

  이 방법은 메타데이터 서버에 액세스할 수 있는 환경에서만 작동합니다. 메타데이터 서버에서 반환된 사용자 인증 정보는 연결된 서비스 계정을 사용하여 애플리케이션 기본 사용자 인증 정보에서 찾은 사용자 인증 정보와 동일하지만, 메타데이터 서버에서 명시적으로 액세스 토큰을 요청한 다음 이를 REST 요청과 함께 제공해야 합니다. 메타데이터 서버에서 사용자 인증 정보를 쿼리하려면 HTTP GET 요청이 필요합니다. 이 방법은 Google Cloud CLI에 의존하지 않습니다.

gcloud CLI 사용자 인증 정보

아래 예시를 실행하려면 프로젝트에 대한 resourcemanager.projects.get 권한이 필요합니다. resourcemanager.projects.get 권한은 브라우저 역할(roles/browser)과 같은 다양한 역할에 포함되어 있습니다.

1. gcloud auth print-access-token 명령어를 사용하여 사용자 인증 정보에서 생성된 액세스 토큰을 삽입합니다.

   다음 예시에서는 지정된 프로젝트의 세부정보를 가져옵니다. REST 요청에도 동일한 패턴을 사용할 수 있습니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트 ID 또는 이름입니다.

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   다음 명령어를 실행합니다.

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   다음 명령어를 실행합니다.

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   프로젝트 세부정보가 반환됩니다.

할당량 프로젝트가 필요한 API의 경우 요청에 명시적으로 프로젝트를 설정해야 합니다. 자세한 내용은 이 페이지의 REST 요청에 할당량 프로젝트 설정을 참조하세요.

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

아래 예시를 실행하려면 ADC에 제공하는 사용자 인증 정보와 연결된 주 구성원에게 프로젝트에 대한 resourcemanager.projects.get 권한이 필요합니다. resourcemanager.projects.get 권한은 브라우저 역할(roles/browser)과 같은 다양한 역할에 포함되어 있습니다.

1. ADC에 사용자 인증 정보 제공

   Google Cloud 컴퓨팅 리소스에서 실행하는 경우 사용자 인증 정보를 ADC에 제공하면 안 됩니다. 대신 연결된 서비스 계정을 사용하여 사용자 인증 정보를 제공하세요. 자세한 내용은 서비스 계정 연결을 지원하는 서비스를 참조하세요.

2. gcloud auth application-default print-access-token 명령어를 사용하여 ADC에서 반환된 액세스 토큰을 REST 요청에 삽입합니다.

   다음 예시에서는 지정된 프로젝트의 세부정보를 가져옵니다. REST 요청에도 동일한 패턴을 사용할 수 있습니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트 ID 또는 이름입니다.

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   다음 명령어를 실행합니다.

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   다음 명령어를 실행합니다.

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   프로젝트 세부정보가 반환됩니다.

   요청이 API에서 지원되지 않는 최종 사용자 인증 정보에 대해 오류 메시지를 반환하는 경우 이 페이지의 REST 요청으로 할당량 프로젝트 설정을 참조하세요.

가장된 서비스 계정

서비스 계정을 가장하여 액세스 토큰을 생성하는 가장 간단한 방법은 gcloud CLI를 사용하는 것입니다. 하지만 프로그래매틱 방식으로 토큰을 생성해야 하거나 gcloud CLI를 사용하고 싶지 않은 경우 명의 도용을 사용하여 단기 토큰을 생성할 수 있습니다.

서비스 계정을 가장하는 방법에 대한 자세한 내용은 서비스 계정 가장 사용을 참조하세요.

1. 필수 권한을 검토합니다.

   • 가장을 실행하는 데 사용할 주 구성원에게는 가장된 서비스 계정 (권한 보유 서비스 계정이라고도 함)에 대한 iam.serviceAccounts.getAccessToken 권한이 있어야 합니다. iam.serviceAccounts.getAccessToken 권한은 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)에 포함되어 있습니다. 사용자 계정을 사용하는 경우 프로젝트에 소유자 역할(roles/owner)이 있는 경우에도 이 권한을 추가해야 합니다. 자세한 내용은 필수 권한 설정을 참고하세요.

2. 권한 보유 서비스 계정(가장할 서비스 계정)을 식별하거나 만듭니다.

   권한 보유 서비스 계정에는 API 메서드를 호출하는 데 필요한 권한이 있어야 합니다.

gcloud

1. --impersonate-service-account 플래그와 함께 gcloud auth print-access-token 명령어를 사용하여 권한 보유 서비스 계정에 대한 액세스 토큰을 REST 요청에 삽입합니다.

다음 예시에서는 지정된 프로젝트의 세부정보를 가져옵니다. REST 요청에도 동일한 패턴을 사용할 수 있습니다.

이 예시를 실행하려면 가장하는 서비스 계정에 resourcemanager.projects.get 권한이 필요합니다. resourcemanager.projects.get 권한은 브라우저 역할(roles/browser)과 같은 다양한 역할에 포함되어 있습니다.

다음을 바꿉니다.

• PRIV_SA: 권한 보유 서비스 계정의 이메일 주소입니다. 예를 들면 [e-mail]입니다.

• PROJECT_ID: Google Cloud 프로젝트 ID 또는 이름입니다.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

단기 토큰

서비스 계정 명의 도용을 사용하여 단기 토큰을 생성하려면 단기 액세스 토큰 만들기에 제공된 안내를 따르세요.

메타데이터 서버

메타데이터 서버에서 액세스 토큰을 가져오려면 메타데이터 서버에 액세스할 수 있는 서비스 중 하나를 사용하여 REST 호출을 수행해야 합니다.

• Compute Engine
• App Engine 표준 환경
• App Engine 가변형 환경
• Cloud Run 함수
• Cloud Run
• Google Kubernetes Engine
• Cloud Build

curl과 같은 명령줄 도구를 사용하여 액세스 토큰을 가져온 후 이를 REST 요청에 삽입합니다.

1. 메타데이터 서버에 액세스 토큰을 쿼리합니다.

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   이 요청은 다음 예시와 비슷한 응답을 반환합니다.

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. REST 요청에 액세스 토큰을 삽입하여 다음과 같이 바꿉니다.

   • ACCESS_TOKEN: 이전 단계에서 반환된 액세스 토큰입니다.
   • PROJECT_ID: Google Cloud 프로젝트 ID 또는 이름입니다.

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

REST 요청으로 할당량 프로젝트 설정

사용자 인증 정보로 일부 API를 호출하려면 사용 요금이 청구되고 할당량 추적에 사용되는 프로젝트도 설정해야 합니다. API 호출에서 사용자 인증 정보가 지원되지 않거나 할당량 프로젝트가 설정되지 않았다는 오류 메시지를 반환하는 경우 요청에 할당량 프로젝트를 명시적으로 설정해야 합니다. 할당량 프로젝트를 설정하려면 요청에 x-goog-user-project 헤더를 포함합니다.

이 문제가 발생할 때의 자세한 내용은 사용자 인증 정보가 작동하지 않음을 참조하세요.

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

다음 예시에서는 Cloud Translation API를 사용하여 'hello'라는 단어를 스페인어로 번역합니다. Cloud Translation API는 할당량 프로젝트를 지정해야 하는 API입니다. 샘플을 실행하려면 요청 본문 콘텐츠가 포함된 request.json이라는 파일을 만듭니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 결제 프로젝트로 사용할 Google Cloud 프로젝트의 ID 또는 이름입니다.

JSON 요청 본문:

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

번역 요청이 성공합니다. x-goog-user-project 헤더 없이 명령어를 시도하여 결제 프로젝트를 지정하지 않을 경우 어떻게 되는지 확인할 수 있습니다.

다음 단계

• 인증 개요 확인하기
• 클라이언트 라이브러리로 인증하는 방법 알아보기
• gcloud CLI 인증 구성 및 ADC 구성 이해하기