이 페이지는 Cloud Translation API를 통해 번역되었습니다.

인증된 Cloud Functions를 호출하는 방법 알아보기

1. 소개

개요

Cloud Functions는 경량형 컴퓨팅 솔루션으로, 서버 또는 런타임 환경을 관리할 필요 없이 HTTPS를 사용하여 트리거하거나 CloudEvents에 응답할 수 있는 단일 목적의 독립형 함수를 만들 수 있습니다.

Cloud Functions에 대한 호출을 제어하는 방법에는 두 가지 주요 접근 방식이 있습니다. ID를 기반으로 액세스 보안 설정하는 것이고 다른 하나는 네트워크 기반 액세스 제어를 사용하여 액세스를 보호하는 것입니다. 이 Codelab에서는 첫 번째 접근 방식에 중점을 두고 함수를 호출하여 ID를 기반으로 액세스를 보호하는 3가지 시나리오를 안내합니다.

gcloud ID 토큰을 사용하여 로컬 개발 및 테스트 목적
로컬에서 개발하고 테스트할 때 서비스 계정을 가장하여 프로덕션과 동일한 사용자 인증 정보를 사용합니다.
Google 클라이언트 라이브러리를 사용하여 Google Cloud API에 대한 인증을 처리합니다(예: 서비스가 함수를 호출해야 할 때

학습할 내용

Cloud 함수에서 인증을 구성하고 인증이 올바르게 구성되었는지 확인하는 방법
gcloud ID의 토큰을 제공하여 로컬 개발 환경에서 인증된 함수 호출
서비스 계정을 만들고 함수를 호출하는 적절한 역할을 부여하는 방법
함수 호출에 적절한 역할이 있는 로컬 개발 환경에서 서비스를 가장하는 방법

2. 설정 및 요구사항

기본 요건

Cloud 콘솔에 로그인했습니다
이전에 HTTP 트리거 2세대 Cloud 함수를 배포했습니다.
(선택사항) 세 번째 시나리오에서는 이 Codelab에서 Node.js와 npm을 예로 사용하지만, Google 인증 클라이언트 라이브러리에서 지원하는 모든 런타임을 사용할 수 있습니다.

Cloud Shell 활성화

Cloud Console에서 Cloud Shell 활성화를 클릭합니다.

Cloud Shell을 처음 시작하는 경우에는 무엇이 있는지 설명하는 중간 화면이 표시됩니다. 중간 화면이 표시되면 계속을 클릭합니다.

Cloud Shell을 프로비저닝하고 연결하는 데 몇 분 정도만 걸립니다.

가상 머신에는 필요한 개발 도구가 모두 들어 있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab에서 대부분의 작업은 브라우저를 사용하여 수행할 수 있습니다.

Cloud Shell에 연결되면 인증이 완료되었고 프로젝트가 자신의 프로젝트 ID로 설정된 것을 확인할 수 있습니다.

Cloud Shell에서 다음 명령어를 실행하여 인증되었는지 확인합니다.

gcloud auth list

명령어 결과

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.

gcloud config list project

명령어 결과

[core]
project = <PROJECT_ID>

또는 다음 명령어로 설정할 수 있습니다.

gcloud config set project <PROJECT_ID>

명령어 결과

Updated property [core/project].

3. 인증된 Cloud 함수 만들기 및 테스트

이 Codelab은 Cloud Functions용 콘솔 빠른 시작과 동일한 안내를 따릅니다. 단, 한 가지 주목할 만한 예외는 함수에 인증이 필요하다는 것입니다.

인증을 요구한다는 것은 함수를 호출하는 주체에 Cloud Functions 호출자 (및 2세대의 Cloud Run 호출자) 역할이 있어야 함을 의미합니다. 그렇지 않으면 함수는 403 Forbidden 오류를 반환합니다. 이 Codelab에서는 원칙에 적절한 호출자 역할을 부여하는 방법을 보여줍니다.

인증된 함수 만들기

Cloud 콘솔을 사용하는 단계는 다음과 같습니다.

Cloud Functions 개요 페이지로 이동하여 함수 만들기를 클릭합니다.
환경 옵션에서 2세대를 선택합니다.
함수 이름을 my-authenticated-function으로 지정합니다.
인증 입력란에서 기본값을 인증 필요로 둡니다.

다음을 클릭합니다.
이 Codelab에서는 원하는 언어를 선택할 수 있습니다.
그런 다음 배포를 누릅니다.

함수를 배포하는 데 약 1분 정도 걸립니다.

간소화된 gcloud 명령어를 위한 로컬 환경 변수 설정

먼저 이 Codelab에서 사용되는 gcloud 명령어의 가독성을 개선하기 위해 몇 가지 환경 변수를 만듭니다.

함수의 리전을 지정하는 것이 좋습니다. 이 예에서는 us-central1를 사용합니다.

REGION="us-central1"

그런 다음 함수 URL을 환경 변수로 저장했다가 나중에 사용할 수 있습니다.

PROJECT_ID=$(gcloud config get-value project)
FUNCTION_URL="$(gcloud functions describe my-authenticated-function --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

익명 호출자로 호출을 시도하여 함수에 인증이 필요한지 확인

예상되는 403 오류가 발생하는지 확인하기 위해 인증 없이 함수를 호출합니다.

명령줄에서 다음 curl 명령어를 실행합니다.

curl $FUNCTION_URL

다음과 같은 결과가 표시됩니다.

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>403 Forbidden</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Forbidden</h1>
<h2>Your client does not have permission to get URL <code>/</code> from this server.</h2>
<h2></h2>
</body></html>

이제 인증을 제공하여 함수를 호출할 수 있는 3가지 시나리오를 살펴보겠습니다.

4. 시나리오 1: gcloud ID 토큰 사용

개발자는 함수를 로컬에서 개발하는 동안 테스트할 방법이 필요합니다. 이 섹션에서는 함수가 본인의 ID를 사용하여 올바르게 인증되었는지 확인하는 간단한 테스트를 수행합니다.

다음 명령어를 실행하여 gcloud로 인증되었는지 확인합니다.

gcloud auth list

활성 ID 옆에 별표가 표시됩니다. 예를 들면 다음과 같습니다.

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

올바른 ID를 사용하고 있음을 확인한 후에는 계정 이메일을 환경 변수에 저장합니다.

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")

자세한 내용은 문서에서 gcloud init 및 gcloud auth login 설정 부분을 참조하세요.

다음으로 함수를 호출하고 ID 토큰을 전달합니다.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token)"

이제 결과가 표시됩니다.

Hello World!

문제 해결

403 금지됨 오류가 발생하면 ID에 2세대 함수의 Cloud Functions 호출자 역할 또는 Cloud Run 호출자 역할이 있는지 확인하세요. IAM 콘솔을 사용하여 주 구성원에게 부여된 역할을 확인할 수 있습니다.

자체 ID 토큰을 사용하는 것이 개발 단계에서 함수를 빠르게 테스트할 수 있지만 인증된 함수의 호출자에게는 적절한 역할이 필요합니다. 그렇지 않으면 호출자는 403 Forbidden 오류를 수신합니다.

함수를 호출하는 역할이 있는 ID 및 서비스 계정의 수를 제한하여 최소 권한의 원칙을 따르는 것이 좋습니다.

새 서비스 계정을 만들고 필요한 역할을 부여합니다.

5. 시나리오 2: 서비스 계정 가장

이 시나리오에서는 로컬에서 개발하고 테스트할 때 함수를 호출하기 위해 서비스 계정을 가장 (권한을 가정)합니다. 서비스 계정을 가장하여 프로덕션에서와 동일한 사용자 인증 정보로 함수를 테스트할 수 있습니다.

이렇게 하면 역할을 확인할 뿐만 아니라 로컬 테스트 목적으로만 다른 ID에 Cloud 함수 호출자 역할을 부여하지 않아도 되므로 최소 권한의 원칙을 준수할 수 있습니다.

이 Codelab의 목적에 맞게 이 Codelab에서 만든 함수를 호출하는 역할만 있는 새 서비스 계정을 만듭니다.

새 서비스 계정 만들기

먼저 gcloud 명령어에 사용되는 서비스 계정을 나타내는 몇 가지 추가 환경 변수를 만듭니다.

SERVICE_ACCOUNT_NAME="invoke-functions-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

다음으로 서비스 계정을 만듭니다.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Function Authentication codelab"

서비스 계정에 Cloud 함수 호출자 역할을 부여합니다.

gcloud functions add-iam-policy-binding my-authenticated-function \
  --region=us-central1 --gen2 \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/cloudfunctions.invoker'

서비스 계정을 가장하여 함수 호출

이를 위해 ID 토큰을 가져와서 새로 만든 서비스 계정을 가장합니다.

가장에 필요한 역할 추가

서비스 계정을 가장하려면 서비스 계정에 대한 ID 토큰을 생성할 수 있는 서비스 계정 토큰 생성자 (roles/iam.serviceAccountTokenCreator) 역할이 사용자 계정에 있어야 합니다.

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_ADDRESS  \
  --member user:$ACCOUNT_EMAIL \
  --role='roles/iam.serviceAccountTokenCreator'

서비스 계정의 ID 토큰 사용

이제 서비스 계정의 ID 토큰을 전달하여 함수를 호출할 수 있습니다.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token --impersonate-service-account $SERVICE_ACCOUNT_ADDRESS)"

다음과 같은 내용이 표시됩니다.

WARNING: This command is using service account impersonation. All API calls will be executed as [invoke-functions-codelab@<project-id>.iam.gserviceaccount.com].
Hello World!

6. 시나리오 3: Google 클라이언트 라이브러리 사용

Codelab의 이 마지막 부분에서는 소규모 서비스를 로컬에서 실행하여 서비스 계정의 ID 토큰을 생성한 다음 Google 인증 클라이언트 라이브러리 및 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 프로그래매틱 방식으로 함수를 호출합니다. Google 클라이언트 라이브러리에 대한 자세한 내용은 문서의 클라이언트 라이브러리 설명 섹션을 참조하세요.

다른 Google Cloud 리소스 (예: Cloud Storage, Vision API 등)와 상호작용하면서 로컬에서 (예: 노트북, Cloud Shell 등) 함수를 작성하고 테스트하려는 경우 ADC를 사용하는 것이 특히 중요합니다. 이 예시에서는 서비스에서 인증이 필요한 다른 함수를 호출하는 방법을 보여줍니다. ADC 및 로컬 개발에 대한 자세한 내용은 블로그 게시물 Cloud Functions를 로컬에서 개발하고 테스트하는 방법 | Google Cloud 블로그

gcloud 명령어를 실행하여 서비스 계정 가장하기

ADC는 애플리케이션 환경을 기반으로 사용자 인증 정보를 자동으로 찾고 해당 사용자 인증 정보를 사용하여 Google Cloud API에 인증합니다. –impersonate-service-account 플래그를 사용하면 Google Cloud API에 대한 인증에 해당 ID를 사용하여 서비스 계정을 가장할 수 있습니다.

다음 명령어를 실행하면 서비스 계정을 가장할 수 있습니다.

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

이제 ID가 아닌 해당 서비스 계정으로 gcloud 명령어를 실행합니다.

인증된 함수를 호출하는 서비스 만들기 및 실행

각 런타임에는 설치할 수 있는 자체 Google 인증 클라이언트 라이브러리가 있습니다. 이 Codelab은 로컬에서 Node.js 앱을 만들고 실행하는 방법을 안내합니다.

Node.js의 단계는 다음과 같습니다.

새 Node.js 앱 만들기

npm init

Google 인증 클라이언트 라이브러리 설치

npm install google-auth-library

index.js 파일 만들기
다음 단계에서 코드에 추가할 Cloud 함수의 URL을 가져옵니다.

echo $FUNCTION_URL

index.js에 다음 코드를 추가합니다. targetAudience 변수를 Cloud 함수 URL로 변경해야 합니다.

index.js

// Cloud Functions uses your function's url as the `targetAudience` value

const targetAudience = '<YOUR-CLOUD-FUNCTION-URL>';

// For Cloud Functions, endpoint(`url`) and `targetAudience` should be equal

const url = targetAudience;

const { GoogleAuth } = require('google-auth-library');
const auth = new GoogleAuth();

async function request() {
    console.info(`request ${url} with target audience ${targetAudience}`);

    // this call retrieves the ID token for the impersonated service account
    const client = await auth.getIdTokenClient(targetAudience);

    const res = await client.request({ url });
    console.info(res.data);
}

request().catch(err => {
    console.error(err.message);
    process.exitCode = 1;
});

앱 실행

node index.js

결과로 반환된 'Hello World!'가

문제 해결

Permission ‘iam.serviceAccounts.getOpenIdToken' 오류가 표시되는 경우 거부된 경우 (또는 리소스가 없을 수 있음). 서비스 계정 토큰 생성자 역할이 적용될 때까지 몇 분 정도 기다려 주세요.

'이 환경에서 ID 토큰을 가져올 수 없음, GCE를 사용하거나 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 사용자 인증 정보 JSON 파일로 설정할 수 없음'이라는 오류 메시지가 표시되면 명령어 실행을 잊은 것일 수 있습니다.

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

7. 축하합니다.

축하합니다. Codelab을 완료했습니다.

Cloud Functions를 보호하는 방법에 관한 문서를 검토하는 것이 좋습니다.

Cloud Functions를 사용한 로컬 개발에 관한 이 블로그 게시물도 로컬 개발자 환경에서 Cloud 함수를 개발하고 테스트하는 방법을 알아볼 수 있습니다.

학습한 내용

Cloud 함수에서 인증을 구성하고 인증이 올바르게 구성되었는지 확인하는 방법
gcloud ID의 토큰을 제공하여 로컬 개발 환경에서 인증된 함수 호출
서비스 계정을 만들고 함수를 호출하는 적절한 역할을 부여하는 방법
함수 호출에 적절한 역할이 있는 로컬 개발 환경에서 서비스를 가장하는 방법

8. 삭제

실수로 인한 청구를 방지하려면(예: 이 Cloud 함수가 무료 등급의 월별 Cloud 함수 호출 할당보다 실수로 더 많이 호출되는 경우) Cloud 함수를 삭제하거나 2단계에서 만든 프로젝트를 삭제하면 됩니다.

서비스 계정 가장을 중단하려면 ID를 사용하여 다시 로그인할 수 있습니다.

gcloud auth application-default login

Cloud 함수를 삭제하려면 Cloud 함수 Cloud 콘솔(https://console.cloud.google.com/functions/)으로 이동합니다. 2단계에서 만든 프로젝트가 현재 선택된 프로젝트인지 확인합니다.

앞서 배포한 my-authenticated-function을 선택합니다. 삭제를 누릅니다.

전체 프로젝트를 삭제하려면 https://console.cloud.google.com/cloud-resource-manager로 이동하여 2단계에서 만든 프로젝트를 선택한 후 삭제를 선택하면 됩니다. 프로젝트를 삭제하면 Cloud SDK에서 프로젝트를 변경해야 합니다. gcloud projects list를 실행하면 사용 가능한 모든 프로젝트의 목록을 볼 수 있습니다.