OIDC 워크로드 아이덴티티 프로바이더 생성

OIDC 워크로드 아이덴티티 프로바이더 생성 (hcp iam workload-identity-providers create-oidc)

hcp iam workload-identity-providers create-oidc 명령은 OIDC 기반의 새로운 워크로드 아이덴티티 프로바이더를 생성하는 명령이에요.

흔히 쓰이는 OIDC 프로바이더로는 Azure, GCP, Kubernetes 클러스터, HashiCorp Vault, GitHub, GitLab 등이 있어요.

OIDC 프로바이더를 만들 때는 issuer URL, 조건부 접근 구문(conditional access statement), 그리고 선택적으로 허용 대상(audience)을 지정해야 해요.

issuer URL은 워크로드 아이덴티티 교환을 허용하는 OIDC 프로바이더의 URL이에요. 이 URL은 HCP 컨트롤 플레인에서 접근 가능한 유효한 URL이어야 하고, OIDC 디스커버리 엔드포인트(${issuer_url}/.well-known/openid-configuration)에 대한 응답에 설정된 issuer와 일치해야 해요.

조건부 접근 구문은 반드시 설정해야 하며, OIDC 프로바이더가 발급한 토큰 중 어떤 것이 아이덴티티를 HCP 액세스 토큰으로 교환할 수 있는지를 제한하는 데 사용돼요. 이 구문은 토큰 교환 시 평가되는 hashicorp/go-bexpr 문자열이에요. 외부 아이덴티티 토큰의 모든 클레임에 접근할 수 있으며, "jwt_claims.<claim_name>" 구문으로 접근할 수 있어요. 특정 subject 클레임으로 접근을 제한하는 조건부 접근 구문의 예로는 'jwt_claims.sub == "example"'가 있어요.

허용 대상(audience)을 설정하지 않으면 기본값은 프로바이더의 리소스 이름이 돼요. 형식은 iam/project/PROJECT_ID/service-principal/SP_NAME/workload-identity-provider/WIP_NAME 이에요. 설정한 경우, 제시된 액세스 토큰은 허용 대상 집합에 포함된 audience를 가져야 해요.

출처: 문서

본문

사용법 (Usage)

$ hcp iam workload-identity-providers create-oidc PROVIDER_NAME
  --conditional-access=STATEMENT --issuer=URI --service-principal=RESOURCE_NAME
  [Optional Flags]

예시 (Examples)

Azure — User Managed Identity 교환 허용:

$ hcp iam workload-identity-providers create-oidc azure-example-user-managed \
  --service-principal=iam/project/PROJECT/service-principal/example-sp \
  --issuer=https://sts.windows.net/AZURE_AD_TENANT_ID/ \
  --allowed-audience=MANAGED_IDENTITY_CLIENT_ID \
  --conditional-access='jwt_claims.sub == "MANAGED_IDENTITY_OBJECT_PRINCIPAL_ID"' \
  --description="Azure User Managed Identity Example"

GCP — Service Account 아이덴티티 교환 허용 (클레임 전체 목록):

$ hcp iam workload-identity-providers create-oidc gcp-example-service-account \
  --service-principal=iam/project/PROJECT/service-principal/example-sp \
  --issuer=https://accounts.google.com \
  --conditional-access='jwt_claims.sub == "SERVICE_ACCOUNT_UNIQUE_ID"' \
  --description="GCP Service Account Example"

GitLab — GitLab 아이덴티티 교환 허용 (클레임 전체 목록):

$ hcp iam workload-identity-providers create-oidc gcp-example-service-account \
  --service-principal=iam/project/PROJECT/service-principal/example-sp \
  --issuer=https://gitlab.com \
  --conditional-access='jwt_claims.project_path == "example-org/example-repo" and jwt_cliams.job_id == 302' \
  --description="GitLab example-repo access for job 302"

위치 인자 (Positional arguments)

  • PROVIDER_NAME — 생성할 프로바이더의 이름이에요.

필수 플래그 (Required flags)

  • --conditional-access=STATEMENT — 조건부 접근 구문은 토큰 교환 시 평가되는 hashicorp/go-bexpr 문자열이에요. 서비스 프린시펄에 접근할 수 있는 업스트림 아이덴티티를 제한해요. 조건부 접근 구문은 jwt_claims.<claim_name> 구문을 사용해 외부 아이덴티티 토큰의 어떤 클레임이든 접근할 수 있어요. 예를 들어 jwt_claims.sub로 subject 클레임에 접근할 수 있어요.
  • --issuer=URI — 워크로드 아이덴티티 교환을 허용하는 OIDC Issuer의 URL이에요.
  • --service-principal=RESOURCE_NAME — 프로바이더를 생성할 서비스 프린시펄의 리소스 이름이에요.

선택 플래그 (Optional flags)

  • --allowed-audience=AUD [반복 가능] — 아이덴티티 교환을 허용하는 액세스 토큰에 설정된 audience 집합이에요. 액세스 토큰은 이 집합에 포함된 audience를 가져야 해요. audience를 설정하지 않으면 기본 허용 audience는 프로바이더의 리소스 이름이 돼요. 형식은 iam/project/PROJECT_ID/service-principal/SP_NAME/workload-identity-provider/WIP_NAME 이에요.
  • --description=TEXT — 프로바이더에 대한 설명이에요.

더 알아보기 (Learn more)