X.509 인증서로 워크로드 아이덴티티 제휴 구성

이 가이드에서는 자체 인증 기관(CA)에서 발급한 X.509 인증서가 포함된 워크로드 아이덴티티 제휴를 사용하여 Google Cloud에 인증하고 Google Cloud 리소스에 액세스하는 방법을 설명합니다.

워크로드에 mTLS 클라이언트 인증서가 포함된 경우 하나 이상의 CA를 워크로드 아이덴티티 제휴에 신뢰 앵커로 등록하여 Google Cloud에 인증할 수 있습니다. 중간 CA를 등록할 수도 있습니다.

워크로드 아이덴티티 제휴를 사용하면 상호 TLS(mTLS) 연결을 통해 이러한 워크로드가 단기적으로 사용되는 Google Cloud 사용자 인증 정보를 얻도록 설정할 수 있습니다. 워크로드에서 이 단기 사용자 인증 정보를 사용하여 Google Cloud API에 액세스할 수 있습니다.

개념

X.509 인증서 기반 제휴 개념에는 다음이 포함됩니다.

• 신뢰 앵커는 신뢰할 수 있는 루트로 간주되는 CA 인증서입니다. 클라이언트 인증서 체인은 신뢰 앵커 중 하나에 연결되어야 합니다.

• 중간 CA는 클라이언트 인증서 체인을 빌드할 수 있게 도와주는 선택적인 인증 기관 인증서입니다.

• 트러스트 저장소에는 클라이언트 인증서 체인을 검증하는 데 사용되는 신뢰 앵커 인증서와 중간 CA 인증서가 포함됩니다. CA는 클라이언트에 대해 신뢰 인증서를 발급합니다.

  다음 유형의 클라이언트 인증서를 트러스트 저장소에 업로드할 수 있습니다.

  • 원하는 타사 CA에서 발급한 인증서
  • 비공개 CA에서 발급한 인증서
  • 자체 서명 인증서 만들기에서 설명하는 서명된 인증서

시작하기 전에

워크로드 아이덴티티 제휴 구성을 시작하려면 다음을 수행합니다.

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

전용 프로젝트를 사용하여 워크로드 아이덴티티 풀과 제공업체를 관리하는 것이 좋습니다.

2. Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

필요한 역할

워크로드 아이덴티티 제휴를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청합니다.

• 워크로드 아이덴티티 풀 관리자(roles/iam.workloadIdentityPoolAdmin)
• 서비스 계정 관리자(roles/iam.serviceAccountAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

또는 IAM 소유자(roles/owner) 기본 역할에는 ID 제휴를 구성하는 권한도 포함됩니다. 프로덕션 환경에서는 기본 역할을 부여하지 말아야 하지만 개발 환경 또는 테스트 환경에서는 부여해도 됩니다.

워크로드 아이덴티티 제휴 구성

이 섹션에서는 워크로드 아이덴티티 제휴와 트러스트 저장소를 구성하는 방법을 보여줍니다. 이 단계는 각 트러스트 저장소마다 한 번만 수행하면 됩니다. 그러면 여러 워크로드와 여러 Google Cloud 프로젝트에 동일한 워크로드 아이덴티티 풀과 공급업체를 사용할 수 있습니다.

트러스트 저장소 만들기 및 구성

이 섹션에서는 트러스트 저장소의 YAML 구성 파일과 자체 서명된 CA 인증서를 만드는 방법을 보여줍니다.

키 및 서명된 인증서 생성

이 섹션에서는 openssl 명령어를 사용하여 루트 인증서와 중간 인증서를 만듭니다.

인증서가 이미 있으면 이 단계를 건너뛰고 인증서 형식 지정을 계속하면 됩니다.

유효한 keyUsage 및 extendedKeyUsage 필드를 사용하여 루트 인증서 및 서명된 중간 인증서를 생성하려면 다음을 수행합니다.

1. 유효한 서명 인증서를 만드는 데 필요한 최소 구성으로 샘플 example.cnf 파일을 만듭니다. 이 파일을 수정하여 이러한 인증서에 대해 추가 필드를 설정할 수 있습니다.

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command line arg.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   EOF
   

2. 루트 인증서를 만듭니다.

   openssl req -x509 \
       -new -sha256 -newkey rsa:2048 -nodes \
       -days 3650 -subj '/CN=root' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout root.key -out root.cert
   

3. 중간 인증서에 대한 서명 요청을 만듭니다.

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. 중간 인증서를 만듭니다.

   openssl x509 -req \
       -CAkey root.key -CA root.cert \
       -set_serial 1 \
       -days 3650 \
       -extfile example.cnf \
       -extensions ca_exts \
       -in int.req -out int.cert
   

인증서 형식 지정

트러스트 저장소에 새 인증서 또는 기존 인증서를 포함하려면 YAML 파일로 읽어 들일 수 있도록 인증서를 한 줄 형식으로 지정하고 환경 변수에 저장합니다. 인증서는 PEM 형식으로 지정해야 합니다. 인증서 형식을 지정하고 환경 변수에 저장하려면 다음을 수행합니다.

1. 루트 인증서를 한 줄 문자열로 저장합니다.

   export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

2. 중간 인증서를 한 줄 문자열로 저장합니다.

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

트러스트 저장소 YAML 파일 만들기

이 섹션에서는 신뢰 앵커 및 중간 CA가 포함된 트러스트 저장소 YAML 파일을 만듭니다.

트러스트 저장소 YAML 파일을 만들려면 다음 명령어를 실행합니다. 이 파일에는 인증서 형식 지정에서 만든 환경 변수의 인증서 콘텐츠가 포함됩니다. 신뢰 앵커를 추가하려면 trustStore 아래에 trustAnchors 항목을 추가합니다. 중간 CA 인증서를 추가하려면 trustStore 아래에 intermediateCas 항목을 추가합니다.

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

속성 매핑 및 조건 정의

클라이언트 X.509 인증서에는 여러 속성이 포함될 수 있습니다. Google Cloud의 google.subject를 인증서의 속성에 매핑하여 주체 식별자로 사용하려는 속성을 선택해야 합니다. 예를 들어 인증서의 속성이 주체 일반 이름이면 매핑이 다음과 같이 표시됩니다. google.subject=assertion.subject.dn.cn

필요한 경우 추가 속성을 매핑할 수 있습니다. 그런 다음 리소스에 대한 액세스 권한을 부여할 때 이러한 속성을 참조할 수 있습니다.

속성 매핑은 클라이언트 인증서 내에서 다음과 같은 속성을 사용할 수 있습니다.

• serialNumberHex: 일련번호
• subject.dn.cn: 주체 일반 이름
• subject.dn.o: 주체 조직 이름
• subject.dn.ou: 주체 조직 단위
• issuer.dn.cn: 발급자 일반 이름
• issuer.dn.o: 발급자 조직 이름
• issuer.dn.ou: 발급자 조직 단위
• san.dns: 주체 대체 이름의 첫 번째 DNS 이름
• san.uri: 주체 대체 이름의 첫 번째 URI

주체를 고유하게 식별하려면 이러한 속성 중 하나를 google.subject에 매핑해야 합니다. 스푸핑 위협을 방지하려면 변경될 수 없는 고유 값을 갖는 속성을 선택합니다. 기본적으로 google.subject 식별자는 클라이언트 인증서 주체 일반 이름인 assertion.subject.dn.cn으로 설정됩니다.

선택사항: 속성 조건을 정의합니다. 속성 조건은 어설션 속성 및 대상 속성을 확인할 수 있는 CEL 표현식입니다. 어설션 조건이 특정 사용자 인증 정보에 대해 true로 평가되면 해당 사용자 인증 정보가 수락됩니다. 그렇지 않으면 사용자 인증 정보가 거부됩니다.

속성 조건을 사용하면 워크로드 아이덴티티 제휴를 사용하여 단기 Google Cloud 토큰을 가져올 수 있는 주체를 제한할 수 있습니다.

예를 들어 다음 조건은 SPIFFE ID spiffe://example/path를 포함하는 클라이언트 인증서에 대한 액세스를 제한합니다.

assertion.san.uri=="spiffe://example/path"

워크로드 아이덴티티 풀 및 공급업체 만들기

1. 새 워크로드 아이덴티티 풀을 만들려면 다음 명령어를 실행합니다.

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   다음을 바꿉니다.

   • POOL_ID: 풀의 고유 ID
   • DISPLAY_NAME: 풀의 이름
   • DESCRIPTION: 선택한 풀에 대한 설명 (이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.)

2. X.509 워크로드 아이덴티티 풀 공급업체를 추가하려면 다음 명령어를 실행합니다.

   gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
       --location=global \
       --workload-identity-pool="POOL_ID" \
       --trust-store-config-path="TRUST_STORE_CONFIG" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS" \
       --billing-project="ALLOWLISTED_PROJECT"
   

   다음을 바꿉니다.

   • PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 공급업체 ID
   • POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
   • TRUST_STORE_CONFIG: 트러스트 저장소 YAML 파일입니다.
   • MAPPINGS: 이 가이드 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록 google.subject를 지정하지 않은 경우 기본 매핑은 google.subject=assertion.subject.dn.cn입니다.
   • CONDITIONS: 이 가이드 앞부분에서 만든 속성 조건(선택사항). 속성 조건이 없는 경우 매개변수를 삭제하세요.
   • ALLOWLISTED_PROJECT: 프로젝트 ID입니다.

워크로드 인증

각 워크로드에서 한 번씩 다음 단계를 수행해야 합니다.

외부 워크로드가 Google Cloud 리소스에 액세스하도록 허용

워크로드에 Google Cloud 리소스에 대한 액세스 권한을 제공하려면 주 구성원에게 직접 리소스에 대한 액세스 권한을 부여하는 것이 좋습니다. 이 경우 주 구성원은 제휴 사용자입니다. 일부 Google Cloud 제품에는 Google Cloud API 제한사항이 있습니다. 워크로드가 제한사항이 있는 API 엔드포인트를 호출하는 경우 대신 서비스 계정 가장을 사용할 수 있습니다. 이 경우 주 구성원은 ID 역할을 하는 Google Cloud 서비스 계정입니다. 서비스 계정에 리소스에 대한 액세스 권한을 부여합니다.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

사용자 인증 정보 구성 다운로드 또는 만들기

Cloud 클라이언트 라이브러리 및 gcloud CLI는 외부 사용자 인증 정보를 자동으로 가져오고 이러한 사용자 인증 정보를 사용하여 서비스 계정을 가장할 수 있습니다. 라이브러리 및 도구가 이 프로세스를 완료하도록 하려면 사용자 인증 정보 구성 파일을 제공해야 합니다. 이 파일은 다음을 정의합니다.

• 외부 사용자 인증 정보를 가져올 위치
• 사용할 워크로드 아이덴티티 풀 및 공급업체
• 가장할 서비스 계정

또한 X.509 인증서 제휴의 경우 인증서 구성 파일이 필요합니다. 이 파일에는 X.509 클라이언트 인증서 및 비공개 키 파일에 대한 경로가 포함되어 있습니다.

사용자 인증 정보 및 인증서 구성 파일을 만들려면 다음을 수행합니다.

gcloud iam workload-identity-pools create-cred-config
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

사용자 인증 정보 구성을 사용하여 Google Cloud에 액세스

도구 및 클라이언트 라이브러리가 사용자 인증 정보 구성을 사용하도록 하려면 다음을 수행합니다.

1. 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 초기화하고 사용자 인증 정보 구성 파일을 가리키도록 합니다.

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   여기서 FILEPATH는 사용자 인증 정보 구성 파일의 상대 경로입니다.

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   여기서 FILEPATH는 사용자 인증 정보 구성 파일의 상대 경로입니다.

2. 클라이언트 라이브러리가 인증서 구성 파일을 찾을 수 있는지 확인합니다. 인증서 구성 파일은 다음 중 하나의 기본 Google Cloud CLI 위치에 저장되어야 합니다.

   • Linux 및 macOS: ~/.config/gcloud/certificate_config.json

   • Windows: %APPDATA%\gcloud\certificate_config.json

   또는 GOOGLE_API_CERTIFICATE_CONFIG 환경 변수로 지정해야 합니다.

3. 워크로드 아이덴티티 제휴를 지원하고 사용자 인증 정보를 자동으로 찾을 수 있는 클라이언트 라이브러리 또는 도구를 사용합니다.

  go list -m cloud.google.com/go/auth
  go list -m cloud.google.com/api

  pip show google-auth

  gcloud auth login --cred-file=FILEPATH.json
  

Google Cloud에 액세스하기 위해 일반 요청을 사용하여 액세스 토큰 가져오기

액세스 토큰을 가져오려면 다음을 수행합니다.

1. curl을 사용하여 mTLS 및 클라이언트 인증서로 토큰 교환을 수행합니다.

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.googleapis.com/v1/token' \
   --header "Content-Type: application/json" \
   --data-raw '{
       "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "audience": "WORKLOAD_IDENTITY_POOL_URI",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "https://www.googleapis.com/auth/cloud-platform",
   }'
   

   다음을 바꿉니다.

   • CLIENT_CERT_KEY: 클라이언트 인증서 비공개 키입니다.
   • CLIENT_CERT: 클라이언트 인증서입니다.

   • WORKLOAD_IDENTITY_POOL_URI: 다음 형식의 워크로드 아이덴티티 풀 공급업체의 URL입니다.

     //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

2. 이전 단계에서 생성한 Bearer 액세스 토큰을 사용해서 Google Cloud 리소스에 액세스합니다. 예를 들면 다음과 같습니다.

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

할당량 및 한도

다음 표는 할당량 및 한도를 보여줍니다.

다음 단계

• 워크로드 아이덴티티 제휴 자세히 알아보기
• 워크로드 아이덴티티 제휴 사용 권장사항 알아보기
• 워크로드 아이덴티티 풀 및 공급업체 관리 방법 알아보기