OpenID Connect

OpenID Connect를 사용하면 워크플로가 클라우드 공급자에서 직접 단기 토큰을 교환할 수 있습니다.

이 기사에서

OpenID Connect (OIDC) 개요

          GitHub Actions 워크플로는 소프트웨어를 배포하거나 클라우드 서비스를 사용하기 위해 클라우드 공급자(예: AWS, Azure, GCP, HashiCorp Vault 등)에 액세스하도록 설계되었습니다. 워크플로가 이러한 리소스에 액세스하기 전에 클라우드 공급자에게 암호 또는 토큰과 같은 자격 증명을 제공합니다. 이러한 자격 증명은 일반적으로 비밀 GitHub로 저장되며 워크플로는 실행될 때마다 클라우드 공급자에게 이 비밀을 제공합니다.

그러나 하드 코딩된 비밀을 사용하려면 클라우드 공급자에서 자격 증명을 만든 다음 비밀로 복제해야 합니다 GitHub .

클라우드 공급자와 OIDC 기반 신뢰 관계를 구축하면, 워크플로에서 해당 공급자에게 직접 단기 액세스 토큰을 요청하도록 설정할 수 있습니다.

OIDC 사용의 이점

OIDC 토큰을 사용하도록 워크플로를 업데이트하면 다음과 같은 적절한 보안 사례를 채택할 수 있습니다.

  •         **클라우드 비밀 없음:** 클라우드 자격 증명을 수명이 GitHub 긴 비밀로 복제할 필요가 없습니다. 대신 클라우드 공급자에서 OIDC 트러스트를 구성한 다음, 워크플로를 업데이트하여 OIDC를 통해 클라우드 공급자로부터 단기 액세스 토큰을 요청할 수 있습니다.

  •         **인증 및 권한 부여 관리**: 워크플로가 자격 증명을 활용하는 방식과 클라우드 공급자의 인증 및 권한 부여 도구를 통해 클라우드 리소스 접근을 관리하는 과정을 더욱 정밀하게 통제할 수 있습니다.

  •         **자격 증명 순환**: OIDC를 활용하면 클라우드 제공업체가 특정 작업에 한해 유효한 단기 액세스 토큰을 발급하며, 해당 토큰은 작업 완료 후 자동으로 만료됩니다.

OIDC와 통합하는 방법 GitHub Actions

다음 다이어그램은 GitHub의 OIDC 공급자가 워크플로와 클라우드 공급자와 어떻게 통합되는지를 보여주는 개요를 제공합니다.

클라우드 서비스 제공업체가 액세스 토큰과 JSON 웹 토큰(JWT) 기반의 클라우드 역할 ID를 활용하여 GitHub Actions와 연동되는 과정을 설명하는 다이어그램입니다.

  1. 클라우드 공급자에서 OIDC 트러스트 관계를 설정하여 특정 GitHub 워크플로가 정의된 클라우드 역할을 대신하여 클라우드 액세스 토큰을 요청할 수 있도록 합니다.
  2. 작업이 실행될 때마다 GitHub의 OIDC 공급자가 OIDC 토큰을 자동으로 생성합니다. 이 토큰에는 인증하려는 특정 워크플로에 대해 보안이 강화되고 확인 가능한 ID를 설정하는 여러 클레임이 포함되어 있습니다.
  3. 워크플로 작업의 단계 또는 작업은 'OIDC 공급자'의 GitHub토큰을 요청할 수 있으며, 이를 클라우드 공급자에게 워크플로 ID 증명으로 표시할 수 있습니다.
  4. 클라우드 공급자가 토큰에 제공된 클레임의 유효성을 성공적으로 검사하면 작업 기간 동안에만 사용할 수 있는 수명이 짧은 클라우드 액세스 토큰을 제공합니다.

OIDC 토큰 이해

각 작업은 OIDC 공급자로부터 GitHubOIDC 토큰을 요청합니다. 이 토큰은 생성된 각 워크플로 작업에 대해 고유한 자동으로 생성된 JWT(JSON 웹 토큰)로 응답합니다. 작업이 실행되면 클라우드 공급자에게 OIDC 토큰이 표시됩니다. 토큰의 유효성을 검사하기 위해 클라우드 공급자는 OIDC 토큰의 주체 및 기타 클레임이 클라우드 역할의 OIDC 트러스트 정의에 미리 구성된 조건과 일치하는지 확인합니다.

다음 예제 OIDC 토큰은 sub 리포지토리에 prod라는 작업 환경을 참조하는 주체(octo-org/octo-repo)를 사용합니다.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "enterprise": "avocado-corp",
  "enterprise_id": "2",
  "repo_property_workspace_id": "ws-abc123",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

클라우드 공급자와의 OIDC 신뢰 설정

워크플로에서 OIDC를 사용하려면 클라우드 공급자와 클라우드 공급자 간에 GitHub 트러스트 관계를 설정해야 합니다. 이를 통해 신뢰 관계가 구축되면, 승인된 워크플로만이 클라우드 리소스 액세스를 위한 토큰을 요청할 수 있게 됩니다.

클라우드 제공업체는 액세스 토큰을 발급하기에 앞서, 신뢰 설정에 정의된 subject 및 기타 조건들이 요청된 JSON 웹 토큰(JWT) 내의 클레임 정보와 일치하는지 철저히 검증합니다. 클라우드 공급자는 신뢰 구성이 일치할 때 워크플로를 위한 임시 액세스 토큰을 발급합니다.

OIDC 신뢰 구성 및 클라우드 공급자 조건 설정에 필요한 단계와 구문은 OpenID 연결 참조을 참고하시기 바랍니다.

OIDC 설정 중 GHE.com

엔터프라이즈에서 데이터 보존 기능을 갖춘 GitHub Enterprise Cloud를 사용하고 있으며 GHE.com에서 OIDC를 설정하는 경우, OIDC를 구성할 때 특정 값을 대체해야 합니다.

자세한 내용은 OpenID 연결 참조을(를) 참조하세요.

OIDC를 활용하여 사용자 정의 작업에 대한 인증

OIDC를 통한 인증은 getIDToken() Actions 도구 키트 또는 curl 명령의 메서드를 활용하여 사용자 지정 작업에서 수행됩니다.

자세한 내용은 OpenID 연결 참조을(를) 참조하세요.

OIDC에 대한 워크플로 업데이트

          GitHub Actions 워크플로는 비밀 대신 OIDC 토큰을 사용하여 클라우드 공급자를 인증할 수 있습니다. 주요 클라우드 공급자들은 워크플로에서 OIDC를 활용한 인증 프로세스를 간편하게 처리할 수 있도록 공식 로그인 작업을 제공합니다. 특정 클라우드 공급자를 통해 워크플로를 업데이트하는 방법에 대해 자세히 알아보려면 [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments)을 참고하시기 바랍니다.

리포지토리 사용자 지정 속성을 OIDC 클레임으로 사용

조직 및 엔터프라이즈 관리자는 리포지토리 사용자 지정 속성을 OIDC 토큰에 클레임으로 포함할 수 있습니다. 이렇게 하면 하드 코딩된 허용 목록이 아닌 리포지토리 메타데이터에 의해 구동되는 클라우드 공급자, 아티팩트 레지스트리 또는 비밀 관리자에서 ABAC(특성 기반 액세스 제어) 정책을 사용할 수 있습니다.

사용자 지정 속성 클레임의 동작 방식

사용자 지정 속성을 OIDC 클레임으로 사용하기 위한 엔드 투 엔드 흐름은 다음과 같습니다.

  1.        **사용자 지정 속성을 정의합니다.** 조직 또는 엔터프라이즈 관리자는 사용자 지정 속성(예: `business_unit`, `data_classification`또는 `environment_tier`)을 만들고 리포지토리에 값을 할당합니다. 자세한 내용은 [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) 및 [AUTOTITLE](/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens)을(를) 참조하세요. 

  2.        **OIDC 토큰에서 속성을 사용하도록 설정합니다.** 조직 또는 엔터프라이즈 관리자는 설정 UI 또는 REST API를 사용하여 OIDC 토큰에 포함할 사용자 지정 속성을 선택합니다.

  3.        **클레임이 자동으로 표시됩니다.** 활성화된 속성에 대해 설정된 값이 있는 리포지토리에서 실행되는 모든 워크플로는 접두사로 `repo_property_`OIDC 토큰에 해당 값을 포함합니다. 워크플로 수준 구성 변경이 필요하지 않습니다.

  4.        **클라우드 신뢰 정책을 업데이트합니다.** 클라우드 공급자의 신뢰 조건을 업데이트하여 새 `repo_property_*` 클레임을 평가하여 세분화된 특성 기반 액세스 결정을 수행할 수 있습니다.

이는 기존 OIDC의 수명이 짧은 자격 증명 모델을 기반으로 GitHub하기 때문에 수명이 긴 비밀이 필요하지 않으며 모든 토큰의 범위가 지정되고 감사 가능하며 워크플로 실행당 자동으로 회전됩니다.

사전 요구 사항

OIDC 토큰 클레임에 사용자 지정 속성 추가

OIDC 토큰에 사용자 지정 속성을 포함하려면 REST API 또는 조직 또는 엔터프라이즈에 대한 설정 UI를 사용합니다.

  •         **설정 UI 사용:** 조직 또는 기업의 작업 OIDC 설정 페이지로 이동하여 OIDC 토큰에 포함된 사용자 지정 속성을 보고 관리합니다.

  •         **REST API 사용:** 엔드포인트에 `POST``/orgs/{org}/actions/oidc/customization/properties/repo` 요청을 보내 조직의 OIDC 토큰 클레임에 사용자 지정 속성을 추가합니다. 요청 매개 변수 및 전체 세부 정보는 OIDC 사용자 지정 속성인 [AUTOTITLE](/rest/actions/oidc)을 관리하기 위한 REST API 설명서를 참조하세요.

사용자 지정 속성을 사용하는 예제 OIDC 토큰

다음 예제에서는 단일 선택 속성과 문자열 business_unit속성의 두 가지 사용자 지정 속성을 workspace_id 포함하는 OIDC 토큰을 보여 있습니다. 각 사용자 지정 속성은 repo_property_ 접두사와 함께 토큰에 나타납니다.

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "repo_property_business_unit": "payments",
  "repo_property_workspace_id": "ws-abc123"
}

클라우드 공급자의 신뢰 조건에서 클레임을 사용하여 repo_property_* 유연한 특성 기반 액세스 제어 정책을 만들 수 있습니다. 클레임 형식, 지원되는 속성 형식 및 제한에 대한 자세한 내용은 OpenID 연결 참조을 참조하세요.

에 대한 OIDC 지원 Dependabot

          Dependabot 는 OIDC를 사용하여 개인 레지스트리로 인증할 수 있으므로 수명이 긴 자격 증명을 리포지토리 비밀로 저장할 필요가 없습니다. OIDC 기반 인증 Dependabot 을 사용하면 업데이트 작업이 클라우드 ID 공급자로부터 수명이 짧은 자격 증명을 동적으로 가져올 수 있습니다.

          Dependabot는 레지스트리가 AWS CodeArtifact, Azure DevOps Artifacts 또는 JFrog Artifactory에서 호스팅될 때 `username` 및 `password` 인증을 사용하는 모든 종류의 레지스트리에 대해 OIDC 인증을 지원합니다.

OIDC 인증 Dependabot 의 이점은 다음과 같습니다.

  •         **향상된 보안:** 리포지토리에서 수명이 긴 정적 자격 증명을 제거합니다.

  •         **더 간단한 관리:** 프라이빗 레지스트리에 대한 보안 정책 규격 액세스를 사용하도록 설정합니다.

  •         **속도 제한 방지:** 동적 자격 증명을 사용하면 정적 토큰과 관련된 속도 제한에 도달하는 것을 방지할 수 있습니다.

자세한 내용은 Dependabot에 대한 개인 레지스트리 액세스 구성을(를) 참조하세요.

다음 단계

OIDC 설정에 관한 자세한 내용은 배포 보안 강화하기을 참고하시기 바랍니다.

OIDC에 대한 참조 정보는 OpenID 연결 참조을 참고하시기 바랍니다.