튜토리얼: HashiCorp Vault 구성 업데이트하여 ID 토큰 사용

Tier: 프리미엄, 얼티밋 Offering: GitLab.com, 자체 관리, 전용 GitLab

참고: Vault 1.17부터 JWT 인증 로그인은 롤의 바운드 수신자를 필요로 합니다(영문). JWT에 aud 클레임이 포함되어 있는 경우 aud 클레임이 단일 문자열이거나 문자열 목록일 수 있습니다.

이 튜토리얼은 기존 CI/CD 비밀 구성을 ID 토큰(영문)을 사용하도록 변경하는 방법을 보여줍니다.

CI_JOB_JWT 변수는 사용되지 않으나 ID 토큰으로 업데이트하려면 Vault와 작업하기 위한 중요한 구성 변경이 필요합니다. 수십 개 이상의 작업이 있는 경우, 한꺼번에 모두 변환하는 것은 어려운 과제입니다.

ID 토큰(영문)으로의 이전에는 하나의 표준적인 방법이 없기 때문에, 이 튜토리얼에는 기존 CI/CD 비밀을 변환하는 두 가지 변형이 포함되어 있습니다. 사용 사례에 맞는 방법을 선택하세요:

  1. Vault 구성 업데이트:
  2. CI/CD 작업 업데이트

전제 조건

본 튜토리얼은 GitLab CI/CD 및 Vault에 익숙하다고 가정합니다.

따라오려면 다음이 필요합니다:

  • GitLab 16.0 이상이 실행 중인 인스턴스 또는 GitLab.com에 있어야 합니다.
  • 이미 사용 중인 Vault 서버.
  • CI_JOB_JWT로부터 비밀을 검색하는 CI/CD 작업.

아래 예시에서 다음을 대체하세요:

  • vault.example.com은 Vault 서버의 URL로 대체합니다.
  • gitlab.example.com은 GitLab 인스턴스의 URL로 대체합니다.
  • jwt 또는 jwt_v2는 인증 방법 이름으로 대체합니다.

방법 A: 기존 Vault 인증 방법에서 JWT 롤을 새로운 Vault 인증 방법으로 이동

이 방법은 사용 중인 기존 방법과 병렬로 두 번째 JWT 인증 방법을 생성합니다. 그 후 GitLab 통합용으로 사용된 모든 Vault 롤은 새로운 인증 방법에서 다시 생성됩니다.

Vault에 두 번째 JWT 인증 경로 생성

CI_JOB_JWT에서 ID 토큰으로의 전환 일환으로 Vault의 bound_issuer를 https://를 포함하여 업데이트해야합니다: 

$ vault write auth/jwt/config \
    oidc_discovery_url="https://gitlab.example.com" \
    bound_issuer="https://gitlab.example.com"

이 변경을 수행하면 CI_JOB_JWT를 사용하는 작업이 실패합니다.

Vault에는 여러 개의 인증 경로를 생성할 수 있으며, 이를 통해 프로젝트별로 작업 단위로 ID 토큰으로 전환할 수 있습니다.

  1. jwt_v2라는 이름으로 새 인증 경로를 구성하려면 다음을 실행하세요: 

    vault auth enable -path jwt_v2 jwt

    다른 이름을 선택할 수 있지만, 이 예시의 나머지 부분에서는 jwt_v2를 사용했다고 가정하므로 필요에 맞게 예시를 업데이트하세요.

  2. 인스턴스에 대한 새로운 인증 경로를 구성합니다: 

    $ vault write auth/jwt_v2/config \
    oidc_discovery_url="https://gitlab.example.com" \
    bound_issuer="https://gitlab.example.com"

새로운 인증 경로를 사용하도록 롤 다시 만들기

롤은 특정 인증 경로에 바인딩되므로 각 작업을 위해 새로운 롤을 추가해야 합니다. 롤에 대한 bound_audiences 매개변수는 JWT에 audience가 포함되어 있는 경우 필수이며 JWT와 관련된 aud 클레임 중 하나와 일치해야 합니다.

  1. myproject-staging이라는 스테이징용의 롤을 다시 생성합니다: 

    $ vault write auth/jwt_v2/role/myproject-staging - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-staging"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_email",
  "bound_audiences": ["https://vault.example.com"],
  "bound_claims": {
    "project_id": "22",
    "ref": "master",
    "ref_type": "branch"
  }
}
EOF

  2. myproject-production이라는 프로덕션용의 롤을 다시 생성합니다: 

    $ vault write auth/jwt_v2/role/myproject-production - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-production"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_email",
  "bound_audiences": ["https://vault.example.com"],
  "bound_claims_type": "glob",
  "bound_claims": {
    "project_id": "22",
    "ref_protected": "true",
    "ref_type": "branch",
    "ref": "auto-deploy-*"
  }
}
EOF

vault 명령어에서 jwt를 jwt_v2로 변경하고, 역할 내의 role_type을 변경하면 안됩니다.

방법 B: 이관 기간 동안 iss 클레임을 롤로 이동

이 방법은 Vault 관리자가 두 번째 JWT 인증 방법을 생성하고 GitLab 관련 롤을 모두 다시 생성하는 것을 요구하지 않습니다.

각 롤에 bound_issuers 클레임 맵 추가

Vault는 JWT 인증 방법 수준에서 여러 iss 클레임을 허용하지 않습니다. 이 수준에서의 bound_issuer(영문) 지시어는 단일 값만 허용합니다. 그러나 역할 수준에서 bound_claims(영문) 맵 구성 지시어를 사용하여 여러 클레임을 구성할 수 있습니다.

이 방법을 사용하면 iss 클레임 유효성을 위해 Vault에 https:// 접두사 GitLab 인스턴스 호스트명 클레임과 이전 접두사 없는 클레임에 대한 여러 옵션을 제공할 수 있습니다.

필요한 롤에 bound_claims(영문) 구성을 추가하려면 다음을 실행하세요: 

$ vault write auth/jwt/role/myproject-staging - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-staging"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_email",
  "bound_audiences": ["https://vault.example.com"],
  "bound_claims": {
    "iss": [
      "https://gitlab.example.com",
      "gitlab.example.com"
    ],
    "project_id": "22",
    "ref": "master",
    "ref_type": "branch"
  }
}
EOF

기존 역할 구성을 제외하고 bound_claims 섹션에 iss 구성을 위해 위에 표시된대로 수정할 필요가 있습니다. 본 롤에 대해 Vault가 접두사가 있는 클레임 및 접두사 없는 iss 클레임을 수락하도록 보장하려면 위에 설명된대로 구성을 추가하세요.

모든 GitLab 통합에 사용되는 JWT 롤에 이 변경을 적용해야 합니다.

모든 프로젝트가 이전되고 CI_JOB_JWT 및 ID 토큰에 대한 병렬 지원이 더 이상 필요하지 않은 경우, 원하는 경우 인증 방법에서 롤로 iss 클레임 유효성 이관을 되돌릴 수 있습니다.

bound_issuers 클레임을 인증 방법에서 제거

모든 역할이 bound_claims.iss 클레임으로 업데이트된 후에는 이 유효성을 위한 인증 방법 수준의 구성을 제거할 수 있습니다. 

$ vault write auth/jwt/config \
    oidc_discovery_url="https://gitlab.example.com" \
    bound_issuer=""

bound_issuer 지시문을 빈 문자열로 설정하면 인증 방법 수준에서 발행자 유효성을 제거합니다. 그러나 이 유효성을 역할 수준으로 이동했으므로이 구성은 여전히 안전합니다.

CI/CD 작업 업데이트

Vault에는 두 가지 다른 KV Secrets Engines가 있으며 사용 중인 버전에 따라 CI/CD에서 비밀을 정의하는 방법에 영향을줍니다.

Vault 서버를 확인하려면 HashiCorp의 지원 포털에있는 내 Vault KV Mount 버전은 무엇입니까? 문서를 확인하세요.

또한 필요한 경우 CI/CD 문서를 검토할 수 있습니다:

다음 예제에서는 secret/myproject/staging/db의 password 필드에 작성된 스테이징 데이터베이스 비밀번호를 가져오는 방법을 보여줍니다.

VAULT_AUTH_PATH 변수의 값은 사용한 마이그레이션 방법에 따라 다릅니다:

  • 방법 A (JWT 역할을 새 Vault 인증 방법으로 마이그레이션): jwt_v2 사용
  • 방법 B (마이그레이션 창을 위해 iss 클레임을 역할로 이동): jwt 사용

KV Secrets Engine v1

secrets:vault 키워드는 KV Mount의 v2를 기본으로합니다. 따라서 작업을 명시적으로 v1 엔진을 사용하도록 구성해야합니다. 

job:
  variables:
    VAULT_SERVER_URL: https://vault.example.com
    VAULT_AUTH_PATH: jwt_v2  # 또는 "jwt" (B 방법 사용 시)
    VAULT_AUTH_ROLE: myproject-staging
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    PASSWORD:
      vault:
        engine:
          name: kv-v1
          path: secret
        field: password
        path: myproject/staging/db
      file: false

VAULT_SERVER_URL 및 VAULT_AUTH_PATH는 프로젝트 또는 그룹 CI/CD 변수로 정의할 수 있습니다.

기본적으로 secrets:file:false를 사용합니다. ID 토큰은 기본적으로 파일에 비밀을 저장하지만 이를 이전 동작과 일치시키기 위해 일반 변수로 작동해야합니다.

KV Secrets Engine v2

v2 엔진에는 두 가지 형식을 사용할 수 있습니다.

긴 형식: 

job:
  variables:
    VAULT_SERVER_URL: https://vault.example.com
    VAULT_AUTH_PATH: jwt_v2  # 또는 "jwt" (B 방법 사용 시)
    VAULT_AUTH_ROLE: myproject-staging
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    PASSWORD:
      vault:
        engine:
          name: kv-v2
          path: secret
        field: password
        path: myproject/staging/db
      file: false

이것은 v1 엔진의 예제와 동일하지만 secrets:vault:engine:name:이 엔진과 일치하도록 kv-v2로 설정됩니다.

또한 짧은 형식을 사용할 수도 있습니다: 

job:
  variables:
    VAULT_SERVER_URL: https://vault.example.com
    VAULT_AUTH_PATH: jwt_v2  # 또는 "jwt" (B 방법 사용 시)
    VAULT_AUTH_ROLE: myproject-staging
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
      PASSWORD:
        vault: myproject/staging/db/password@secret
        file: false

업데이트된 CI/CD 구성을 커밋하면 이제 작업에서 ID 토큰을 사용하여 비밀을 가져옵니다. 축하합니다!

모든 프로젝트를 ID 토큰으로 비밀을 가져오도록 마이그레이션하고 마이그레이션에 방법 B를 사용한 경우 iss 클레임 유효성을 다시 원하는대로 인증 방법 구성으로 이동할 수 있게 되었습니다.