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

클라이언트 라이브러리 사용을 위한 인증

이 페이지에서는 클라이언트 라이브러리와 애플리케이션 기본 사용자 인증 정보를 사용하여 Google API에 액세스하는 방법을 설명합니다.

클라이언트 라이브러리를 사용하면 지원되는 언어로 Google Cloud API에 쉽게 액세스할 수 있습니다. 서버에 원시 요청을 수행해서 Google Cloud API를 직접 사용할 수 있지만 클라이언트 라이브러리는 작성해야 하는 코드 양을 크게 줄여 주는 간소화 기능을 제공합니다. 이는 클라이언트 라이브러리가 애플리케이션 기본 사용자 인증 정보 (ADC)를 지원하기 때문에 특히 더 그렇습니다.

API 키를 사용하려는 경우 ADC를 사용하지 않습니다. 자세한 내용은 클라이언트 라이브러리에서 API 키 사용을 참조하세요.

클라이언트 라이브러리에 애플리케이션 기본 사용자 인증 정보 사용

애플리케이션 기본 사용자 인증 정보를 사용하여 애플리케이션을 인증하려면 먼저 애플리케이션이 실행되는 환경에 대한 ADC를 설정해야 합니다. 클라이언트 라이브러리를 사용하여 클라이언트를 만드는 경우 클라이언트 라이브러리는 코드가 사용하는 API에 인증하기 위해 ADC에 제공된 사용자 인증 정보를 자동으로 확인하고 사용합니다. 애플리케이션이 토큰을 명시적으로 인증하거나 관리할 필요가 없습니다. 이러한 요구사항은 인증 라이브러리에 의해 자동으로 관리됩니다.

로컬 개발 환경의 경우 gcloud CLI를 사용하여 사용자 인증 정보 또는 서비스 계정 가장으로 ADC를 설정할 수 있습니다. 프로덕션 환경의 경우 서비스 계정을 연결하여 ADC를 설정합니다.

클라이언트 만들기 예시

다음 코드 샘플은 Cloud Storage 서비스의 클라이언트를 만듭니다. 코드에는 여러 클라이언트가 필요할 수 있습니다. 이 샘플에서는 클라이언트를 만들고 명시적으로 인증하기 위한 코드 없이 사용하는 방법을 보여주기 위한 것입니다.

다음 샘플을 실행하려면 먼저 다음 단계를 완료해야 합니다.

환경에 ADC를 설정합니다.
Cloud Storage 클라이언트 라이브러리를 설치합니다.

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// authenticateImplicitWithAdc uses Application Default Credentials
// to automatically find credentials and authenticate.
func authenticateImplicitWithAdc(w io.Writer, projectId string) error {
	// projectId := "your_project_id"

	ctx := context.Background()

	// NOTE: Replace the client created below with the client required for your application.
	// Note that the credentials are not specified when constructing the client.
	// The client library finds your credentials using ADC.
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	it := client.Buckets(ctx, projectId)
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Bucket: %v\n", bucketAttrs.Name)
	}

	fmt.Fprintf(w, "Listed all storage buckets.\n")

	return nil
}

자바


import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;

public class AuthenticateImplicitWithAdc {

  public static void main(String[] args) throws IOException {
    // TODO(Developer):
    //  1. Before running this sample,
    //  set up Application Default Credentials as described in
    //  https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable below.
    //  3. Make sure you have the necessary permission to list storage buckets
    //  "storage.buckets.list"
    String projectId = "your-google-cloud-project-id";
    authenticateImplicitWithAdc(projectId);
  }

  // When interacting with Google Cloud Client libraries, the library can auto-detect the
  // credentials to use.
  public static void authenticateImplicitWithAdc(String project) throws IOException {

    // *NOTE*: Replace the client created below with the client required for your application.
    // Note that the credentials are not specified when constructing the client.
    // Hence, the client library will look for credentials using ADC.
    //
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    Storage storage = StorageOptions.newBuilder().setProjectId(project).build().getService();

    System.out.println("Buckets:");
    Page<Bucket> buckets = storage.list();
    for (Bucket bucket : buckets.iterateAll()) {
      System.out.println(bucket.toString());
    }
    System.out.println("Listed all storage buckets.");
  }
}

Node.js

/**
 * TODO(developer):
 *  1. Uncomment and replace these variables before running the sample.
 *  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
 *  3. Make sure you have the necessary permission to list storage buckets "storage.buckets.list"
 *    (https://cloud.google.com/storage/docs/access-control/iam-permissions#bucket_permissions)
 */
// const projectId = 'YOUR_PROJECT_ID';

const {Storage} = require('@google-cloud/storage');

async function authenticateImplicitWithAdc() {
  // This snippet demonstrates how to list buckets.
  // NOTE: Replace the client created below with the client required for your application.
  // Note that the credentials are not specified when constructing the client.
  // The client library finds your credentials using ADC.
  const storage = new Storage({
    projectId,
  });
  const [buckets] = await storage.getBuckets();
  console.log('Buckets:');

  for (const bucket of buckets) {
    console.log(`- ${bucket.name}`);
  }

  console.log('Listed all storage buckets.');
}

authenticateImplicitWithAdc();

PHP

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

/**
 * Authenticate to a cloud client library using a service account implicitly.
 *
 * @param string $projectId The Google project ID.
 */
function auth_cloud_implicit($projectId)
{
    $config = [
        'projectId' => $projectId,
    ];

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python


from google.cloud import storage


def authenticate_implicit_with_adc(project_id="your-google-cloud-project-id"):
    """
    When interacting with Google Cloud Client libraries, the library can auto-detect the
    credentials to use.

    // TODO(Developer):
    //  1. Before running this sample,
    //  set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable.
    //  3. Make sure that the user account or service account that you are using
    //  has the required permissions. For this sample, you must have "storage.buckets.list".
    Args:
        project_id: The project id of your Google Cloud project.
    """

    # This snippet demonstrates how to list buckets.
    # *NOTE*: Replace the client created below with the client required for your application.
    # Note that the credentials are not specified when constructing the client.
    # Hence, the client library will look for credentials using ADC.
    storage_client = storage.Client(project=project_id)
    buckets = storage_client.list_buckets()
    print("Buckets:")
    for bucket in buckets:
        print(bucket.name)
    print("Listed all storage buckets.")

Ruby

def authenticate_implicit_with_adc project_id:
  # The ID of your Google Cloud project
  # project_id = "your-google-cloud-project-id"

  ###
  # When interacting with Google Cloud Client libraries, the library can auto-detect the
  # credentials to use.
  # TODO(Developer):
  #   1. Before running this sample,
  #      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
  #   2. Replace the project variable.
  #   3. Make sure that the user account or service account that you are using
  #      has the required permissions. For this sample, you must have "storage.buckets.list".
  ###

  require "google/cloud/storage"

  # This sample demonstrates how to list buckets.
  # *NOTE*: Replace the client created below with the client required for your application.
  # Note that the credentials are not specified when constructing the client.
  # Hence, the client library will look for credentials using ADC.
  storage = Google::Cloud::Storage.new project_id: project_id
  buckets = storage.buckets
  puts "Buckets: "
  buckets.each do |bucket|
    puts bucket.name
  end
  puts "Plaintext: Listed all storage buckets."
end

외부 소스의 사용자 인증 정보 구성을 사용할 때의 보안 요구사항

일반적으로 gcloud CLI 명령어를 사용하거나 Google Cloud 콘솔을 사용하여 사용자 인증 정보 구성을 생성합니다. 예를 들어 gcloud CLI를 사용하여 로컬 ADC 파일 또는 로그인 구성 파일을 생성할 수 있습니다. 마찬가지로 Google Cloud 콘솔을 사용하여 서비스 계정 키를 만들고 다운로드할 수 있습니다.

그러나 일부 사용 사례에서는 외부 항목에서 사용자 인증 정보 구성을 제공합니다. 이러한 사용자 인증 정보 구성은 Google API에 인증하는 데 사용됩니다.

일부 유형의 사용자 인증 정보 구성에는 인증 라이브러리가 토큰을 획득하는 데 사용하는 엔드포인트와 파일 경로가 포함됩니다. 외부 소스의 사용자 인증 정보 구성을 수락하는 경우 구성을 사용하기 전에 구성을 검증해야 합니다. 구성을 검증하지 않으면 악의적인 행위자가 사용자 인증 정보를 사용하여 시스템과 데이터를 손상시킬 수 있습니다.

외부 소스의 사용자 인증 정보 구성 유효성 검사

외부 사용자 인증 정보의 유효성을 검사하는 방법은 애플리케이션에서 허용하는 사용자 인증 정보 유형에 따라 다릅니다.

서비스 계정 키 유효성 검사

애플리케이션이 서비스 계정 키만 허용하는 경우 다음 예와 같이 서비스 계정 키 전용 사용자 인증 정보 로더를 사용하세요. 유형별 사용자 인증 정보 로더는 서비스 계정 키에 있는 필드만 파싱하며, 이 필드는 취약점을 노출하지 않습니다.

C#

var saCredential = ServiceAccountCredential.FromServiceAccountData(stream);

C++

auto cred = google::cloud::MakeServiceAccountCredentials(json)

자바

ServiceAccountCredentials credentials =
      ServiceAccountCredentials.fromJson(json, new HttpTransportFactory());

Node.js

const keys = JSON.parse(json_input)
const authClient = JWT.fromJSON(keys);

PHP

cred = new Google\Auth\Credentials\ServiceAccountCredentials($scope, $jsonKey);

Python

cred = service_account.Credentials.from_service_account_info(json_data)

Ruby

creds = Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: json_stream)

유형별 사용자 인증 정보 로더를 사용할 수 없는 경우 type 필드의 값이 service_account인지 확인하여 사용자 인증 정보의 유효성을 검사합니다. type 필드의 값이 다른 값인 경우 서비스 계정 키를 사용하지 마세요.

기타 사용자 인증 정보 구성 검증

애플리케이션이 서비스 계정 키 외에 모든 유형의 사용자 인증 정보를 허용하는 경우 추가 인증을 실행해야 합니다. 다른 유형의 사용자 인증 정보 구성의 예로는 ADC 사용자 인증 정보 파일, 워크로드 아이덴티티 제휴 사용자 인증 정보 파일 또는 직원 ID 제휴 로그인 구성 파일이 있습니다.

다음 표에는 사용자 인증 정보에 있는 경우 검증해야 하는 필드가 나와 있습니다. 일부 사용자 인증 정보 구성에는 이러한 필드가 일부만 포함되어 있습니다.

필드	목적	예상 값
`service_account_impersonation_url`	인증 라이브러리는 이 필드를 사용하여 엔드포인트에 액세스하여 명의 도용된 서비스 계정의 액세스 토큰을 생성합니다.	`https://iamcredentials.googleapis.com.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken`
`token_url`	인증 라이브러리는 외부 토큰을 이 엔드포인트로 전송하여 제휴 액세스 토큰으로 교환합니다.	`https://sts.googleapis.com.com/v1/token`
`credential_source.file`	인증 라이브러리는 이 필드에 지정된 위치의 파일에서 외부 토큰을 읽고 `token_url` 엔드포인트로 전송합니다.	외부 토큰이 포함된 파일의 경로입니다. 이 경로를 알아야 합니다.
`credential_source.url`	외부 토큰을 반환하는 엔드포인트입니다. 인증 라이브러리는 이 URL에 요청을 보내고 응답을 `token_url` 엔드포인트로 전송합니다.	다음 항목 중 하나 클라우드 제공업체에서 제공하는 잘 알려진 엔드포인트입니다. 토큰을 제공하도록 명시적으로 설정한 엔드포인트입니다.
`credential_source.executable.command`	`GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES` 환경 변수가 `1`로 설정되면 인증 라이브러리가 이 명령어 또는 실행 파일을 실행합니다.	외부 토큰을 반환하는 실행 파일 또는 명령어입니다. 이 명령을 인식하고 안전한지 확인해야 합니다.
`credential_source.aws.url`	인증 라이브러리는 이 URL에 요청을 발행하여 AWS 보안 토큰을 가져옵니다.	다음 정확한 값 중 하나입니다. `http://169.254.169.254/latest/meta-data/iam/security-credentials` `http://[fd00:ec2::254]/latest/meta-data/iam/security-credentials`
`credential_source.aws.region_url`	인증 라이브러리는 이 URL에 요청을 보내 활성 AWS 리전을 가져옵니다.	다음 정확한 값 중 하나입니다. `http://169.254.169.254/latest/meta-data/placement/availability-zone` `http://[fd00:ec2::254]/latest/meta-data/placement/availability-zone`
`credential_source.aws.imdsv2_session_token_url`	인증 라이브러리는 이 URL에 요청을 보내 AWS 세션 토큰을 가져옵니다.	다음 정확한 값 중 하나입니다. `http://169.254.169.254/latest/api/token` `http://[fd00:ec2::254]/latest/api/token`

다음 단계

애플리케이션 기본 사용자 인증 정보 자세히 알아보기
인증 방법의 개요 확인하기