Google 인증 라이브러리 시작하기

Google Auth Library는 Java용 오픈소스 인증 클라이언트 라이브러리입니다. 이 문서에서는 이 라이브러리를 사용하여 Java 애플리케이션을 인증하여 Google Cloud 서비스에 액세스하는 방법을 설명합니다.

이 가이드를 따르면 다음 작업을 수행하는 방법을 알 수 있습니다.

• Maven, Gradle 또는 Simple Build Tool (SBT)을 사용하여 프로젝트에 필요한 인증 라이브러리 종속 항목을 추가합니다.
• 애플리케이션 기본 사용자 인증 정보 (ADC)를 중심으로 다양한 방법을 사용하여 인증합니다.
• 워크로드 아이덴티티 제휴, 직원 ID 제휴, 서비스 계정 가장 등 고급 인증 시나리오를 구성합니다.
• 범위가 축소된 토큰을 생성하고 사용하여 권한을 제한합니다.
• 사용자 인증 정보를 Google HTTP 클라이언트 라이브러리와 통합합니다.

이 문서는 Java 개발자를 대상으로 합니다. 전체 API 세부정보는 Google Auth Library API 문서를 참고하세요.

Java용 Google 인증 라이브러리는 다음 네 가지 아티팩트로 구성됩니다.

• google-auth-library-credentials에는 Google 사용자 인증 정보의 기본 클래스와 인터페이스가 포함되어 있습니다.
• google-auth-library-appengine에는 App Engine 사용자 인증 정보가 포함되어 있으며 App Engine SDK에 종속됩니다.
• google-auth-library-oauth2-http에는 애플리케이션 기본 사용자 인증 정보를 가져오는 기능을 비롯한 다양한 사용자 인증 정보와 유틸리티 메서드가 포함되어 있습니다. 또한 범위가 축소된 토큰을 생성하는 서버 측 접근 방식을 제공합니다.
• google-auth-library-cab-token-generator은 권한이 축소된 토큰을 생성하는 클라이언트 측 접근 방식을 제공합니다.

사용자 인증 정보 구성 검사

외부 소스의 사용자 인증 정보 구성(예: JSON, 파일 경로 또는 스트림)을 사용하는 경우 이를 검증해야 합니다.Google Cloud 에 대한 인증을 위해 Google API 또는 클라이언트 라이브러리에 검증되지 않은 사용자 인증 정보를 제공하면 시스템과 데이터의 보안이 손상될 수 있습니다.

자세한 내용은 외부 소스 사용자 인증 정보를 참고하세요. 기본 사용자 인증 정보

인증 라이브러리 가져오기

인증 라이브러리를 가져오려면 com.google.cloud:libraries-bom을 사용하거나 Maven 또는 Gradle과 함께 Google 인증 라이브러리 자재 명세서를 사용하세요.

Java SDK 라이브러리-bom

인증 라이브러리를 사용하여 Java SDK(예: google-cloud-datastore)의 클라이언트 라이브러리를 인증하려면 해당 클라이언트 라이브러리와 호환되는 인증 라이브러리 버전을 가져오는 libraries-bom를 사용하세요.

예를 들어 pom.xml을 사용하여 Maven으로 인증 라이브러리를 가져오려면 다음을 실행합니다.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

libraries-bom 또는 기타 클라이언트 라이브러리를 사용하지 않는 경우 Google 인증 라이브러리 BOM을 사용하여 인증 모듈을 직접 가져옵니다.

Google 인증 라이브러리 자재 명세서

Google 인증 라이브러리 BOM을 사용하여 인증 모듈과 관련 전이 종속 항목이 호환되는지 확인할 수 있습니다.

Maven

pom.xml 파일에 다음을 추가합니다.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies> 섹션에서 필요한 인증 모듈을 지정할 수 있습니다. 예를 들어 google-auth-library-oauth2-http 모듈을 포함하려면 다음 <dependency> 항목을 추가합니다.

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

애플리케이션 요구사항에 따라 예시의 google-auth-library-oauth2-http을 google-auth-library-credentials 또는 google-auth-library-appengine로 바꿉니다.

Gradle

Maven과 마찬가지로 Gradle 사용자는 google-auth-library-bom를 사용하여 종속 항목 버전을 관리하고 다양한 google-auth-library 모듈 간의 호환성을 보장할 수 있습니다.

Gradle에서 BOM을 사용하려면 BOM을 platform 종속 항목으로 추가하세요. 그런 다음 필요한 google-auth-library 모듈을 추가합니다. BOM은 사용하는 모든 모듈의 버전이 호환되도록 합니다. 예를 들어 build.gradle 파일에 다음을 추가합니다.

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

Maven 및 Gradle과 달리 SBT (Scala Build Tool)는 Maven BOM (Bills of Materials)을 지원하지 않습니다. 따라서 Scala를 사용하는 경우 google-auth-library-bom를 가져와 호환되는 버전의 인증 라이브러리 모듈과 전이 종속 항목을 자동으로 처리할 수 없습니다.

대신 필요한 각 하위 모듈을 build.sbt 파일에 직접 추가해야 합니다. 사용 중인 모든 google-auth-library 모듈의 버전을 명시적으로 지정하고 정렬하는 것이 중요합니다. 버전을 일관되게 유지하지 않으면 전이 종속 항목 간에 버전 충돌이 발생하여 애플리케이션에서 예기치 않은 동작이나 런타임 오류가 발생할 수 있습니다.

SBT를 사용하는 경우 종속 항목에 다음을 추가합니다.

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

GoogleCredential에서 GoogleCredentials로 마이그레이션

google-api-java-client의 GoogleCredential이 지원 중단되었으며 GoogleCredentials으로 대체하는 것이 좋습니다.

애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 GoogleCredentials를 인스턴스화합니다. 다음은 권장되는 방법입니다.

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

GoogleCredentials를 사용하는 방법은 클라이언트 라이브러리에 따라 다릅니다.

• Cloud 클라이언트 라이브러리: 이 라이브러리는 애플리케이션 기본 사용자 인증 정보 (ADC)를 자동으로 사용하므로 코드에서 사용자 인증 정보를 제공할 필요가 없습니다.

• Google API 클라이언트 라이브러리: GoogleCredentials를 인스턴스화하고 클라이언트에 전달해야 합니다. 예를 보려면 Google API Java 클라이언트 가이드를 참고하세요.

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

Google 인증 라이브러리는 Java용 애플리케이션 기본 사용자 인증 정보 (ADC)를 구현합니다. ADC는 Google API를 호출할 승인 사용자 인증 정보를 가져오는 방법을 제공합니다.

애플리케이션에 사용자와 관계없이 일관된 ID와 승인 수준이 필요한 경우 ADC를 사용합니다. 특히 Google Cloud에서 애플리케이션을 빌드할 때는 ADC를 사용하여 Cloud API 호출을 승인하는 것이 좋습니다.

ADC는 워크로드 아이덴티티 제휴도 지원하므로 애플리케이션이 Amazon Web Services (AWS), Microsoft Azure 또는 OpenID Connect (OIDC)를 지원하는 ID 공급업체와 같은 외부 플랫폼의 Google Cloud 리소스에 액세스할 수 있습니다.Google Cloud 이외의 환경에서는 워크로드 아이덴티티 제휴를 사용하는 것이 좋습니다. 서비스 계정 비공개 키를 로컬로 다운로드, 관리, 저장할 필요가 없기 때문입니다.

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

애플리케이션 기본 사용자 인증 정보를 가져오려면 GoogleCredentials.getApplicationDefault() 또는 GoogleCredentials.getApplicationDefault(HttpTransportFactory)를 사용하세요. 이러한 메서드는 전체 애플리케이션을 식별하고 승인하는 애플리케이션 기본 사용자 인증 정보를 반환합니다.

애플리케이션 기본 사용자 인증 정보를 찾기 위해 다음이 이 순서대로 검색됩니다.

1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수로 지정된 사용자 인증 정보 파일
2. Google Cloud SDK gcloud auth application-default login 명령어로 제공되는 사용자 인증 정보
3. Google App Engine 기본 사용자 인증 정보입니다.
4. Google Cloud 셸 내장 사용자 인증 정보
5. Google Compute Engine 내장 사용자 인증 정보입니다.
   • NO_GCE_CHECK=true 환경 변수를 설정하여 이 검사를 건너뜁니다.
   • 환경 변수 GCE_METADATA_HOST=<hostname>를 설정하여 메타데이터 서버 주소를 맞춤설정합니다.

명시적 사용자 인증 정보 로드

서비스 계정 JSON 키에서 사용자 인증 정보를 가져오려면 다음 예시 코드에 표시된 대로 GoogleCredentials.fromStream(InputStream) 또는 GoogleCredentials.fromStream(InputStream, HttpTransportFactory)를 사용하세요.

액세스 토큰을 사용하려면 먼저 사용자 인증 정보를 새로고침해야 합니다.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

가장된 사용자 인증 정보

ImpersonatedCredentials를 사용하여 사용자 인증 정보 (주 구성원)가 서비스 계정 (타겟)을 가장하도록 허용합니다. 이를 통해 주 구성원은 대상의 비공개 키 없이도 대상으로 리소스에 액세스할 수 있습니다.

ImpersonatedCredentials를 사용하려면 다음 요구사항을 충족해야 합니다.

• 주체의 프로젝트에 IAMCredentials API가 사용 설정되어 있어야 합니다.
• 주 구성원에게 타겟 서비스 계정에 대한 Service Account Token Creator (Identity and Access Management) 역할이 있어야 합니다.

다음 코드 샘플은 ImpersonatedCredentials을 만듭니다. 주체의 사용자 인증 정보는 애플리케이션 기본 사용자 인증 정보 (ADC)에서 가져옵니다. 결과 ImpersonatedCredentials는 타겟 서비스 계정으로 Google Cloud Storage에 액세스하는 데 사용됩니다.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "[e-mail]")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

워크로드 아이덴티티 제휴

워크로드 아이덴티티 제휴를 사용하면 애플리케이션에서 Amazon Web Services (AWS), Microsoft Azure 또는 OpenID Connect (OIDC)를 지원하는 ID 공급업체의 Google Cloud리소스에 액세스할 수 있습니다.

일반적으로 Google Cloud 외부에서 실행되는 애플리케이션은 서비스 계정 키를 사용하여 Google Cloud 리소스에 액세스합니다. ID 제휴를 사용하면 워크로드가 서비스 계정을 가장할 수 있습니다. 이를 통해 외부 워크로드가 Google Cloud 리소스에 직접 액세스할 수 있으므로 서비스 계정 키와 관련된 유지보수 및 보안 부담이 사라집니다.

AWS에서 리소스 액세스

Amazon Web Services (AWS)에서 Google Cloud 리소스에 액세스하려면 먼저 워크로드 아이덴티티 제휴를 구성해야 합니다. 설정 프로세스는 AWS에서 리소스 액세스에 자세히 설명되어 있습니다.

이 프로세스의 일환으로 사용자 인증 정보 구성 파일을 생성합니다. 이 파일에는 라이브러리가 외부 주체 토큰을 가져오고 서비스 계정 액세스 토큰으로 교환하는 방법을 안내하는 민감하지 않은 메타데이터가 포함되어 있습니다. Google Cloud CLI를 사용하여 파일을 생성할 수 있습니다.

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• AWS_PROVIDER_ID: AWS 공급자 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.

이 예시에서는 지정된 출력 파일에 구성 파일을 생성합니다.

AWS IMDSv2를 사용하는 경우 gcloud iam workload-identity-pools create-cred-config 명령어에 플래그 --enable-imdsv2를 추가해야 합니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

이제 인증 라이브러리를 사용하여 AWS에서Google Cloud 리소스를 호출할 수 있습니다.

Microsoft Azure에서 리소스 액세스

Microsoft Azure에서 Google Cloud 리소스에 액세스하려면 먼저 워크로드 아이덴티티 제휴를 구성해야 합니다. 설정 프로세스는 Azure에서 리소스 액세스에 자세히 설명되어 있습니다.

이 프로세스의 일환으로 사용자 인증 정보 구성 파일을 생성합니다. 이 파일에는 라이브러리가 외부 주체 토큰을 가져오고 서비스 계정 액세스 토큰으로 교환하는 방법을 안내하는 민감하지 않은 메타데이터가 포함되어 있습니다. Google Cloud CLI를 사용하여 파일을 생성할 수 있습니다.

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• AZURE_PROVIDER_ID: Azure 제공업체 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.

이 명령어는 지정된 출력 파일에 구성 파일을 생성합니다.

이제 인증 라이브러리를 사용하여 Azure에서 Google Cloud리소스를 호출할 수 있습니다.

OIDC ID 공급업체에서 리소스 액세스

OpenID Connect (OIDC)를 지원하는 ID 공급업체에서 Google Cloud 리소스에 액세스하려면 먼저 OIDC ID 공급업체에서 워크로드 아이덴티티 제휴 구성에 설명된 대로 워크로드 아이덴티티 제휴를 구성해야 합니다.

이 프로세스의 일환으로 Google Cloud CLI를 사용하여 사용자 인증 정보 구성 파일을 생성합니다. 이 파일에는 라이브러리가 외부 주체 토큰을 가져와 서비스 계정 액세스 토큰으로 교환하는 방법을 안내하는 민감하지 않은 메타데이터가 포함되어 있습니다.

OIDC 제공업체의 경우 인증 라이브러리는 로컬 파일(파일 소스 사용자 인증 정보), 로컬 서버(URL 소스 사용자 인증 정보) 또는 X.509 인증서와 비공개 키 조합 (X.509 인증서 소스 사용자 인증 정보)에서 OIDC 토큰을 가져올 수 있습니다.

파일 소스 사용자 인증 정보

파일 소스 사용자 인증 정보의 경우 백그라운드 프로세스가 만료되기 전에 새 OIDC 토큰으로 파일 위치를 지속적으로 새로고침해야 합니다. 수명이 1시간인 토큰의 경우 매시간 파일에서 토큰을 업데이트해야 합니다. 토큰을 일반 텍스트 또는 JSON 형식으로 직접 저장할 수 있습니다.

파일 소스 OIDC 구성을 생성하려면 다음 명령어를 실행합니다.

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• OIDC_PROVIDER_ID: OIDC 공급업체 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
• PATH_TO_OIDC_ID_TOKEN: OIDC 토큰을 검색하는 데 사용되는 경로입니다.

이 명령어는 지정된 출력 파일에 구성 파일을 생성합니다.

URL 소스 사용자 인증 정보

URL에서 가져온 사용자 인증 정보의 경우 로컬 서버가 일반 텍스트 또는 JSON 형식으로 OIDC 토큰을 제공하는 GET 엔드포인트를 호스팅해야 합니다. 엔드포인트에서 필요한 경우 토큰 요청에 전송할 추가 HTTP 헤더를 지정할 수 있습니다.

URL 소스 OIDC 워크로드 아이덴티티 구성을 생성하려면 다음 명령어를 실행합니다.

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• OIDC_PROVIDER_ID: OIDC 공급업체 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
• URL_TO_GET_OIDC_TOKEN: OIDC 토큰을 검색하기 위해 호출할 로컬 서버 엔드포인트의 URL입니다.
• HEADER_KEY 및 HEADER_VALUE: URL_TO_GET_OIDC_TOKEN에 대한 GET 요청에 전달할 추가 헤더 키-값 쌍입니다(예: Metadata-Flavor=Google).

이제 인증 라이브러리를 사용하여 OIDC 제공업체에서Google Cloud 리소스를 호출할 수 있습니다.

X.509 인증서 소스 사용자 인증 정보를 사용하여 리소스에 액세스

X.509 인증서 소스 사용자 인증 정보의 경우 인증 라이브러리는 X.509 인증서와 비공개 키를 사용하여 애플리케이션의 ID를 증명합니다. X.509 인증서에는 만료일이 포함되어 있으며 액세스 권한을 유지하려면 만료되기 전에 갱신해야 합니다.

자세한 내용은 공식 문서를 참고하세요.

X.509 제휴용 구성 파일 생성

X.509 인증서 소스 사용자 인증 정보를 구성하려면 기본 사용자 인증 정보 구성 파일과 인증서 구성 파일이라는 두 개의 별도 파일을 생성합니다.

• 기본 사용자 인증 정보 구성 파일에는 인증에 필요한 메타데이터가 포함되어 있습니다. 이 파일은 인증서 구성 파일도 참조합니다.
• 인증서 구성 파일은 X.509 인증서, 비공개 키, 신뢰 체인의 파일 경로를 지정합니다.

gcloud iam workload-identity-pools create-cred-config 명령어를 사용하여 두 가지를 모두 만들 수 있습니다.

gcloud에서 인증서 구성 파일을 만드는 위치는 --credential-cert-configuration-output-file 플래그를 사용하는지 여부에 따라 달라집니다.

기본 동작 (권장)

--credential-cert-configuration-output-file 플래그를 생략하면 gcloud에서 인증 라이브러리가 자동으로 검색할 수 있는 기본 위치에 인증서 구성 파일을 만듭니다. 이 접근 방식은 대부분의 사용 사례에 적합합니다. 기본 사용자 인증 정보 구성 파일의 이름은 config.json이고 기본 인증서 구성 파일의 이름은 certificate_config.json입니다.

예를 들어 기본 동작을 사용하여 구성 파일을 만들려면 다음 명령어를 실행합니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• PROVIDER_ID: 공급업체 ID
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
• PATH_TO_CERTIFICATE: 리프 X.509 인증서가 있는 경로입니다.
• PATH_TO_PRIVATE_KEY: 리프 인증서의 해당 비공개 키가 있는 경로입니다.
• PATH_TO_TRUST_CHAIN: X.509 인증서 신뢰 체인 파일의 경로입니다. 이 파일은 리프 인증서와 워크로드 아이덴티티 제휴 풀에 구성된 트러스트 저장소 간의 신뢰 체인을 완료하는 데 필요한 중간 인증서가 포함된 PEM 형식 파일이어야 합니다. 리프 인증서는 이 파일에서 선택사항입니다.

이 명령어는 다음 결과를 생성합니다.

• /path/to/config.json: 지정한 경로에 생성됩니다. 이 파일에는 클라이언트가 기본 경로에서 인증서 구성을 찾도록 지시하는 "use_default_certificate_config": true가 포함됩니다.
• certificate_config.json: 기본 Google Cloud CLI 구성 경로에 생성됩니다. 일반적으로 Linux 및 macOS에서는 ~/.config/gcloud/certificate_config.json, Windows에서는 %APPDATA%\gcloud\certificate_config.json입니다.

맞춤 위치 동작

기본 위치가 아닌 위치에 인증서 구성 파일을 저장해야 하는 경우 --credential-cert-configuration-output-file 플래그를 사용하세요.

명령어 예 (맞춤 위치):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

이 명령어의 결과는 다음과 같습니다.

• /path/to/config.json: 지정한 경로에 생성됩니다. 이 파일에는 맞춤 경로를 가리키는 "certificate_config_location" 필드가 포함됩니다.
• cert_config.json: 플래그에 지정된 대로 /custom/path/cert_config.json에서 생성됩니다.

이제 인증 라이브러리를 사용하여 X.509 인증서 소스 사용자 인증 정보로Google Cloud resources를 호출할 수 있습니다.

OIDC 및 SAML과 함께 실행 파일 소스 사용자 인증 정보 사용

실행 파일 소스 사용자 인증 정보의 경우 로컬 실행 파일을 사용하여 서드 파티 토큰을 가져옵니다. 실행 파일은 유효하고 만료되지 않은 OIDC ID 토큰 또는 SAML 어설션을 JSON 형식으로 stdout에 제공해야 합니다.

실행 파일 소스 사용자 인증 정보를 사용하려면 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 환경 변수를 1로 설정해야 합니다.

실행 소스 워크로드 아이덴티티 구성을 생성하려면 다음 명령어를 실행합니다.

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• PROVIDER_ID: OIDC 또는 SAML 제공업체 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
• SUBJECT_TOKEN_TYPE: 주체 토큰 유형입니다.
• EXECUTABLE_COMMAND: 실행할 전체 명령어(인수 포함) 프로그램의 절대 경로여야 합니다.

--executable-timeout-millis 플래그는 선택사항입니다. 인증 라이브러리가 실행 파일이 완료될 때까지 대기하는 시간(밀리초)을 지정합니다. 제공하지 않으면 기본값은 30초입니다. 허용되는 최댓값은 2분이고 최솟값은 5초입니다.

선택사항인 --executable-output-file 플래그는 실행 파일의 서드 파티 사용자 인증 정보 응답을 캐시할 경로를 지정합니다. 캐싱은 인증 라이브러리가 실행 파일을 실행하기 전에 먼저 이 파일에서 유효하고 만료되지 않은 사용자 인증 정보를 확인하므로 성능을 개선하는 데 도움이 됩니다. 유효한 캐시된 사용자 인증 정보가 있으면 라이브러리에서 이를 사용하여 불필요한 실행 파일 실행을 방지합니다.

실행 파일은 사용자 인증 정보 응답을 이 파일에 써야 합니다. 인증 라이브러리는 이 위치에서만 읽습니다. 파일의 콘텐츠는 예상되는 JSON 형식과 일치해야 합니다.

서드 파티 토큰을 가져오기 위해 라이브러리는 지정된 명령어를 사용하여 실행 파일을 실행합니다. 실행 파일의 출력은 다음 예에 지정된 응답 형식을 준수해야 하며 stdout에 응답을 출력해야 합니다.

다음은 성공적인 실행 가능한 OIDC 응답의 샘플입니다.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

다음은 실행 가능한 성공적인 SAML 응답의 샘플입니다.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

사용자 인증 정보 구성에서 --executable-output-file 인수를 사용하여 출력 파일을 지정하는 경우 실행 파일의 성공적인 응답에는 expiration_time 필드가 포함되어야 합니다. 이를 통해 인증 라이브러리는 해당 파일에 저장된 사용자 인증 정보의 유효성을 효과적으로 캐시하고 관리할 수 있습니다.

다음은 실행 가능한 오류 응답의 예입니다.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

이 필드는 모두 오류 응답에 필요합니다. 라이브러리는 코드 및 메시지 필드를 발생한 예외의 일부로 사용합니다.

응답 형식 필드 요약: * version: JSON 출력의 버전입니다. 버전 1만 지원됩니다. * success: true인 경우 응답에 서드 파티 토큰과 토큰 유형이 포함되어야 합니다. 출력 파일이 사용자 인증 정보 구성에 지정된 경우 응답에 expiration_time 필드도 포함해야 합니다. 실행 파일은 종료 코드 0으로도 종료되어야 합니다. false인 경우 응답은 오류 코드와 메시지 필드를 포함하고 0이 아닌 값으로 종료되어야 합니다. * token_type: 이 필드는 서드 파티 제목 토큰 유형을 지정합니다. urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token 또는 urn:ietf:params:oauth:token-type:saml2이어야 합니다. * id_token: 서드 파티 OIDC 토큰입니다. * saml_response: 서드 파티 SAML 응답입니다. * expiration_time: 서드 파티 주체 토큰 만료 시간(초)(유닉스 에포크 시간)입니다. * code: 오류 코드 문자열입니다. * message: 오류 메시지입니다.

모든 응답 유형에는 version 및 success 필드가 모두 포함되어야 합니다. * 성공적인 응답에는 token_type와 id_token 또는 saml_response 중 하나가 포함되어야 합니다. 출력 파일이 사용자 인증 정보 구성에 지정된 경우 expiration_time 필드도 있어야 합니다. * 오류 응답에는 code 및 message 필드가 모두 포함되어야 합니다.

라이브러리는 실행 파일을 실행할 때 다음 환경 변수를 채웁니다.

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 사용자 인증 정보 구성의 잠재고객 필드입니다. 항상 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 예상되는 주체 토큰 유형입니다. 항상 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: 서비스 계정 이메일 주소입니다. 서비스 계정 명의 도용이 사용된 경우에만 표시됩니다.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 사용자 인증 정보 구성의 출력 파일 위치입니다. 사용자 인증 정보 구성에 지정된 경우에만 존재합니다.

이러한 환경 변수를 사용하여 실행 파일에서 이러한 값을 하드코딩하지 않도록 할 수 있습니다.

보안 고려사항

다음 보안 방법을 따르는 것이 좋습니다.

• stdout를 통해 이러한 프로세스와 사용자에게 민감한 사용자 인증 정보를 출력하므로 악성 프로세스가 실행 파일을 실행하지 못하도록 합니다.
• 비정상 프로세스가 구성이나 실행 파일의 호출을 변경하지 못하도록 방지합니다.

실행 파일 소스 사용자 인증 정보의 사용이 복잡하므로 특정 요구사항을 충족하지 않는 경우를 제외하고 파일 또는 URL 소스와 같은 지원되는 다른 메커니즘을 사용하여 서드 파티 사용자 인증 정보를 제공하는 것이 좋습니다.

이제 인증 라이브러리를 사용하여 OIDC 또는 SAML 제공업체에서Google Cloud 리소스를 호출할 수 있습니다.

OIDC 및 SAML과 함께 맞춤 공급업체 사용

IdentityPoolCredentials을 빌드하는 동안 IdentityPoolSubjectTokenSupplier의 맞춤 구현을 사용하여 Google Cloud 액세스 토큰으로 교환할 수 있는 주제 토큰을 제공할 수 있습니다. 공급자는 Google Cloud사용자 인증 정보에 의해 호출될 때 유효하고 만료되지 않은 주제 토큰을 반환해야 합니다.

IdentityPoolCredentials는 반환된 토큰을 캐시하지 않으므로 동일한 주제 토큰에 대한 여러 요청을 방지하기 위해 토큰 공급자에 캐싱 로직을 구현하세요.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

여기서 audience는 다음을 나타냅니다.

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• WORKLOAD_POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• PROVIDER_ID: 공급업체 ID

gcloud CLI로 사용자 인증 정보 구성 파일을 생성하여 대상, 서비스 계정 가장 URL, 기타 빌더 필드의 값을 찾을 수도 있습니다.

AWS에서 맞춤 공급업체 사용

AwsCredentials을 초기화할 때 AwsSecurityCredentialsSupplier의 맞춤 구현을 제공할 수 있습니다. 제공된 경우 AwsCredentials 인스턴스는 공급자에게 위임하여Google Cloud 액세스 토큰으로 교환할 AWS 보안 사용자 인증 정보를 가져옵니다. 공급자는 Google Cloud credential에 의해 호출될 때 유효하고 만료되지 않은 AWS 보안 사용자 인증 정보를 반환해야 합니다.

AwsCredentials 반환된 AWS 보안 사용자 인증 정보 또는 리전을 캐시하지 마세요. 동일한 리소스에 대한 여러 요청을 방지하려면 공급업체에서 캐싱 로직을 구현하세요.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

여기서 audience는 다음과 같습니다. //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• WORKLOAD_POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• PROVIDER_ID: 공급업체 ID

gcloud CLI로 사용자 인증 정보 구성 파일을 생성하여 대상, 서비스 계정 가장 URL, 기타 빌더 필드의 값을 찾을 수도 있습니다.

구성 가능한 토큰 수명

서비스 계정 가장을 사용하여 워크로드 아이덴티티 제휴로 사용자 인증 정보 구성을 만들 때 서비스 계정 액세스 토큰 수명을 구성하는 선택적 인수를 제공할 수 있습니다.

구성 가능한 토큰 수명으로 구성을 생성하려면 다음 명령어를 실행합니다. 이 예에서는 AWS 구성을 사용하지만 모든 워크로드 아이덴티티 제휴 공급자에 대해 토큰 수명을 구성할 수 있습니다.

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

다음을 바꿉니다.

• PROJECT_NUMBER: Google Cloud 프로젝트 번호
• POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
• AWS_PROVIDER_ID: AWS 공급자 ID입니다.
• SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
• TOKEN_LIFETIME: 선택한 서비스 계정 액세스 토큰의 수명 기간(초)입니다.

service-account-token-lifetime-seconds 플래그는 선택사항입니다. 제공되지 않으면 플래그는 기본적으로 1시간으로 설정됩니다. 허용되는 최소값은 600 (10분)이고 허용되는 최댓값은 43200 (12시간)입니다. 1시간 넘는 수명이 필요하면 constraints/iam.allowServiceAccountCredentialLifetimeExtension 제약조건을 시행하는 조직 정책 서비스에 서비스 계정을 허용되는 값으로 추가해야 합니다.

짧은 전체 기간 (예: 10분)을 구성하면 라이브러리가 10분마다 전체 토큰 교환 흐름을 시작합니다. 이렇게 하면 서드 파티 토큰이 만료되지 않은 경우에도 서드 파티 토큰 제공자가 호출됩니다.

승인된 외부 계정 사용자 직원 인증 정보 사용

외부 계정 승인된 사용자 사용자 인증 정보를 사용하면 gcloud CLI를 사용하여 웹브라우저로 외부 ID 공급업체 계정에 로그인하고 인증 라이브러리에서 사용할 구성을 만들 수 있습니다.

승인된 사용자 직원 ID 외부 계정 구성을 생성하려면 다음 명령어를 실행합니다.

gcloud auth application-default login --login-config=LOGIN_CONFIG

여기서 다음 변수를 대체해야 합니다.

• LOGIN_CONFIG: Google Cloud 콘솔 또는 gcloud iam workforce-pools create-login-config로 생성된 로그인 구성 파일

그러면 구성된 서드 파티 ID 공급업체를 사용하여 로그인할 수 있는 브라우저 흐름이 열립니다. 그런 다음 승인된 외부 계정 사용자 구성을 잘 알려진 ADC 위치에 저장합니다.

그러면 인증 라이브러리가 구성에서 제공된 갱신 토큰을 사용하여 액세스 토큰을 생성하고 갱신하여 Google Cloud 서비스를 호출합니다.

새로고침 토큰의 기본 수명은 1시간입니다. 그런 다음 gcloud CLI에서 새 구성을 생성해야 합니다. 직원 풀의 세션 시간을 변경하여 수명을 수정할 수 있으며 최대 12시간까지 설정할 수 있습니다.

외부 ID 사용

Application Default Credentials에서 외부 ID를 사용할 수 있습니다. 애플리케이션 기본 사용자 인증 정보와 함께 외부 ID를 사용하려면 워크로드 아이덴티티 제휴 섹션에 설명된 대로 외부 ID의 JSON 사용자 인증 정보 구성 파일을 생성합니다. 생성되면 이 파일의 경로를 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 저장합니다.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

이제 라이브러리에서 올바른 유형의 클라이언트를 선택하고 구성 파일에서 제공하는 컨텍스트에서 사용자 인증 정보를 초기화할 수 있습니다.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

생성된 구성 파일을 사용하여 외부 계정 클라이언트를 명시적으로 초기화할 수도 있습니다.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

보안 고려사항

이 라이브러리는 사용자 인증 정보 구성의 token_url, token_info_url 또는 service_account_impersonation_url 필드에 대한 유효성 검사를 실행하지 않습니다. URL 필드가 googleapis.com 도메인을 가리키는지 확인하지 않는 한 gcloud CLI로 생성하지 않은 사용자 인증 정보 구성을 사용하지 않는 것이 좋습니다.

사용자 인증 정보 액세스 경계를 사용하여 권한 축소

사용자 인증 정보 액세스 경계를 사용한 범위 축소를 사용하면 단기 사용자 인증 정보가 Cloud Storage에 사용할 수 있는 Identity and Access Management (IAM) 권한을 제한할 수 있습니다. 여기에는 범위가 축소된 토큰에 적용되는 제한사항을 정의하는 CredentialAccessBoundary를 만드는 작업이 포함됩니다. 범위가 축소된 사용자 인증 정보를 사용하면 전송 중인 토큰에 항상 최소 권한이 부여됩니다. 최소 권한의 원칙을 참고하세요.

CredentialAccessBoundary 만들기

사용자 인증 정보 액세스 경계는 새로 생성된 사용자 인증 정보가 액세스할 수 있는 리소스를 지정합니다. 또한 각 리소스에서 사용할 수 있는 권한의 상한값을 지정합니다. 여기에는 하나 이상의 AccessBoundaryRule 객체가 포함됩니다.

다음 스니펫은 AccessBoundaryRule 하나로 CredentialAccessBoundary를 초기화하는 방법을 보여줍니다. 이 규칙은 범위가 축소된 토큰이 bucket-123 버킷에서 customer-a로 시작하는 객체에 대한 읽기 전용 액세스 권한을 갖는다고 지정합니다.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

일반적인 사용 패턴

일반적인 사용 패턴에는 액세스 권한이 상승된 토큰 브로커가 포함됩니다. 이 브로커는 액세스 권한이 높은 소스 사용자 인증 정보에서 권한이 축소된 사용자 인증 정보를 생성합니다. 그런 다음 권한이 축소된 단기 액세스 토큰을 Google Cloud스토리지 리소스에 대한 제한된 액세스를 위해 보안 인증 채널을 통해 토큰 소비자에게 전달합니다.

범위가 축소된 토큰 생성

CredentialAccessBoundary를 사용하여 권한이 축소된 토큰을 생성하는 방법에는 두 가지가 있습니다.

• 서버 측 (DownscopedCredentials 사용): 권한이 축소된 토큰이 필요할 때마다 클라이언트가 보안 토큰 서비스 (STS)를 호출합니다. 이는 사용자 인증 정보 액세스 경계 규칙이 자주 변경되지 않거나 권한이 축소된 단일 사용자 인증 정보를 여러 번 재사용하는 애플리케이션에 적합합니다. 중요한 점은 규칙을 변경할 때마다 STS를 새로 호출해야 한다는 것입니다. 이 접근 방식은 google-auth-library-oauth2-http 라이브러리 내에서 사용할 수 있으며 추가 종속 항목이 필요하지 않습니다. 이렇게 하면 통합이 더 간단해집니다. 사용 사례에서 클라이언트 측 접근 방식의 구체적인 이점을 요구하지 않는 경우에 적합합니다.

• 클라이언트 측 (ClientSideCredentialAccessBoundaryFactory 사용): 클라이언트가 암호화 자료를 한 번 가져온 다음 범위가 축소된 토큰을 여러 개 로컬로 생성합니다. 이렇게 하면 STS 호출이 최소화되고 사용자 인증 정보 액세스 경계 규칙이 자주 변경될 때 더 효율적입니다. 클라이언트가 각 규칙 변경에 대해 STS에 문의할 필요가 없기 때문입니다. 또한 권한 범위가 축소된 많은 고유 토큰을 생성해야 하는 애플리케이션에도 효율적입니다. 이 접근 방식은 google-auth-library-cab-token-generator 모듈에서 사용할 수 있습니다. 하지만 이 모듈에는 자체 종속 항목이 있습니다. 이러한 종속 항목은 프로젝트에 복잡성을 추가할 수 있습니다. STS 호출을 최소화하고 고유한 토큰을 많이 생성하는 것이 주요 관심사라면 이 방법을 고려하세요. 추가 종속 항목도 관리해야 합니다.

서버 측 CAB

DownscopedCredentials 클래스를 사용하여 소스 사용자 인증 정보와 CredentialAccessBoundary에서 권한이 축소된 액세스 토큰을 생성할 수 있습니다.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

클라이언트 측 CAB

클라이언트 측 CAB의 경우 ClientSideCredentialAccessBoundaryFactory가 소스 사용자 인증 정보와 함께 사용됩니다. 팩토리를 초기화한 후 generateToken() 메서드를 다양한 CredentialAccessBoundary 객체와 함께 반복적으로 호출하여 범위가 축소된 여러 토큰을 만들 수 있습니다.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

권한이 축소된 액세스 토큰 사용

비공개 네트워크의 서버에서 토큰 브로커를 설정할 수 있습니다. 동일한 네트워크의 다양한 워크로드 (토큰 소비자)가 권한이 축소된 토큰을 위해 인증된 요청을 해당 브로커로 전송합니다. 이러한 토큰을 통해 특정 Google Cloud 스토리지 버킷에 액세스하거나 수정할 수 있습니다.

브로커는 단기 범위 축소 액세스 토큰을 생성할 수 있는 범위 축소 사용자 인증 정보 인스턴스를 인스턴스화합니다. 그런 다음 이러한 토큰을 토큰 소비자로 전달합니다.

이러한 권한이 축소된 액세스 토큰은 OAuth2Credentials 또는 OAuth2CredentialsWithRefresh를 사용하여 토큰 소비자가 사용할 수 있습니다. 그런 다음 이 사용자 인증 정보를 사용하여 스토리지 클라이언트 인스턴스를 초기화하여 액세스가 제한된 Google Cloud스토리지 리소스에 액세스할 수 있습니다.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

Cloud Storage만 사용자 인증 정보 액세스 경계를 지원하며 다른Google Cloud 서비스는 이 기능을 지원하지 않습니다.

google-http-client로 사용자 인증 정보 사용

com.google.auth:google-auth-library-oauth2-http에서 제공하는 사용자 인증 정보는 Google의 HTTP 기반 클라이언트와 함께 사용할 수 있습니다. Google의 HTTP 기반 클라이언트는 빌더의 마지막 인수인 HttpRequestInitializer로 사용할 수 있는 HttpCredentialsAdapter를 제공합니다.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

JWT 토큰 확인 (베타 기능)

JWT 토큰을 확인하려면 TokenVerifier 클래스를 사용하세요.

서명 확인

서명을 확인하려면 기본 TokenVerifier를 사용합니다.

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

TokenVerifier 맞춤설정하기

TokenVerifier을 맞춤설정하려면 빌더를 사용하여 인스턴스화하세요.

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

더 많은 옵션은 TokenVerifier.Builder 문서를 참고하세요.

google-auth-library-credentials

이 아티팩트에는 Google 사용자 인증 정보의 기본 클래스와 인터페이스가 포함되어 있습니다.

• Credentials: 승인된 ID의 기본 클래스입니다. 이 클래스의 구현은 애플리케이션을 승인할 수 있습니다.
• RequestMetadataCallback: 비동기 Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback)의 결과를 수신하는 콜백의 인터페이스입니다.
• ServiceAccountSigner: 서비스 계정 서명자의 인터페이스입니다. 이 클래스의 구현은 Google 서비스 계정에 연결된 사용자 인증 정보를 사용하여 바이트 배열에 서명할 수 있습니다.

google-auth-library-appengine

이 아티팩트는 App Engine SDK (appengine-api-1.0-sdk)에 종속됩니다. urlfetch를 사용하는 App Engine 환경에서 실행되는 애플리케이션에만 사용하세요. AppEngineCredentials 클래스를 사용하면 AppIdentityService 인스턴스가 제공된 App Engine 애플리케이션을 승인할 수 있습니다.

사용:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

중요: com.google.auth.appengine.AppEngineCredentials은 com.google.auth.oauth2.AppEngineCredentials과 별도의 클래스입니다.

google-auth-library-cab-token-generator

이 모듈은 ClientSideCredentialAccessBoundaryFactory 클래스를 제공하여 사용자 인증 정보 액세스 경계를 사용하여 Cloud Storage용 범위가 축소된 토큰을 클라이언트 측에서 생성할 수 있도록 지원합니다. 이 접근 방식은 보안 토큰 서비스 (STS)에 대한 호출을 최소화하므로 사용자 인증 정보 액세스 경계 규칙을 자주 변경하거나 고유한 범위 축소 토큰을 많이 생성해야 하는 애플리케이션에 특히 유용합니다. 사용 예는 클라이언트 측 CAB 섹션을 참고하세요. 이 모듈에는 자체 종속 항목이 있습니다. 클라이언트 측 다운스코핑의 이점이 특정 사용 사례의 추가 복잡성보다 큰지 평가하세요.