Teleport 워크로드 아이덴티티는 JWT 형식으로 유연한 단기 아이덴티티를 발급합니다. GCP 워크로드 아이덴티티 Federation을 사용하면 이러한 JWT를 사용해 GCP 서비스에 인증할 수 있습니다.

이는 머신이 장기 자격 증명을 사용하지 않고 GCP 서비스에 안전하게 인증해야 하는 경우에 유용합니다. 머신이 위임된 조인 방법 중 하나를 사용하여 공유 시크릿 없이 Teleport에 인증할 수 있기 때문입니다.

이 가이드에서는 Teleport 워크로드 아이덴티티와 GCP를 구성하여 워크로드가 GCP Cloud Storage API에 인증하고 버킷에 콘텐츠를 업로드할 수 있도록 합니다.

작동 방식#

이 구현은 Teleport Application Service를 사용하여 GCP API를 보호하는 것과 몇 가지 다른 점이 있습니다:

• GCP에 대한 요청은 Teleport Proxy Service를 통해 프록시되지 않으므로 지연 시간은 줄어들지만 가시성도 낮아집니다. 이러한 요청은 Teleport의 감사 로그에 기록되지 않기 때문입니다.
• 워크로드 아이덴티티는 명령줄 도구는 물론 SDK를 포함한 모든 GCP 클라이언트와 함께 작동합니다.
• Teleport Application Service를 사용하여 GCP에 접근하는 방식은 Machine & Workload Identity와 함께 작동하지 않으므로 머신이 GCP에 인증해야 하는 경우에는 사용할 수 없습니다.

사전 요구 사항#

• 실행 중인 Teleport 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

• tctl and tsh clients.

  Installing `tctl` and `tsh` clients

  1. Teleport 클러스터의 버전을 확인합니다. tctl and tsh clients는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     

  2. 사용 중인 플랫폼에 대한 지침에 따라 tctl and tsh clients를 설치합니다:

Mac

     `tctl` and `tsh` clients가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     

       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     # NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 `tctl` and `tsh` clients가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 

Teleport cluster에 연결할 수 있는지 확인하려면 tsh login으로 로그인한 다음, 현재 자격 증명으로 tctl 명령을 실행할 수 있는지 확인합니다.

예를 들어, teleport.example.com에 cluster 내 Teleport Proxy Service의 도메인 이름을, email@example.com에 Teleport 사용자 이름을 지정하여 다음 명령을 실행합니다:

$ tsh login --proxy=teleport.example.com --user=email@example.com
$ tctl status
# Cluster  (=teleport.url=)
# Version  (=teleport.version=)
# CA pin   (=presets.ca_pin=)

cluster에 연결하여 tctl status 명령을 실행할 수 있다면, 현재 자격 증명을 사용하여 워크스테이션에서 이후의 tctl 명령을 실행할 수 있습니다. 자체 Teleport cluster를 호스팅하는 경우, 전체 권한을 얻기 위해 Teleport Auth Service를 호스팅하는 컴퓨터에서 tctl 명령을 실행할 수도 있습니다.

• tbot은 Teleport 워크로드 아이덴티티에 접근해야 하는 워크로드가 실행되는 호스트에 이미 설치 및 구성되어 있어야 합니다. 자세한 내용은 배포 가이드를 참조하세요.

SPIFFE ID 구조 결정#

Teleport 워크로드 아이덴티티 내에서 모든 아이덴티티는 SPIFFE ID를 사용하여 표현됩니다. 이는 아이덴티티가 나타내는 엔티티를 고유하게 식별하는 URI입니다. 스키마는 항상 spiffe://이며, 호스트는 Teleport 클러스터의 이름이 됩니다. 이 URI 경로의 구조는 사용자가 원하는 대로 정할 수 있습니다.

이 가이드에서는 spiffe://example.teleport.sh/svc/example-service SPIFFE ID에 GCP 접근 권한을 부여합니다.

이미 Teleport 워크로드 아이덴티티를 배포했다면 SPIFFE ID 구조가 이미 마련되어 있을 것입니다. 아직 배포하지 않았다면 SPIFFE ID의 구조를 결정해야 합니다.

GCP 워크로드 아이덴티티 Federation과 함께 Teleport 워크로드 아이덴티티만 사용하는 경우, SPIFFE ID가 가정할 수 있는 GCP 서비스 계정을 명시적으로 지정하도록 구조화할 수 있습니다. 하지만 SPIFFE ID를 사용할 워크로드나 사람의 이름을 지정하는 편이 더 합리적인 경우가 많습니다. 자세한 조언은 모범 사례 가이드를 참조하세요.

1/4단계. GCP 구성#

GCP 워크로드 아이덴티티 Federation을 처음 구성할 때는 몇 가지 단계를 거쳐야 합니다. 이전에 Teleport 클러스터에 대해 GCP 워크로드 아이덴티티 Federation을 구성한 적이 있다면 일부 단계는 필요하지 않을 수 있습니다.

워크로드 아이덴티티 풀 및 OIDC 공급자 생성#

먼저 GCP에서 워크로드 아이덴티티 풀과 이 풀 내의 OIDC 공급자를 생성해야 합니다. 워크로드 아이덴티티 풀은 외부 워크로드 아이덴티티가 GCP 내에서 어떻게 표현되는지를 관리하는 엔티티입니다.

공급자는 외부 아이덴티티가 풀에 인증하는 방법을 구성합니다. Teleport 워크로드 아이덴티티는 OIDC 호환 JWT-SVID를 발급하므로 OIDC 공급자 유형을 사용합니다.

풀을 구성할 때는 풀을 식별할 이름을 선택해야 합니다. 이 이름은 워크로드 아이덴티티의 출처를 고유하게 식별해야 합니다. Teleport 클러스터의 이름을 따서 명명하는 것이 합리적일 수 있습니다. 이 예제에서는 workload-id-pool이라는 이름을 사용합니다.

공급자를 구성할 때는 발급자(issuer) URI를 지정해야 합니다. 이는 Teleport Proxy Service의 공개 주소에 /workload-identity 경로를 추가한 값이 됩니다. OIDC federation이 작동하려면 GCP에서 Teleport Proxy Service에 접근할 수 있어야 합니다.

또한 "속성 매핑(attribute mapping)"도 지정해야 합니다. 이는 GCP가 JWT 내의 아이덴티티를 GCP의 주체(principal)에 매핑하는 방법을 결정합니다. 여기서는 SVID를 사용하므로 JWT 내의 sub 클레임을 google.subject 속성에 매핑하여, 워크로드의 SPIFFE ID를 사용해 GCP에서 권한 부여 결정을 내릴 수 있도록 합니다.

data "google_project" "project" {}

resource "google_iam_workload_identity_pool" "workload_identity" {
    workload_identity_pool_id = "workload-id-pool"
}

resource "google_iam_workload_identity_pool_provider" "workload_identity_oidc" {
    workload_identity_pool_id          = google_iam_workload_identity_pool.workload_identity.workload_identity_pool_id
    workload_identity_pool_provider_id = "workload-id-oidc"
    attribute_mapping                  = {
        // Maps the `sub` claim within the JWT to the `google.subject` attribute.
        // This will allow it to be used to make Authz decisions in GCP.
        "google.subject" = "assertion.sub"
    }
    oidc {
        // Replace example.teleport.sh with the hostname of your Proxy Service's
        // public address.
        issuer_uri        = "https://example.teleport.sh/workload-identity"
    }
}

# Replace "workload-id-pool" with a meaningful, unique name.
$ gcloud iam workload-identity-pools create workload-id-pool \
    --location="global"

# Replace "workload-id-pool" with the name of the pool you just created and
# "workload-id-oidc" with a meaningful, unique name.
# Replace example.teleport.sh with the hostname of your Proxy Service's 
# public address for issuer-uri. 
# The `attribute-mapping` maps the `sub` claim within the JWT to the `google.subject` attribute.
# This will allow it to be used to make Authz decisions in GCP.

$ gcloud iam workload-identity-pools providers create-oidc workload-id-oidc \
    --location="global" \
    --workload-identity-pool="workload-id-pool" \
    --issuer-uri="https://example.teleport.sh/workload-identity" \
    --attribute-mapping="google.subject=assertion.sub"

저장소 버킷 및 RBAC 생성#

이 가이드에서는 워크로드에 GCP 저장소 버킷 접근 권한을 부여합니다. 원하는 다른 GCP 서비스에 접근 권한을 부여하도록 이 단계를 대체할 수 있습니다.

워크로드가 서비스 계정을 가정하지 않고도 리소스에 직접 접근할 수 있도록 워크로드 아이덴티티에 권한을 부여합니다.

이를 위해 이미 구성한 속성 매핑을 기반으로 워크로드 아이덴티티 페더레이션 풀이 생성하는 주체 (principal)를 사용합니다. 이 주체는 IAM 정책에서 직접 사용하여 워크로드 아이덴티티에 권한을 부여할 수 있습니다. 주체에는 GCP 프로젝트 번호, 워크로드 아이덴티티 풀의 이름, SPIFFE ID가 포함됩니다. 형식은 다음과 같습니다:

principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_NAME/subject/$SPIFFE_ID

워크로드가 서비스 계정을 가정할 수 있도록 권한을 부여하는 것도 가능합니다. 이 가이드에서는 다루지 않지만, 이미 필요한 권한으로 서비스 계정이 생성되어 있고 장기 공유 시크릿을 사용하지 않고 워크로드가 이를 사용할 수 있도록 허용하려는 시나리오에서 유용할 수 있습니다.

resource "google_storage_bucket" "demo" {
    // Replace with a meaningful, unique name.
    name          = "example"
    location      = "EU"
    force_destroy = true

    uniform_bucket_level_access = true
}

locals {
    // Replace with the SPIFFE ID of the workload that will access the bucket.
    allow_spiffe_id = "spiffe://example.teleport.sh/svc/example-service"
}

resource "google_storage_bucket_iam_binding" "binding" {
    bucket = google_storage_bucket.demo.name
    role = "roles/storage.admin"
    members = [
        "principal://iam.googleapis.com/projects/${data.google_project.project.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.leaf_cluster.workload_identity_pool_id}/subject/${local.allow_spiffe_id}",
    ]
}

# Replace "example" with a meaningful, unique name.
$ gcloud storage buckets create gs://example \
    --location=EU \
    --uniform-bucket-level-access

$ ROLE="roles/storage.admin"
# Replace PROJECT_NUMBER with your GCP project number.
$ PROJECT_NUMBER="123456789000"
# Replace POOL_ID with the ID of the Workload Identity Pool you created.
$ POOL_ID="workload-id-pool"
# Replace SPIFFE_ID with the SPIFFE ID of the workload that will access the bucket.
$ SPIFFE_ID="spiffe://example.teleport.sh/svc/example-service"
$ MEMBER="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${SPIFFE_ID}"
$ gcloud storage buckets add-iam-policy-binding gs://example --member=$MEMBER --role=$ROLE

2/4단계. Teleport RBAC 구성#

이제 선택한 SPIFFE ID를 포함하는 JWT를 발급할 수 있도록 Teleport를 구성해야 합니다.

먼저 아이덴티티와 그 특성을 정의하는 워크로드 아이덴티티 리소스를 생성합니다. workload-identity.yaml 이라는 새 파일을 만듭니다:

kind: workload_identity
version: v1
metadata:
  name: example-workload-identity
  labels:
    example: getting-started
spec:
  spiffe:
    id: /svc/example-service

tctl을 사용하여 클러스터에 이를 적용합니다:

$ tctl create -f workload-identity.yaml

다음으로 이 워크로드 아이덴티티에 대한 접근 권한을 부여하는 역할을 생성합니다. 다음 내용으로 role.yaml을 만듭니다:

kind: role
version: v6
metadata:
  name: example-workload-identity-issuer
spec:
  allow:
    workload_identity_labels:
      example: ["getting-started"]
    rules:
    - resources:
      - workload_identity
      verbs:
      - list
      - read

교체:

• example-workload-identity-issuer를 역할에 대한 설명적인 이름으로 바꿉니다.
• 워크로드 아이덴티티의 레이블을 수정한 경우 레이블 선택기를 바꿉니다.

tctl을 사용하여 이 역할을 Teleport 클러스터에 적용합니다:

$ tctl create -f role.yaml

이제 이 역할을 봇에 할당해야 합니다:

$ tctl bots update my-bot --add-roles example-workload-identity-issuer

3/4단계. 워크로드 아이덴티티 JWT 발급#

이제 워크로드를 위한 단기 JWT SVID를 발급하고 갱신하도록 tbot을 구성합니다. tbot은 JWT를 디스크의 파일로 기록하며, GCP 클라이언트와 SDK가 이를 읽도록 구성할 수 있습니다.

이를 구성하기 전에 JWT SVID에서 요청할 올바른 대상(audience)을 결정해야 합니다. 이는 방금 생성한 워크로드 아이덴티티 Federation 구성에 특정하며 세 가지 구성 요소를 포함합니다:

• GCP 프로젝트의 프로젝트 번호
• GCP에서 구성한 워크로드 아이덴티티 Federation 풀의 이름
• GCP에서 구성한 워크로드 아이덴티티 Federation 공급자의 이름

형식은 다음과 같습니다: https://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_NAME/providers/$PROVIDER_NAME.

이미 배포한 tbot 서비스를 가져와 다음 내용을 tbot 구성 파일에 추가하여 SPIFFE SVID를 발급하도록 구성합니다:

services:
  - type: workload-identity-jwt
    destination:
      type: directory
      path: /opt/workload-identity
    selector:
      name: example-workload-identity
    audiences: ["https://iam.googleapis.com/projects/123456789000/locations/global/workloadIdentityPools/workload-id-pool/providers/workload-id-oidc"]

교체:

• 123456789000을 GCP 프로젝트 번호로 바꿉니다.
• workload-id-pool을 워크로드 아이덴티티 Federation 풀의 이름으로 바꿉니다.
• workload-id-oidc를 워크로드 아이덴티티 Federation 공급자의 이름으로 바꿉니다.
• example-workload-identity를 생성한 워크로드 아이덴티티의 이름으로 바꿉니다.

/opt/workload-identity/jwt_svid에 JWT를 포함하는 파일이 생성된 것을 볼 수 있습니다.

4/4단계. GCP CLI 및 SDK 구성#

마지막으로 GCP CLI와 SDK가 워크로드 아이덴티티를 사용하여 인증하도록 구성하는 구성 파일을 생성해야 합니다. 이 구성 파일은 tbot이 기록하는 JWT 파일의 경로를 지정하고, 사용할 워크로드 아이덴티티 Federation 풀과 공급자를 지정합니다.

gcloud CLI를 사용하여 이 구성 파일을 생성할 수 있습니다:

$ gcloud iam workload-identity-pools create-cred-config \
    projects/123456789000/locations/global/workloadIdentityPools/workload-id-pool/providers/workload-id-oidc \
    --output-file=gcp-workload-identity.json \
    --credential-source-file=/opt/workload-identity/jwt_svid \
    --credential-source-type=text

교체:

• 123456789000을 GCP 프로젝트 번호로 바꿉니다.
• workload-id-pool을 워크로드 아이덴티티 Federation 풀의 이름으로 바꿉니다.
• workload-id-oidc를 워크로드 아이덴티티 Federation 공급자의 이름으로 바꿉니다.
• /opt/workload-identity/jwt_svid를 tbot이 기록하는 JWT 파일의 경로로 바꿉니다.

이 명령을 실행하면 현재 디렉터리에 gcp-workload-identity.json이라는 파일이 생성됩니다.

gcloud CLI#

워크로드 아이덴티티를 사용하여 인증하도록 gcloud CLI를 구성하려면, gcloud auth login 명령을 사용하고 방금 생성한 구성 파일의 경로를 지정합니다:

$ gcloud auth login --cred-file gcp-workload-identity.json

이제 GCP Storage API에 대한 인증을 테스트할 수 있습니다. 버킷에 업로드할 파일을 만듭니다:

$ echo "Hello, World!" > hello.txt

이제 gcloud CLI를 사용하여 이 파일을 버킷에 업로드합니다:

$ gcloud storage cp hello.txt gs://example

모든 것이 올바르게 구성되었다면 이 파일이 버킷에 업로드된 것을 볼 수 있습니다. GCP의 감사 로그를 확인하면 요청이 워크로드 아이덴티티를 사용하여 인증되었으며, 요청을 보낸 워크로드의 SPIFFE ID가 명시되어 있음을 확인할 수 있습니다.

GCP SDK#

GCP SDK가 워크로드 아이덴티티를 사용하여 인증하도록 구성하려면, GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 방금 생성한 구성 파일의 경로로 설정해야 합니다:

$ export GOOGLE_APPLICATION_CREDENTIALS=gcp-workload-identity.json

다음 단계#

• GCP 워크로드 아이덴티티 Federation 문서: 워크로드 아이덴티티 Federation에 대한 공식 GCP 문서입니다.
• 워크로드 아이덴티티 개요: Teleport 워크로드 아이덴티티에 대한 개요입니다.
• JWT SVID 개요: Teleport 워크로드 아이덴티티가 발급하는 JWT SVID에 대한 개요입니다.
• 모범 사례: 프로덕션 환경에서 워크로드 아이덴티티를 사용하기 위한 모범 사례입니다.
• 사용 가능한 모든 구성 옵션을 살펴보려면 구성 참조를 읽어보세요.