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

개요

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

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

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

이 문서는 Java 개발자를 대상으로 합니다. 전체 API 세부정보는 Google 인증 라이브러리 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, 파일 경로 또는 스트림)을 사용하는 경우 이를 검증해야 합니다.Cloud de Confiance by S3NS 에 인증하기 위해 Google API 또는 클라이언트 라이브러리에 검증되지 않은 사용자 인증 정보를 제공하면 시스템과 데이터의 보안이 손상될 수 있습니다.

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

Google 인증 라이브러리 가져오기

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

Java SDK libraries-bom

Google 인증 라이브러리를 사용하여 Java SDK의 클라이언트 라이브러리(예: google-cloud-datastore)에 인증하려면 libraries-bom를 사용합니다. 그러면 해당 클라이언트 라이브러리와 호환되는 Google 인증 라이브러리 버전이 가져옵니다.

예를 들어 pom.xml을 사용하여 Maven으로 Google 인증 라이브러리를 가져오려면 다음 안내를 따르세요.

<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 인증 라이브러리 자재 명세서

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

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 인증 라이브러리 모듈을 지정할 수 있습니다. 예를 들어 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를 가져와 Google 인증 라이브러리 모듈의 호환 버전과 전이 종속 항목을 자동으로 처리할 수 없습니다.

대신 필요한 각 하위 모듈을 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"

Google 인증 라이브러리 로깅

Java용 Google 인증 라이브러리는 클라이언트 라이브러리 디버그 로깅을 사용하여 로깅하는 것이 좋습니다. 디버그 로깅은 민감한 토큰(예: access_token, refresh_token 등)을 해싱하고 값은 마스킹됩니다. 민감한 토큰이 유출되지 않도록 Google 인증 라이브러리에서 java.util.logging를 사용한 로깅이 사용 중지됩니다.

클라이언트 디버그 로깅 기능은 선택사항이며 설정이 필요합니다.

디버그 로깅은 로그 수준에 따라 다음을 로깅할 수 있습니다.

  • 요청 정보: 헤더, URL, 메서드(INFO 수준)
  • 응답 정보: 헤더, 상태, 메시지(INFO 수준)
  • 응답 페이로드(DEBUG 수준)

GoogleCredential에서 GoogleCredentials로 마이그레이션

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

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

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

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

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

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

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

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

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

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

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

  1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수로 지정된 사용자 인증 정보 파일
  2. Google Cloud SDK gcloud auth application-default login 명령어에서 제공하는 사용자 인증 정보
  3. Google App Engine 기본 제공 사용자 인증 정보
  4. Cloud de Confiance 셸 내장 사용자 인증 정보
  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(
            "impersonated-account@project.s3ns.iam.gserviceaccount.com")
        .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);
}

에이전트 ID의 인증서 바인딩 토큰

애플리케이션이 에이전트 ID(예: --identity-type=agent-identity로 배포된 Cloud Run 서비스 또는 작업)로 실행되면 ComputeEngineCredentials는 기본적으로 메타데이터 서버에서 인증서 바인딩 액세스 토큰과 ID 토큰을 요청합니다. 바인딩된 토큰은 워크로드의 X.509 인증서에 연결되며 상호 TLS(mTLS)를 통해 일치하는 비공개 키의 소유를 증명해야 합니다. 이 비공개 키는 워크로드에서만 사용할 수 있으므로 유출된 토큰은 다른 곳에서 사용할 수 없습니다.

바인딩된 토큰은 이를 전달하는 요청이 동일한 인증서로 mTLS를 통해 전송되는 경우에만 허용됩니다. 자바용 Cloud 클라이언트 라이브러리는 에이전트 ID가 사용 설정되면 mTLS를 구성하고 순환된 워크로드 인증서를 자동으로 새로고침합니다. 자체 HTTP 클라이언트로 Google API를 호출하는 경우 워크로드 인증서로 mTLS를 구성하고 런타임이 디스크에서 인증서를 순환할 때 이를 새로고침해야 합니다. 순환 후 새로 갱신된 토큰은 새 인증서에 바인딩됩니다. 이전 인증서로 설정된 mTLS 연결을 통해 새 토큰이 전송되면 API는 401 UNAUTHENTICATED로 요청을 거부합니다.

라이브러리는 다음 조건이 모두 충족되는 경우에만 바인딩된 토큰을 요청합니다.

  • GOOGLE_API_CERTIFICATE_CONFIG 환경 변수로 이름이 지정된 파일 또는 기본 위치(/var/run/secrets/workload-spiffe-credentials/)를 통해 워크로드 인증서가 발견됩니다.
  • 인증서의 SPIFFE ID가 에이전트 ID 트러스트 도메인에 속합니다.
  • 토큰 결합 및 mTLS가 사용 중지되지 않았습니다(토큰 결합 사용 중지 참조).

다른 모든 환경에서 ComputeEngineCredentials는 이전과 같이 작동하고 바인딩되지 않은 토큰을 반환합니다.

토큰 결합 사용 중지

토큰 바인딩을 사용 중지해야 하는 경우(알려진 제한사항 참조) 다음 환경 변수를 설정합니다.

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false
환경 변수 효과
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN 바인딩되지 않은 토큰을 요청하려면 false로 설정합니다.
GOOGLE_API_USE_CLIENT_CERTIFICATE 이 값을 false로 설정하면 mTLS가 완전히 사용 중지되며 토큰 결합도 사용 중지됩니다. 바인딩되지 않은 토큰만 필요한 경우 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false를 사용하는 것이 좋습니다.

값은 대소문자를 구분하지 않으며 주변 공백은 무시됩니다. false만 기능을 사용 중지하며 다른 값은 기본값을 그대로 둡니다.

환경 변수는 전체 프로세스에 적용되므로 토큰 바인딩을 사용 중지하면 애플리케이션 기본 사용자 인증 정보를 사용하는 애플리케이션의 모든 라이브러리에 영향을 미칩니다. 일부 대상에 바인딩되지 않은 ID 토큰만 필요한 경우 대신 특정 대상에 바인딩되지 않은 ID 토큰 요청에 설명된 대상별 옵션을 사용합니다.

특정 타겟에 대한 바인딩되지 않은 ID 토큰 요청

바인딩된 ID 토큰은 cnf(x5t#S256) 클레임에 워크로드 인증서 지문을 포함합니다. 수신 서비스는 mTLS 핸드셰이크 중에 제공된 클라이언트 인증서와 비교하여 이 클레임을 검증하거나 인증서 바인딩을 적용하지 않는 경우 클레임을 무시할 수 있습니다.

Cloud Run은 ID 토큰에 cnf 클레임이 있으면 인증서 바인딩을 자동으로 적용합니다. 바인딩된 ID 토큰으로 Cloud Run 서비스를 호출하는 경우 mTLS를 통해 *.mtls.run.app URL을 호출해야 합니다. mTLS가 없는 표준 *.run.app URL 또는 커스텀 도메인에 대한 요청은 401 Unauthorized로 거부됩니다.

비 mTLS 엔드포인트(예: 표준 *.run.app URL)를 통해 인증서 바인딩을 적용하는 서비스를 호출하거나 대상 엔드포인트에 인증서 바인딩이 필요하지 않은 경우 IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN를 전달하여 해당 대상에 대해서만 바인딩되지 않은 ID 토큰을 요청합니다.

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
    IdTokenCredentials.newBuilder()
        .setIdTokenProvider((IdTokenProvider) credentials)
        .setTargetAudience("https://my-service-12345.us-central1.run.app")
        .setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
        .build();

다른 대상의 액세스 토큰과 ID 토큰은 계속 바인딩됩니다. 이 옵션은 ComputeEngineCredentials에서만 지원됩니다. 다른 IdTokenProvider 구현은 바인딩된 ID 토큰을 요청하지 않고 이 옵션을 무시하므로 동일한 코드가 에이전트 ID 환경 외부에서도 작동합니다.

알려진 제한사항

  • Java용 에이전트 개발 키트(ADK)는 Vertex AI의 Gemini와 같은 Google API를 호출할 때 mTLS를 사용하지 않습니다. 바인딩된 토큰(기본값)을 사용하면 이러한 호출은 com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials로 인해 실패합니다. 이 문제를 해결하려면 Java용 ADK를 사용하는 에이전트에 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false를 설정하세요. 자세한 내용은 Cloud Run에서 에이전트 인증을 참조하세요.

워크로드 아이덴티티 제휴

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

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

AWS에서 리소스 액세스

Amazon Web Services(AWS)에서 Cloud de Confiance 리소스에 액세스하려면 먼저 워크로드 아이덴티티 제휴를 구성해야 합니다. 설정 프로세스는 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: Cloud de Confiance 프로젝트 번호입니다.
  • POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
  • AWS_PROVIDER_ID: AWS 제공업체 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.

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

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

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

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

Microsoft Azure에서 리소스 액세스

Microsoft Azure에서 Cloud de Confiance 리소스에 액세스하려면 먼저 워크로드 아이덴티티 제휴를 구성해야 합니다. 설정 프로세스는 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: Cloud de Confiance 프로젝트 번호입니다.
  • POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
  • AZURE_PROVIDER_ID: Azure 제공업체 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.

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

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

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

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

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

OIDC 공급업체의 경우 Java용 Google 인증 라이브러리는 다음 소스에서 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: Cloud de Confiance 프로젝트 번호입니다.
  • 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: Cloud de Confiance 프로젝트 번호입니다.
  • POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
  • OIDC_PROVIDER_ID: OIDC 제공업체 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
  • URL_TO_GET_OIDC_TOKEN: OIDC 토큰을 검색하기 위해 호출할 로컬 서버 엔드포인트의 URL입니다.
  • HEADER_KEY 및 HEADER_VALUE: GET 요청을 URL_TO_GET_OIDC_TOKEN에 전달하는 추가 헤더 키 및 값 쌍(예: Metadata-Flavor=Google)

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

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는 Google 인증 라이브러리가 자동으로 검색할 수 있는 기본 위치에 인증서 구성 파일을 만듭니다. 이 방식은 대부분의 사용 사례에 적합합니다. 기본 사용자 인증 정보 구성 파일의 이름은 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: Cloud de Confiance 프로젝트 번호입니다.
  • 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에 생성됩니다.

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

작업자 위임을 사용하여 리소스에 액세스

RFC 8693: OAuth 2.0 토큰 교환에 정의된 대로 행위자 위임과 함께 OIDC 워크로드 아이덴티티 제휴를 사용하는 워크로드의 경우 Java용 Google 인증 라이브러리는 로컬 JSON 파일에서 서드 파티 주체 토큰과 서드 파티 행위자 토큰을 모두 교환합니다. 주체 토큰은 요청의 주 구성원 ID를 나타내고 행위자 토큰은 주체를 대신하여 작동하는 워크로드 또는 서비스를 나타냅니다.

액터 위임은 다음 두 가지 모드로 사용할 수 있습니다.

  • 표준 작업자 위임(인증서 바인딩 없음): Google 인증 라이브러리는 표준 TLS를 통해 보안 토큰 서비스(sts.googleapis.com)와 주 구성원 토큰 및 작업자 토큰을 교환하고, 구성된 경우 iamcredentials.googleapis.com를 사용하여 서비스 계정을 가장합니다.
  • 작업자 위임이 있는 인증서 바인딩 토큰(mTLS): Google 인증 라이브러리는 sts.mtls.googleapis.com와의 토큰 교환(및 구성된 경우 iamcredentials.mtls.googleapis.com를 사용한 서비스 계정 가장) 중에 상호 TLS(mTLS)를 통해 X.509 클라이언트 인증서를 제공합니다.Cloud de Confiance 는 토큰의 확인(cnf.x5t#S256) 클레임에 있는 SHA-256 인증서 지문이 mTLS 핸드셰이크에 제공된 리프 클라이언트 인증서와 일치하는지 확인하고 해당 인증서에 암호화 방식으로 바인딩된 단기 액세스 토큰을 발급합니다.

시작하기 전에

Java용 Google 인증 라이브러리를 구성하기 전에 다음이 있는지 확인하세요.

  1. 액터 위임에 구성된 OIDC 워크로드 아이덴티티 풀 및 제공업체(주체 제공업체의 --actor-providers 구성에서 승인된 액터 제공업체의 전체 리소스 이름 사용) 및 인증서 바인딩 토큰을 사용할 때 선택적으로 컨텍스트 인식 액세스 정책 시행
  2. 만료 전에 주체 토큰과 행위자 토큰이 모두 포함된 JSON 파일을 지속적으로 새로고침하는 로컬 백그라운드 프로세스:

    {
      "subject_token": "<var>SUBJECT_JWT_TOKEN</var>",
      "actor_token": "<var>ACTOR_JWT_TOKEN</var>"
    }
    

    토큰이 다음 요구사항을 충족하는지 확인합니다.

    • 주체 토큰(may_act 클레임): 주체 토큰에는 작업자의 sub(및 선택적 iss) 클레임을 승인하는 may_act 클레임이 포함되어야 합니다.

       "may_act": {
         "sub": "<var>ACTOR_SUBJECT</var>",
         "iss": "<var>ACTOR_ISSUER</var>"
       }
       ```
      
    • 작업자 토큰(aud, sub, iss 클레임): 작업자 토큰의 aud 클레임은 작업자 제공업체의 전체 리소스 이름(//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>ACTOR_PROVIDER_ID</var>)으로 설정되어야 하며 sub(및 iss) 클레임은 주체 토큰의 may_act 클레임에 선언된 값과 일치해야 합니다.

    • 확인(cnf) 클레임(인증서 바인딩 토큰만 해당): 바인딩된 토큰의 JWT 페이로드에는 워크로드의 DER로 인코딩된 X.509 리프 인증서의 base64url로 인코딩된 SHA-256 인증서 지문(x5t#S256)이 포함된 cnf 클레임이 포함되어야 합니다. 주체 토큰이 인증서에 바인딩된 경우 행위자 토큰도 인증서에 바인딩되어야 하며 mTLS 핸드셰이크에 제공된 클라이언트 인증서가 행위자 토큰의 cnf.x5t#S256 인증서 지문과 일치해야 합니다.

       "cnf": {
         "x5t#S256": "<var>BASE64URL_SHA256_CERT_FINGERPRINT</var>"
       }
       ```
      
  3. (인증서 바인딩 토큰만 해당) PEM으로 인코딩된 X.509 리프 인증서 파일과 디스크에 일치하는 암호화되지 않은 PKCS#8 비공개 키 파일입니다.

작업자 위임을 위한 구성 파일 생성

gcloud iam workload-identity-pools create-cred-config 명령어를 사용하여 구성 파일을 생성할 수 있습니다.

표준 행위자 위임(인증서 바인딩 없음)

인증서 바인딩 없이 표준 작업자 위임을 위한 사용자 인증 정보 구성 파일(config.json)을 생성하려면 다음 명령어를 실행합니다.

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_TOKENS_JSON</var>" \
    --credential-source-type "json" \
    --credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
    --actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
    --actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
    --output-file /path/to/config.json
액터 위임이 있는 인증서 바인딩 토큰(mTLS)

액터 위임으로 인증서 바인딩 토큰을 구성하기 위해 gcloud CLI는 --credential-cert-path 및 --credential-cert-private-key-path 플래그가 지정될 때 두 개의 개별 파일을 생성합니다.

  • 기본 사용자 인증 정보 구성 파일(config.json): 워크로드 아이덴티티 풀 메타데이터, .mtls.googleapis.com 엔드포인트, JSON 토큰 파일 경로, 주체 및 행위자 토큰의 필드 이름, 인증서 구성 파일에 대한 참조가 포함됩니다.
  • 인증서 구성 파일(certificate_config.json): 워크로드의 X.509 리프 인증서 및 비공개 키의 경로를 지정합니다.

--credential-cert-configuration-output-file 플래그를 생략하면(권장) gcloud가 기본 Google Cloud CLI 구성 경로(Linux 및 macOS의 경우 ~/.config/gcloud/certificate_config.json, Windows의 경우 %APPDATA%\gcloud\certificate_config.json)에 certificate_config.json를 만들고 config.json에 "use_default_certificate_config": true를 설정합니다.

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_TOKENS_JSON</var>" \
    --credential-source-type "json" \
    --credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
    --actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
    --actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --output-file /path/to/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>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file "<var>PATH_TO_TOKENS_JSON</var>" \
    --credential-source-type "json" \
    --credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
    --actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
    --actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-configuration-output-file "/custom/path/certificate_config.json" \
    --output-file /path/to/config.json

다음을 바꿉니다.

  • PROJECT_NUMBER: Cloud de Confiance 프로젝트 번호입니다.
  • POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
  • OIDC_PROVIDER_ID: 주체 토큰을 인증하는 OIDC 워크로드 아이덴티티 풀 공급업체 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: (선택사항) 가장할 서비스 계정의 이메일입니다. 직접 리소스 액세스를 사용하는 경우 --service-account를 생략합니다.
  • PATH_TO_TOKENS_JSON: 주체 토큰과 행위자 토큰이 모두 포함된 로컬 JSON 파일의 경로입니다.
  • SUBJECT_TOKEN_FIELD_NAME: 주체 토큰이 포함된 PATH_TO_TOKENS_JSON의 JSON 키입니다(예: subject_token).
  • ACTOR_TOKEN_FIELD_NAME: 작업자 토큰이 포함된 PATH_TO_TOKENS_JSON의 JSON 키입니다(예: actor_token). 이 키는 SUBJECT_TOKEN_FIELD_NAME와 달라야 합니다.
  • PATH_TO_CERTIFICATE(인증서 바인딩 토큰만 해당): PEM으로 인코딩된 리프 X.509 인증서의 경로입니다.
  • PATH_TO_PRIVATE_KEY(인증서 바인딩 토큰만 해당): 해당 PEM으로 인코딩된 비공개 키의 경로입니다.

환경 변수 구성 및 Cloud de Confiance API 호출

  1. 사용자 인증 정보 구성 파일을 가리키도록 GOOGLE_APPLICATION_CREDENTIALS를 설정합니다.

    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json
    

    인증서 바인딩 토큰을 사용하는 경우 GOOGLE_API_USE_CLIENT_CERTIFICATE=true를 설정하여 Cloud 클라이언트 라이브러리에서 클라이언트 인증서 mTLS 전송을 사용 설정합니다.

    export GOOGLE_API_USE_CLIENT_CERTIFICATE=true
    

    certificate_config.json를 커스텀 위치에 저장한 경우 GOOGLE_API_CERTIFICATE_CONFIG를 설정합니다.

    export GOOGLE_API_CERTIFICATE_CONFIG=/custom/path/certificate_config.json
    
  2. 애플리케이션 기본 사용자 인증 정보를 사용하여 Cloud de Confiance 클라이언트 라이브러리를 초기화합니다. 클라이언트 라이브러리는 자동으로 IdentityPoolCredentials를 사용하여 주 구성원 및 작업자 토큰을 교환합니다(인증서 바인딩이 구성된 경우 mTLS를 통해 워크로드 클라이언트 인증서를 제공함).

    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.ProjectName;
    import com.google.pubsub.v1.Topic;
    
    public class ActorDelegationExample {
      public static void main(String[] args) throws Exception {
        String projectId = "your-project-id";
    
        // TopicAdminClient automatically detects GOOGLE_APPLICATION_CREDENTIALS
        // and uses mTLS when GOOGLE_API_USE_CLIENT_CERTIFICATE=true is set.
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
          for (Topic topic :
              topicAdminClient.listTopics(ProjectName.of(projectId)).iterateAll()) {
            System.out.println(topic.getName());
          }
        }
      }
    }
    

토큰 및 인증서 순환

백그라운드 프로세스가 디스크에서 토큰(인증서 바인딩 토큰의 경우 워크로드의 X.509 리프 인증서 및 비공개 키)을 순환할 때는 다음 동작과 요구사항에 유의하세요.

  • 원자적 업데이트: Google 인증 라이브러리는 새로고침당 한 번의 읽기로 JSON 토큰 파일에서 주체 토큰과 행위자 토큰을 모두 읽습니다. 주체 토큰과 행위자 토큰이 동기화된 상태로 유지되도록 JSON 토큰 파일을 원자적으로 업데이트합니다(예: 임시 파일에 쓰고 이름 바꾸기). 인증서 바인딩 토큰을 사용하는 경우 토큰 파일의 cnf.x5t#S256 지문이 디스크의 X.509 인증서와 동기화된 상태로 유지되도록 인증서, 비공개 키, JSON 토큰 파일을 원자적으로 업데이트합니다.
  • 주기별 인증서 고정(인증서 바인딩 토큰): IdentityPoolCredentials가 mTLS를 통해 액세스 토큰을 새로고침할 때 새로고침 주기가 시작될 때 X.509 키 저장소의 스냅샷을 만들고 보안 토큰 서비스 exchangeToken 요청과 (구성된 경우) Service Account Credentials API generateAccessToken 가장 요청 모두에서 동일한 클라이언트 인증서를 사용합니다.
  • 401 Unauthorized에서 자동 새로고침(인증서 바인딩 토큰): 인증서가 순환되고 mTLS 요청이 401 Unauthorized를 반환하면 Google 인증 라이브러리가 디스크에서 X.509 인증서와 비공개 키를 자동으로 새로고침하고 토큰 새로고침을 한 번 다시 시도합니다.

행위자 위임 문제 해결

다음 표에는 액터 위임에 대한 일반적인 오류와 해결 방법이 나와 있습니다.

오류 또는 예외 원인 해결 방법
IllegalArgumentException: Actor tokens are only supported for JSON-formatted credential sources. actor_token_field_name가 지정되었지만 credential_source.format.type가 누락되었거나 text로 설정되었습니다. credential_source.format.type를 "json"로 설정하고 subject_token_field_name 및 actor_token_field_name를 모두 지정합니다.
IllegalArgumentException: The actor_token_field_name must not be empty. credential_source.format의 actor_token_field_name은 빈 문자열("")입니다. actor_token_field_name에 비어 있지 않은 JSON 필드 이름을 제공하거나 작업 수행자 위임이 사용되지 않는 경우 필드를 삭제하세요.
IllegalArgumentException: The actor_token_field_name must differ from the subject_token_field_name. actor_token_field_name 및 subject_token_field_name가 동일한 JSON 키로 설정되어 있습니다. 토큰 파일과 config.json에서 주체 토큰과 행위자 토큰에 고유한 JSON 필드 이름을 사용합니다.
IllegalArgumentException: An actorTokenType must be specified when an actorTokenSupplier is configured.(또는 그 반대) actor_token_type 또는 actor_token_field_name 중 하나만 config.json에 있습니다. "actor_token_type": "urn:ietf:params:oauth:token-type:jwt" 및 credential_source.format.actor_token_field_name 모두 지정합니다.
IOException: Invalid token field name. No token was found for field: FIELD_NAME credential_source.file의 JSON 파일에 구성된 subject_token_field_name 또는 actor_token_field_name 키가 포함되어 있지 않거나 값이 null입니다. 토큰 갱신 프로세스에서 두 키를 모두 JSON 파일에 쓰는지 확인합니다.
IOException: Invalid token field value. Empty token was found for field: FIELD_NAME JSON 토큰 파일에 구성된 subject_token_field_name 또는 actor_token_field_name 키가 비어 있거나 공백만 있는 문자열입니다. 토큰 갱신 프로세스에서 두 필드가 비어 있지 않은 JWT 문자열로 채워지는지 확인합니다.
IOException: Token field value for FIELD_NAME must be a String... JSON 토큰 파일의 subject_token_field_name 또는 actor_token_field_name에 있는 값이 문자열이 아닌 JSON 객체, 배열, 숫자 또는 불리언입니다. 두 토큰 필드에 직렬화된 JWT 문자열("eyJ...")이 포함되어 있는지 확인합니다.
RuntimeException: Failed to initialize mTLS transport for file credential source due to certificate configuration error. SDK가 certificate_config.json, cert_path의 X.509 인증서 또는 key_path의 비공개 키를 로드하거나 파싱할 수 없습니다. certificate_config.json가 기본 경로(또는 GOOGLE_API_CERTIFICATE_CONFIG)에 있고 cert_path 및 key_path가 유효하고 읽을 수 있는 PEM 파일을 가리키는지 확인합니다.
sts.mtls.googleapis.com에서 400 Bad Request/invalid_request 토큰의 cnf.x5t#S256 지문이 mTLS 핸드셰이크 중에 제공된 클라이언트 인증서와 일치하지 않습니다. x5t#S256 값이 certificate_config.json에 있는 DER로 인코딩된 리프 인증서의 base64url로 인코딩된 SHA-256 해시인지 확인합니다.
토큰 교환이 성공한 후 Cloud de Confiance API를 호출할 때 401 Unauthorized 또는 403 Forbidden 다운스트림 클라이언트 라이브러리가 mTLS를 설정하지 않았거나 액세스 토큰에 바인딩된 인증서와 다른 인증서를 사용했습니다. export GOOGLE_API_USE_CLIENT_CERTIFICATE=true가 설정되어 있고 (커스텀 인증서 구성 경로를 사용하는 경우) GOOGLE_API_CERTIFICATE_CONFIG가 config.json에서 참조하는 동일한 certificate_config.json 파일을 가리키는지 확인합니다.

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: Cloud de Confiance 프로젝트 번호입니다.
  • POOL_ID: 워크로드 아이덴티티 풀 ID입니다.
  • PROVIDER_ID: OIDC 또는 SAML 제공업체 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: 가장할 서비스 계정의 이메일입니다.
  • SUBJECT_TOKEN_TYPE: 제목 토큰 유형입니다.
  • EXECUTABLE_COMMAND: 인수를 포함하여 실행할 전체 명령어입니다. 프로그램의 절대 경로여야 합니다.

--executable-timeout-millis 플래그는 선택사항입니다. Google 인증 라이브러리가 실행 파일이 완료될 때까지 대기하는 시간(밀리초)을 지정합니다. 제공하지 않으면 기본값은 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 필드가 포함되어야 합니다. 이렇게 하면 Google 인증 라이브러리가 해당 파일에 저장된 사용자 인증 정보의 유효성을 효과적으로 캐시하고 관리할 수 있습니다.

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

{
  "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 소스와 같은 다른 지원되는 메커니즘을 사용하는 것이 좋습니다.

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

OIDC 및 SAML과 함께 커스텀 공급업체 사용

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

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 Cloud de Confiance audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

잠재고객은 다음과 같습니다.

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

다음을 바꿉니다.

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

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

AWS에서 커스텀 공급업체 사용

AwsCredentials를 초기화할 때 AwsSecurityCredentialsSupplier의 맞춤 구현을 제공할 수 있습니다. 제공된 경우 AwsCredentials 인스턴스는 공급업체에 위임하여 AWS 보안 사용자 인증 정보를 검색하고Cloud de Confiance 액세스 토큰으로 교환합니다. 공급업체는 Cloud de Confiance 사용자 인증 정보로 호출될 때 만료되지 않은 유효한 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 Cloud de Confiance audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

여기서 잠재고객은 다음과 같습니다. //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

다음을 바꿉니다.

  • PROJECT_NUMBER: Cloud de Confiance 프로젝트 번호입니다.
  • 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: Cloud de Confiance 프로젝트 번호입니다.
  • 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 공급업체 계정에 로그인하고 Google 인증 라이브러리에서 사용할 구성을 만들 수 있습니다.

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

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

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

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

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

갱신 토큰의 기본 수명은 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();

일반적인 사용 패턴

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

범위 축소 토큰 생성

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가 소스 사용자 인증 정보와 함께 사용됩니다. 팩토리를 초기화한 후에는 다양한 CredentialAccessBoundary 객체로 generateToken() 메서드를 반복적으로 호출하여 여러 다운스코프 토큰을 만들 수 있습니다.

// 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);

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

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

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

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

// 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만 사용자 인증 정보 액세스 경계를 지원합니다. 다른Cloud de Confiance 서비스는 이 기능을 지원하지 않습니다.

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();

google-auth-library-cab-token-generator

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