기타 OIDC 제공자와 워크로드 아이덴티티 페더레이션

기타 OIDC 제공자와 워크로드 아이덴티티 페더레이션 (Federate workload identity with other OIDC providers)

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

출처: 문서

본문

사전 요구 사항

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

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

아이덴티티 제공자 사전 요구 사항

사용하는 IdP는 다음 요구 사항을 충족해야 해요.

• OpenID Connect 1.0을 지원해야 해요.
• 공개적으로 접근 가능한 OIDC 메타데이터 및 JWKS 엔드포인트를 가져야 해요. 엔드포인트는 SSL과 TLS로 보호되어야 하고 https://로 시작해야 해요.

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

커스텀 OIDC IdP용 HCP 워크로드 아이덴티티 제공자를 만들려면 다음 구성 값을 제공해야 해요.

• issuer URI
• 예상 audience
• 조건부 접근 문(conditional access statement)

Audience

기본적으로 OIDC 워크로드 아이덴티티 제공자는 들어오는 토큰의 aud 필드가 워크로드 아이덴티티 제공자의 리소스 이름과 같은지 검증해요. 이 동작은 토큰이 HCP와 교환되도록 의도된 것임을 보장해요.

이 값의 형식은 다음과 같아요.

`iam/project/<PROJECT_ID>/service-principal/<SERVICE_PRINCIPAL_NAME>/workload-identity-provider/<NAME>`

다음 예시는 my_sp를 HCP 서비스 주체로, oidc-example을 그 서비스 주체를 사용하는 워크로드 아이덴티티 제공자의 이름으로 식별해요.

`iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-sp/workload-identity-provider/oidc-example`.

워크로드 아이덴티티 제공자를 만들 때 예상 audience를 정의하지 않았다면, 워크로드가 최종적으로 받는 토큰의 aud가 형식화된 리소스 이름으로 설정되어 있는지 확인해 주세요.

프로바이더에 커스텀 aud 클레임을 기대하도록 구성할 수도 있어요.

조건부 접근 문 (Conditional access statement)

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

아이덴티티 토큰을 HCP 접근 권한으로 교환할 때, 조건부 접근 문은 jwt_claims. 접두어로 토큰의 모든 클레임에 접근할 수 있어요. 다음 예시는 JWT 토큰의 필드와 이름을 나열하고, 그 토큰의 정보를 사용하는 조건부 접근 문을 설명해요.

{
  "jti": "example-id",
  "sub": "env:prod::namespace:my-namespace::service:my-workload",
  "namespace": "my-namespace",
  "service": "my-workload",
  "env": "prod",
  "aud": "iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-sp/workload-identity-provider/oidc-example",
  "iss": "https://custom-oidc-idp.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

다음 예시에서 HCP는 토큰의 sub 필드가 "env:prod::namespace:my-namespace::service:my-workload"일 때만 워크로드의 접근을 허용해요.

`jwt_claims.sub == “env:prod::namespace:my-namespace::service:my-workload”`

다음 예시에서 HCP는 워크로드가 시작된 환경과 관계없이 서비스 이름 my-workload와 네임스페이스 my-namespace를 가진 워크로드를 허용해요.

`jwt_claims.sub matches “^env:.+::namespace:my-namespace::service:my-workload$”`

다음 예시에서 HCP는 prod 환경의 my-namespace 네임스페이스에 있는 워크로드를 허용해요.

`jwt_claims.env == “prod” and jwt_claims.namespace == “my-namespace”`

조건부 접근 문 형식화에 대한 자세한 내용은 OIDC providers 문서를 참고하세요.

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

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

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=<ISSUER_URI> \
  --conditional-access=<CONDITION> \
  --allowed-audience=<CUSTOM_AUDIENCE_1> \
  --allowed-audiences=<CUSTOM_AUDIENCE_2> \
  --description=<DESCRIPTION>

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

• <PROVIDER_NAME>: 만들 워크로드 아이덴티티 제공자의 이름.
• <SP_RESOURCE_NAME>: iam/project/<PROJECT_ID>/service-principal/<NAME> 형식의 서비스 주체 리소스 이름.
• <ISSUER_URI>: IdP의 issuer URI. https://로 시작해야 해요.
• <CONDITION>: 지정된 워크로드에 대한 접근을 제한하는 조건부 접근 문.
• <CUSTOM_AUDIENCE>: ID 토큰의 예상 audience. 기본 예상 audience를 사용할 때는 플래그를 생략해요.
• <DESCRIPTION>: 프로바이더에 대한 선택적인 설명.

hcp_iam_workload_identity_provider 리소스를 사용해요.

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

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "oidc-example"
  service_principal = hcp_service_principal.workload_sp.resource_name
  description       = "Allow my-workload to act as my-app-runtime service principal"

  oidc {
    issuer_uri = "<ISSUER_URI>"

    # If not using the default audience, configure up to 16 allowed audiences.
    # allowed_audiences = ["<CUSTOM_AUDIENCE_1>", "<CUSTOM_AUDIENCE_>", ..., "<CUSTOM_AUDIENCE_N>" ]
  }

  conditional_access = "<CONDITION>"
}

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

• <ISSUER_URI>: IdP의 issuer URI. https://로 시작해야 해요.
• <CUSTOM_AUDIENCE>: 기본 예상 audience를 사용하지 않을 때의 ID 토큰 예상 audience.
• <CONDITION>: 지정된 워크로드에 대한 접근을 제한하는 조건부 접근 문.

워크로드의 자격 증명 인증

HCP CLI, HCP Terraform Provider, HCP Go SDK를 사용해 외부 자격 증명을 자동으로 가져와 HCP 액세스 토큰으로 교환할 수 있어요. 이 과정은 외부 자격 증명을 얻는 데 필요한 정보와 교환할 워크로드 아이덴티티 제공자를 포함하는 자격 증명 파일을 사용해요.

자세한 내용은 credential files 문서를 참고하세요.

커스텀 IdP용 자격 증명 파일 만들기

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

$ hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME> \
  --source-[<TOKEN_SOURCE>]
  --output-file=credentials.json

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

• <PROVIDER_NAME>: iam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME> 형식으로 자격 증명을 교환할 워크로드 아이덴티티 제공자의 이름.
• <TOKEN_SOURCE>: 자격 증명 파일은 환경 변수, 파일, 또는 URL에서 워크로드의 토큰을 가져올 수 있어요. 적절한 플래그를 선택하고 명령의 문서와 예시를 참고해요.

자격 증명 파일이 런타임 환경에 존재하는지 확인해 주세요. 자격 증명 파일에는 시크릿 값이 없으므로 VM이나 컨테이너에 저장할 수 있어요. 또는 런타임에 생성할 수도 있어요.

자격 증명 파일로 인증하려면 HCP CLI, HCP Terraform Provider, 또는 HCP Go SDK를 사용할 수 있어요. 자세한 내용은 자격 증명 파일로 인증하기 문서를 참고하세요.

더 알아보기 (Learn more)

• 워크로드 아이덴티티 페더레이션 — 워크로드 아이덴티티 페더레이션의 개요와 동작 방식을 확인해 보세요.
• 조건부 접근 문 — 조건부 접근 문을 작성하고 형식화하는 방법을 알아보세요.
• GitHub 제공자 구성 — GitHub Actions 워크로드를 연결하는 방법을 확인해 보세요.
• AWS 제공자 구성 — AWS 워크로드를 연결하는 방법을 알아보세요.