워크로드 아이덴티티 제휴의 인증서 기반 액세스 구성

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 X.509 인증서를 사용하여 워크로드 아이덴티티 제휴에 대한 인증서 기반 액세스를 구성하는 방법을 설명합니다.

인증서 기반 액세스는 상호 TLS (mTLS)를 사용하여 TLS 핸드셰이크 중에 클라이언트와 서버를 모두 인증합니다. 이 프로세스에서 mTLS 바인딩은 전송 컨텍스트를 기반으로 정책을 통합하고 TLS 세션 내에서 클라이언트 인증서 상태를 사용하여 승인 결정을 내립니다.

X.509 워크로드 아이덴티티 제휴의 경우 mTLS 바인딩은 전체 인증 흐름이 신뢰할 수 있는 워크로드에 안전하게 연결되도록 합니다. 이렇게 하면 시스템이 인증을 신뢰할 수 있는 특정 엔드포인트에 바인딩하므로 사용자 인증 정보 도용 위험이 완화됩니다.

워크로드 아이덴티티 제휴를 위한 인증서 기반 액세스 구성 개요

다음은 워크로드 아이덴티티 제휴에 대한 인증서 기반 액세스를 구성하는 프로세스를 간략하게 설명합니다.

1. X.509 인증서의 신뢰 앵커로 트러스트를 구성하여 워크로드 아이덴티티 제휴를 설정합니다.

2. 인증서 기반 액세스의 액세스 수준을 만듭니다.

3. mTLS 바인딩을 적용하는 컨텍스트 인식 액세스 정책에 액세스 수준을 추가합니다.

시작하기 전에

다음 기본 요건을 충족하는지 확인합니다.

• 최신 버전의 Google Cloud CLI입니다.

  gcloud CLI를 최신 버전으로 업데이트하려면 다음 명령어를 실행합니다.

  gcloud components update
  

  gcloud CLI를 설치해야 하는 경우 gcloud CLI 설치를 참조하세요.

• X.509 인증서 신뢰 앵커를 사용하는 워크로드 아이덴티티 제휴 구성

• 이 기능을 사용하려면 허용 목록 요청 양식을 작성하여 액세스를 요청하세요.

인증서의 액세스 수준 만들기

1. mTLS 액세스 수준을 만듭니다. mTLS 액세스 수준은 리소스에 대한 액세스를 결정할 때 인증서를 검증합니다.

   콘솔

   Access Context Manager에서 커스텀 액세스 수준을 만들고 CEL 표현식 필드에 request.auth.matchesMtlsTokens(origin) == true 표현식을 입력합니다.

   gcloud

   커스텀 액세스 수준을 만들려면 다음 명령어를 실행합니다.

   gcloud access-context-manager levels create ACCESS_LEVEL_NAME \
       --title=TITLE \
       --custom-level-spec=FILE \
       --description=DESCRIPTION \
       --policy=POLICY_NAME

   다음을 바꿉니다.

   • ACCESS_LEVEL_NAME: 액세스 수준의 이름입니다.
   • TITLE: 액세스 수준의 제목입니다.
   • FILE: expression: "request.auth.matchesMtlsTokens(origin) == true" 콘텐츠가 포함된 YAML 파일입니다.
   • DESCRIPTION: 액세스 수준에 대한 설명입니다.
   • POLICY_NAME: 액세스 정책의 이름입니다.

2. 이후 단계에서 사용할 수 있도록 만든 액세스 수준을 환경 변수로 내보냅니다.

     export ACCESS_LEVEL_ID=ACCESS_LEVEL_ID
     

   ACCESS_LEVEL_ID을 액세스 수준 이름으로 바꿉니다(예: accessPolicies/12345/accessLevels/acl_1).

워크로드 아이덴티티 풀에 대한 컨텍스트 인식 액세스 바인딩 만들기

1. 다음 환경 변수를 설정합니다.

   export ORG_ID=ORG_ID
   export CALLER_PROJECT_ID=CALLER_PROJECT_ID
   export FEDERATED_PRINCIPAL=FEDERATED_PRINCIPAL
   

   다음을 바꿉니다.

   • ORG_ID: 조직의 ID입니다.
   • CALLER_PROJECT_ID: API를 호출하는 데 사용할 프로젝트의 ID입니다.

   • FEDERATED_PRINCIPAL: 컨텍스트 인식 액세스 정책을 준수하는 워크로드 아이덴티티 풀의 ID 주 구성원 이름입니다. 다음 옵션 중 하나를 사용할 수 있습니다.

     • 단일 ID: principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
     • 풀의 모든 ID: principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

   gcloud

   gcloud alpha access-context-manager cloud-bindings create \
   --organization=ORG_ID \
   --federated-principal=FEDERATED_PRINCIPAL \
   --level=ACCESS_LEVEL_ID \
   --dry-run-level=DRY_RUN_ACCESS_LEVEL_ID
   

   다음을 바꿉니다.

   • ACCESS_LEVEL_ID: 액세스 수준 이름입니다.
   • DRY_RUN_ACCESS_LEVEL_ID: 드라이 런 액세스 수준 이름입니다. 기존 트래픽에 미칠 수 있는 영향을 파악하기 위해 먼저 드라이 런 정책 바인딩을 사용 설정하는 것이 좋습니다.

   curl

   1. 컨텍스트 인식 액세스 바인딩을 사용하여 JSON 파일을 만듭니다.

      필드가 반복되더라도 요청에 액세스 수준을 하나만 제공할 수 있습니다. 다음 유형의 제휴 주 구성원을 사용할 수 있습니다.

      • 단일 ID: principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
      • 풀의 모든 ID: principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

      cat <<EOF > request.json
      {
        "principal": {
          "federatedPrincipal": "${FEDERATED_PRINCIPAL:?}"
        },
        "accessLevels": ["${ACCESS_LEVEL_ID:?}"]
      }
      EOF
      

   2. curl을 사용하여 다음 HTTP 요청을 전송합니다.

      curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
       "https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings"
      

Google Cloud 클라이언트 라이브러리를 사용하여 승인

Google Cloud 클라이언트 라이브러리를 사용하여 워크로드 아이덴티티 제휴 워크로드를 승인하려면 다음 단계를 완료하세요.

1. 워크로드 아이덴티티 제휴 인증에 구성된 애플리케이션 기본 사용자 인증 정보 (ADC) 파일을 만듭니다.

   gcloud iam workload-identity-pools create-cred-config IDENTITY_POOL_ID \
   --credential-cert-path WORKLOAD_CERTIFICATE_PATH \
   --credential-cert-private-key-path WORKLOAD_KEY_PATH \
   --output-file ADC_FILE_OUTPUT_PATH
   

   다음을 바꿉니다.

   • IDENTITY_POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
   • WORKLOAD_CERTIFICATE_PATH: 워크로드의 인증서 파일 경로입니다.
   • WORKLOAD_KEY_PATH: 워크로드의 비공개 키 파일 경로입니다.
   • ADC_FILE_OUTPUT_PATH: ADC 파일의 출력 경로입니다.

   이 명령어는 gcloud CLI 기본 구성 디렉터리에 인증서 구성 파일도 생성합니다. 인증서 구성 파일은 초기 인증을 지원하고 Google Cloud 리소스에 대한 후속 요청에 mTLS 핸드셰이크를 설정합니다.

2. Google 클라이언트 라이브러리에서 사용자 인증 정보를 검색할 수 있도록 ADC 파일을 가리키는 환경 변수를 설정합니다.

   export GOOGLE_APPLICATION_CREDENTIALS=ADC_FILE_OUTPUT_PATH
   

   ADC 파일을 생성할 때 --output-file 인수를 생략하는 경우 이 단계는 선택사항입니다. 인수를 생략하면 gcloud CLI가 gcloud CLI 기본 구성 디렉터리에서 ADC 파일을 만들고 읽습니다.

3. 이 기능은 Go, Python, 자바의 클라이언트 라이브러리를 지원합니다. Python 및 Java에 mTLS를 사용 설정하려면 환경 변수를 설정해야 합니다.

4. Google Cloud API에 대한 mTLS 액세스를 빠르게 설정하고 테스트하려면 다음 코드 예시를 사용하면 됩니다.

   Go

   1. 다음 예시를 사용하여 Go 파일(예: golang_test.go)을 만듭니다.

      package golang_test
      
      import (
           "io"
           "log"
           "testing"
      
           "cloud.google.com/go/auth/credentials"
           "cloud.google.com/go/auth/httptransport"
      )
      
      func TestGoExample(t *testing.T) {
      
           scopes := []string{
                   "https://www.googleapis.com/auth/pubsub", // Scope for Pub/Sub access
                   // Add other scopes as needed
           }
      
           dopts := credentials.DetectOptions{
                   Scopes: scopes,
           }
      
           // Create httptransport.Options with the scopes
           opts := &httptransport.Options{
                   DetectOpts: &dopts,
           }
           hc, err := httptransport.NewClient(opts)
           if err != nil {
                   t.Fatalf("NewHTTPClient: %v", err)
           }
      
           resp, err := hc.Get("https://pubsub.mtls.googleapis.com/v1/projects/PROJECT_ID/topics")
           if err != nil {
                   t.Fatalf("Get: %v", err)
           }
           t.Logf("Status: %s", resp.Status)
      
           t.Cleanup(func() {
                  resp.Body.Close()
           })
      
           b, err := io.ReadAll(resp.Body)
           if err != nil {
                  t.Fatal(err)
           }
           log.Println(string(b))
      }
      

      PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

   2. Compute Engine VM에서 테스트를 실행하려면 다음 명령어를 사용합니다.

   go mod init example.com
   go mod tidy
   go test -v golang_test.go --count=1
   

   Python

   1. 다음 예시를 사용하여 테스트 파일(예: python_test.py)을 만듭니다.

      import google.auth
      import google.auth.transport.requests
      import requests
      
      def test_python_example():
      # Define the required scopes for your application
      scopes = [
         "https://www.googleapis.com/auth/pubsub",  # Scope for Pub/Sub access
         # Add other scopes as needed
      ]
      
      # Obtain Application Default Credentials (ADC) with the specified scopes
      credentials, _ = google.auth.default(scopes=scopes)
      
      # Create an authorized HTTP session using the ADC credentials
      authed_session = google.auth.transport.requests.AuthorizedSession(credentials)
      
      try:
       # Make a GET request to the Pub/Sub API endpoint
       response = authed_session.get(
           "https://pubsub.mtls.googleapis.com/v1/projects/PROJECT_ID/topics"
       )
      
       # Check if the request was successful
       response.raise_for_status()  # Raise an exception for error statuses
      
       # Log the response status and content
       print(f"Status: {response.status_code}")
       print(response.text)
      
      except requests.exceptions.RequestException as e:
       print(f"Error making the request: {e}")
      
      if __name__ == "__main__":
      test_python_example()
      

      PROJECT_ID를Google Cloud 프로젝트 ID로 바꿉니다.

   2. Compute Engine VM에서 테스트를 실행하려면 다음 단계를 완료합니다.

      1. Python 가상 환경을 설정합니다.

      2. 필요한 라이브러리를 설치합니다.

         pip install google-auth google-auth-httplib2 requests
         

      3. 테스트를 실행합니다.

         python3 python_test.py
         

일반 HTTP 요청을 사용하여 승인

일반 HTTP 요청을 사용하여 워크로드 아이덴티티 제휴 워크로드를 승인하려면 다음 단계를 완료합니다.

1. 표준 mTLS 핸드셰이크를 통해 Google Cloud 보안 토큰 서비스에서 인증서 바인딩 액세스 토큰을 가져옵니다.

2. 보안 토큰 서비스에서 가져온 액세스 토큰으로 Google Cloud 서비스를 호출합니다. 이 예시에서는 Cloud Storage를 쿼리합니다.

   curl --key WORKLOAD_KEY_PATH --cert WORKLOAD_CERTIFICATE_PATH \
    -X GET "https://storage.mtls.googleapis.com/RESOURCE_PATH" \
    -H "Authorization: Bearer $ACCESS_TOKEN"
   

3. mTLS 바인딩은 mTLS 사용을 적용합니다. 다음 명령어를 실행하여 mTLS가 아닌 연결이 승인되지 않은 오류로 실패하는지 확인합니다.

   curl -X GET "https://storage.googleapis.com/RESOURCE_PATH" \
    -H "Authorization: Bearer $ACCESS_TOKEN"
   

정책 바인딩 나열

워크로드 아이덴티티 제휴의 정책 바인딩을 나열하려면 다음 명령어를 실행합니다.

gcloud

다음 명령어는 지정된 조직 내의 특정 바인딩을 나열하고 제휴 주 구성원에 적용되는 바인딩을 필터링합니다.

gcloud alpha access-context-manager cloud-bindings list \
--organization=ORG_ID \
--filter='principal:federatedPrincipal'

curl

curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings?filter=principal%3Afederated_principal"

정책 바인딩 업데이트

정책 바인딩을 업데이트하려면 다음 단계를 완료합니다.

gcloud

gcloud alpha access-context-manager cloud-bindings update \
--binding=BINDING_ID \
--organization=ORG_ID \
--level=NEW_ACCESS_LEVEL_ID

curl

request.json 파일에 새 액세스 수준을 추가하고 다음 명령어를 실행합니다.

curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d @request.json \
"https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings/${BINDING_ID:?}?updateMask=access_levels"

정책 바인딩 삭제

정책 바인딩을 삭제하려면 다음 명령어를 실행합니다.

gcloud

gcloud alpha access-context-manager cloud-bindings delete \
--binding=BINDING_ID \
--organization=ORG_ID

curl

curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X DELETE \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings/${BINDING_ID:?}"

다음 단계

• 워크로드 아이덴티티 제휴의 인증서 기반 액세스 문제 해결