HashiCorp Vault에서 OpenID Connect 구성하기

HashiCorp Vault에서 OpenID Connect 구성하기

워크플로우에서 OpenID Connect를 사용해 HashiCorp Vault에 인증해보세요.

출처: 문서

본문

워크플로우에서 OpenID Connect를 사용해 HashiCorp Vault에 인증해 시크릿을 검색할 수 있어요.

개요

OpenID Connect(OIDC)를 사용하면 GitHub Actions 워크플로우가 HashiCorp Vault에 인증해 시크릿을 검색할 수 있어요.

이 가이드는 HashiCorp Vault가 GitHub의 OIDC를 페더레이션 ID로 신뢰하도록 구성하는 방법의 개요를 제공하고, hashicorp/vault-action 액션에서 이 구성을 사용해 HashiCorp Vault에서 시크릿을 검색하는 방법을 보여줍니다.

사전 요구 사항

  • GitHub가 OpenID Connect(OIDC)를 사용하는 방법, 그 아키텍처와 이점에 대한 기본 개념을 배우려면 OpenID Connect를 참고하세요.

  • 진행하기 전에 보안 전략을 계획해 접근 토큰이 예측 가능한 방식으로만 할당되도록 해야 해요. 클라우드 공급자가 접근 토큰을 발급하는 방식을 제어하려면 신뢰할 수 없는 저장소가 클라우드 리소스에 대한 접근 토큰을 요청할 수 없도록 반드시 최소 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 OpenID Connect reference를 참고하세요.

  • Dependabot 업데이트 작업을 위해 요청된 OIDC 토큰은 event_name 클레임이 dynamic입니다. 신뢰 정책이 GitHub Actions 워크플로우만 승인하도록 의도되었고 클라우드 공급자가 event_name에 대한 조건을 지원한다면, 워크플로우가 기대하는 이벤트 이름만 허용하세요. 자세한 내용은 OpenID Connect reference를 참고하세요.

HashiCorp Vault에 ID 공급자 추가하기

HashiCorp Vault와 함께 OIDC를 사용하려면 GitHub OIDC 공급자에 대한 신뢰 구성을 추가해야 해요. 자세한 내용은 HashiCorp Vault documentation을 참고하세요.

Vault 서버가 인증을 위해 JSON Web Token(JWT)을 수락하도록 구성하려면:

  1. JWT auth 메서드를 활성화하고 write를 사용해 구성을 Vault에 적용하세요. oidc_discovery_url와 bound_issuer 매개변수에는 https://token.actions.githubusercontent.com을 사용하세요. 이 매개변수들은 Vault 서버가 인증 과정 중에 받은 JSON Web Token(JWT)을 검증할 수 있게 해줍니다.

    vault auth enable jwt

    vault write auth/jwt/config \
  bound_issuer="https://token.actions.githubusercontent.com" \
  oidc_discovery_url="https://token.actions.githubusercontent.com"

  2. 워크플로우가 시크릿을 검색하는 데 사용할 특정 경로에만 접근을 부여하는 정책을 구성하세요. 더 고급 정책은 HashiCorp Vault Policies documentation을 참고하세요.

    vault policy write myproject-production - <<EOF
# Read-only permission on 'secret/data/production/*' path

path "secret/data/production/*" {
  capabilities = [ "read" ]
}
EOF

  3. 서로 다른 정책을 함께 그룹화하는 역할을 구성하세요. 인증이 성공하면 이 정책들은 결과 Vault 접근 토큰에 첨부됩니다.

    vault write auth/jwt/role/myproject-production -<<EOF
{
  "role_type": "jwt",
  "user_claim": "actor",
  "bound_claims": {
    "repository": "user-or-org-name/repo-name"
  },
  "policies": ["myproject-production"],
  "ttl": "10m"
}
EOF
  • ttl은 결과 접근 토큰의 유효 기간을 정의합니다.
  • 보안 요구 사항을 위해 bound_claims 매개변수가 정의되고 최소 하나의 조건을 갖도록 하세요. 선택적으로 bound_subject와 bound_audiences 매개변수도 설정할 수 있어요.
  • 받은 JWT 페이로드의 임의 클레임을 확인하려면 bound_claims 매개변수에 클레임 집합과 필요한 값이 포함됩니다. 위 예시에서 역할은 user-or-org-name 계정이 소유한 repo-name 저장소의 모든 수신 인증 요청을 수락합니다.
  • GitHub의 OIDC 공급자가 지원하는 모든 사용 가능한 클레임을 보려면 OpenID Connect reference를 참고하세요.

자세한 내용은 HashiCorp Vault documentation을 참고하세요.

GitHub Actions 워크플로우 업데이트하기

워크플로우를 OIDC용으로 업데이트하려면 YAML을 두 가지 변경해야 해요:

  1. 토큰에 대한 권한 설정을 추가하세요.
  2. hashicorp/vault-action 액션을 사용해 OIDC 토큰(JWT)을 클라우드 접근 토큰으로 교환하세요.

[!NOTE] 워크플로우나 OIDC 정책에서 환경을 사용할 때는 추가 보안을 위해 환경에 보호 규칙을 추가하는 것을 권장합니다. 예를 들어 환경에 배포 규칙을 구성해 어떤 브랜치와 태그가 환경에 배포하거나 환경 시크릿에 접근할 수 있는지 제한할 수 있어요. 자세한 내용은 Managing environments for deployment를 참고하세요.

워크플로우가 Vault의 시크릿에 접근할 수 있도록 OIDC 통합을 추가하려면 다음 코드 변경을 추가해야 해요:

  • GitHub OIDC 공급자에서 토큰을 가져올 권한을 부여하세요:
    • 워크플로우는 id-token 값이 write로 설정된 permissions: 설정이 필요합니다. 이렇게 하면 워크플로우의 모든 작업에서 OIDC 토큰을 가져올 수 있어요.
  • GitHub OIDC 공급자에서 JWT를 요청하고 HashiCorp Vault에 제시해 접근 토큰을 받으세요:

이 예시는 공식 액션과 함께 OIDC를 사용해 HashiCorp Vault에서 시크릿을 요청하는 방법을 보여줍니다.

권한 설정 추가하기

작업 또는 워크플로우 실행에는 GitHub의 OIDC 공급자가 매 실행마다 JSON Web Token을 만들 수 있도록 id-token: write가 있는 permissions 설정이 필요합니다.

[!NOTE] 워크플로우의 권한에 id-token: write를 설정해도 워크플로우가 리소스를 수정하거나 쓰기 권한을 얻는 것은 아닙니다. 대신 액션이나 단계를 위해 OIDC 토큰을 요청(가져오기)하고 사용(설정)할 수만 있게 해줍니다. 이 토큰은 이후 단기 접근 토큰으로 외부 서비스에 인증하는 데 사용됩니다.

필요한 권한, 구성 예시, 고급 시나리오에 대한 자세한 정보는 OpenID Connect reference를 참고하세요.

[!NOTE] permissions 키를 사용하면 metadata 스코프를 제외한 모든 지정되지 않은 권한이 no access로 설정됩니다(metadata 스코프는 항상 read 접근을 받습니다). 그 결과 contents: read와 같은 다른 권한을 추가해야 할 수 있어요. 자세한 내용은 Automatic token authentication을 참고하세요.

접근 토큰 요청하기

hashicorp/vault-action 액션은 GitHub OIDC 공급자로부터 JWT를 받은 다음 HashiCorp Vault 인스턴스에 접근 토큰을 요청해 시크릿을 검색합니다. 자세한 내용은 HashiCorp Vault GitHub Action documentation을 참고하세요.

이 예시는 HashiCorp Vault에서 시크릿을 요청하는 작업을 만드는 방법을 보여줍니다.

  • VAULT-URL: HashiCorp Vault의 URL로 바꾸세요.
  • VAULT-NAMESPACE: HashiCorp Vault에서 설정한 Namespace로 바꾸세요. 예: admin.
  • ROLE-NAME: HashiCorp Vault 신뢰 관계에서 설정한 역할로 바꾸세요.
  • SECRET-PATH: HashiCorp Vault에서 검색하는 시크릿의 경로로 바꾸세요. 예: secret/data/production/ci npmToken.
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        with:
          method: jwt
          url: VAULT-URL
          namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only
          role: ROLE-NAME
          secrets: SECRET-PATH

      - name: Use secret from Vault
        run: |
          # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.

[!NOTE]

  • Vault 서버가 공개 네트워크에서 접근할 수 없다면, 사용 가능한 다른 Vault auth methods와 함께 셀프 호스팅 러너 사용을 고려하세요. 자세한 내용은 Self-hosted runners를 참고하세요.
  • Vault Enterprise(HCP Vault 포함) 배포에는 VAULT-NAMESPACE가 설정되어야 합니다. 자세한 내용은 Vault namespace를 참고하세요.

접근 토큰 취소하기

기본적으로 Vault 서버는 TTL이 만료되면 접근 토큰을 자동으로 취소하므로 수동으로 취소할 필요가 없어요. 하지만 작업이 완료되거나 실패한 직후에 접근 토큰을 취소하고 싶다면 Vault API를 사용해 발급된 토큰을 수동으로 취소할 수 있습니다.

  1. exportToken 옵션을 true(기본값: false)로 설정하세요. 이렇게 하면 발급된 Vault 접근 토큰이 VAULT_TOKEN 환경 변수로 내보내집니다.
  2. Revoke a Token (Self) Vault API를 호출해 접근 토큰을 취소하는 단계를 추가하세요.
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        with:
          exportToken: true
          method: jwt
          url: VAULT-URL
          role: ROLE-NAME
          secrets: SECRET-PATH

      - name: Use secret from Vault
        run: |
          # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.

      - name: Revoke token
        # This step always runs at the end regardless of the previous steps result
        if: always()
        run: |
          curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \
            VAULT-URL/v1/auth/token/revoke-self

더 알아보기 (Learn more)