GitHub와 워크로드 아이덴티티 페더레이션

GitHub와 워크로드 아이덴티티 페더레이션 (Federate workload identity with GitHub)

GitHub Actions Workflow에서 GitHub OIDC 토큰을 사용해 인증하도록 워크로드 아이덴티티 페더레이션을 설정하는 방법을 설명해 드릴게요. 인증된 워크로드는 HCP 서비스 주체 키를 전혀 저장하지 않고 HCP 서비스와 상호작용할 수 있어요.

출처: 문서

본문

사전 요구 사항

GitHub용 워크로드 아이덴티티 제공자를 구성하기 전에 다음 단계를 완료해야 해요.

• HCP 프로젝트에 대한 Admin 역할이 있어야 해요.
• 원하는 프로젝트에 서비스 주체를 만들고 워크로드가 필요로 하는 HCP 리소스에 대한 접근 권한을 부여해요.
• HCP로의 접근을 페더레이션할 GitHub Workflow에 대한 접근 권한이 있어야 해요.
• 원하는 구성 워크플로에 따라 HCP CLI를 설치하거나 HCP Terraform Provider를 사용해요.

GitHub용 외부 워크로드 아이덴티티 제공자 구성

GitHub Actions용 HCP 워크로드 아이덴티티 제공자를 만들려면 조건부 접근 문이 필요해요.

조건부 접근 문 (Conditional access statement)

워크로드 아이덴티티를 페더레이션할 때 요구 사항 중 하나가 조건부 접근 문이에요. 이 문은 아이덴티티 클레임에 접근할 수 있고 어떤 외부 아이덴티티가 허용되는지 제한하는 불리언 표현식이에요.

GitHub OIDC 토큰을 HCP 접근 권한으로 교환할 때, 조건부 접근 문은 jwt_claims. 접두어로 토큰의 모든 클레임에 접근할 수 있어요. 자세한 내용은 GitHub 문서의 OIDC 토큰 클레임 레퍼런스를 참고하세요.

다음 예시 조건부 접근 문은 acme-org/acme-repo GitHub 리포지토리에서 시작된 GitHub Actions에 대해서만 HCP 서비스 접근을 제한해요.

`jwt_claims.repository == "acme-org/acme-repo"`

더 제한하여 Git main 브랜치의 요청만 인증되도록 하려면 추가 선택자와 값을 더할 수 있어요.

`jwt_claims.repository == "acme-org/acme-repo" and jwt_claims.ref == "refs/heads/main"`

선택자와 값을 사용해 복합 조건부 접근 문을 만드는 방법에 대한 자세한 내용은 conditional access statements 문서를 참고하세요.

워크로드 아이덴티티 제공자 만들기

필요한 정보를 정리한 뒤 GitHub용 워크로드 아이덴티티 제공자를 만들어요.

HCP CLI / Terraform

hcp iam workload-identity-providers create-oidc 명령을 사용해요.

$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
  --service-principal=<SP_RESOURCE_NAME> \
  --issuer=https://token.actions.githubusercontent.com \
  --conditional-access='<CONDITION>' \
  --description=<DESCRIPTION>

이 명령에는 HCP와 GitHub 계정에 특정한 다음 정보가 필요해요.

• <PROVIDER_NAME>: 만들 워크로드 아이덴티티 제공자의 이름.
• <SP_RESOURCE_NAME>: iam/project/<PROJECT_ID>/service-principal/<NAME> 형식의 서비스 주체 리소스 이름.
• <CONDITION>: 지정된 GitHub 리포지토리와 브랜치에 대한 접근을 제한하는 조건부 접근 문.
• <DESCRIPTION>: 프로바이더에 대한 선택적인 설명.

다음 예시는 github-example이라는 워크로드 아이덴티티 제공자를 만들어요. 이 제공자는 JWT 토큰이 acme-org/acme-repo 리포지토리의 main 브랜치에서 시작된 액션임을 식별하도록 요구해 GitHub Actions 접근만 제한하도록 HCP를 구성해요. HCP 서비스에 대한 접근 권한을 부여받은 워크로드는 my-app-deployer 서비스 주체를 사용해요.

$ hcp iam workload-identity-providers create-oidc github-example \
  --service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-deployer \
  --issuer=https://token.actions.githubusercontent.com \
  --conditional-access='jwt_claims.repository == "acme-org/acme-repo" and jwt_claims.ref == "refs/heads/main"' \
  --description="Allow acme-repo deploy workflow to access my-app-deployer service principal"

hcp_iam_workload_identity_provider 리소스를 사용해요.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "deployment_sp" {
  name = "my-app-deployer"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "github-example"
  service_principal = hcp_service_principal.deployment_sp.resource_name
  description       = "Allow acme-repo deploy workflow to access my-app-runtime service principal"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }

  conditional_access = "<CONDITION>"
}

이 구성에는 GitHub 계정에 특정한 다음 정보가 필요해요.

• <CONDITION>: 지정된 리포지토리와 브랜치에 대한 접근을 제한하는 조건부 접근 문.

다음 예시는 github-example이라는 워크로드 아이덴티티 제공자를 만들어요. 이 제공자는 JWT 토큰이 acme-org/acme-repo 리포지토리의 main 브랜치에서 시작된 액션임을 식별하도록 요구해 GitHub Actions 접근만 제한하도록 HCP를 구성해요. HCP 서비스에 대한 접근 권한을 부여받은 워크로드는 my-app-deployer 서비스 주체를 사용해요.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "deployment_sp" {
  name = "my-app-deployer"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "github-example"
  service_principal = hcp_service_principal.deployment_sp.resource_name
  description       = "Allow acme-repo deploy workflow to access my-app-deployer service principal"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }

  conditional_access = "jwt_claims.repository == `acme-org/acme-repo` and jwt_claims.ref == `refs/heads/main`"
}

GitHub Actions 워크플로 구성

hashicorp/hcp-auth-action GitHub Action은 워크플로 실행 중에 자격 증명 파일을 자동으로 생성해요. HCP CLI를 사용해 외부 자격 증명을 자동으로 가져와 HCP 액세스 토큰으로 교환할 수 있어요.

GitHub Actions YAML 파일에 다음 구성을 추가해요.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
      - id: 'Authenticate to HCP'
      - uses: 'hashicorp/hcp-auth-action@v0'
        with:
          workload_identity_provider: <PROVIDER_NAME>

이 명령에는 HCP 계정에 특정한 다음 정보가 필요해요.

• <PROVIDER_NAME>: iam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME> 형식으로 자격 증명을 교환할 워크로드 아이덴티티 제공자의 이름.

GitHub Actions 워크플로에서 사용할 수 있는 명령에 대한 자세한 내용은 HCP CLI 명령 레퍼런스를 참고하세요.

더 알아보기 (Learn more)

• 워크로드 아이덴티티 페더레이션 — 워크로드 아이덴티티 페더레이션의 개요와 동작 방식을 확인해 보세요.
• 조건부 접근 문 — 조건부 접근 문을 작성하고 형식화하는 방법을 알아보세요.
• 기타 OIDC 제공자 구성 — 커스텀 OIDC IdP를 연결하는 방법을 확인해 보세요.
• GitLab 제공자 구성 — GitLab CI/CD 워크로드를 연결하는 방법을 알아보세요.