OpenID Connect 살펴보기

OpenID Connect를 사용하면 워크플로가 클라우드 제공자로부터 단기 토큰을 직접 교환할 수 있어요.

출처: OpenID Connect

본문

OpenID Connect(OIDC) 개요

GitHub Actions 워크플로는 소프트웨어를 배포하거나 클라우드 서비스를 사용하기 위해 클라우드 제공자(AWS, Azure, GCP, HashiCorp Vault 등)에 접근하도록 설계되는 경우가 많아요. 워크플로가 이런 리소스에 접근하기 전에 비밀번호나 토큰 같은 자격 증명을 클라우드 제공자에 제공해요. 이 자격 증명은 보통 GitHub에 비밀(secret)으로 저장되며, 워크플로는 실행할 때마다 이 비밀을 클라우드 제공자에 제시해요.

하지만 하드코딩된 비밀을 사용하려면 클라우드 제공자에서 자격 증명을 만들고, 그 다음 GitHub에 비밀로 중복해서 만들어야 해요.

OIDC를 지원하는 클라우드 제공자와 신뢰 연결을 설정한 후에는 워크플로가 클라우드 제공자에게 단기 액세스 토큰을 직접 요청하도록 구성할 수 있어요.

OIDC 사용의 이점

워크플로를 OIDC 토큰을 사용하도록 업데이트하면 다음의 좋은 보안 관행을 채택할 수 있어요:

클라우드 비밀 불필요(No cloud secrets): 클라우드 자격 증명을 장기 보존 GitHub 비밀로 중복할 필요가 없어요. 대신 클라우드 제공자에 OIDC 신뢰를 구성하고, 워크플로가 OIDC를 통해 클라우드 제공자에게 단기 액세스 토큰을 요청하도록 업데이트하면 돼요.
인증·인가 관리(Authentication and authorization management): 클라우드 제공자의 인증(authN)과 인가(authZ) 도구를 사용해 클라우드 리소스 접근을 제어하면서, 워크플로가 자격 증명을 사용하는 방법을 더 세밀하게 제어할 수 있어요.
자격 증명 회전(Rotating credentials): OIDC를 사용하면 클라우드 제공자가 단일 작업에서만 유효하고 자동으로 만료되는 단기 액세스 토큰을 발급해요.

OIDC가 GitHub Actions와 통합되는 방식

다음 다이어그램은 GitHub의 OIDC 제공자가 워크플로와 클라우드 제공자와 통합되는 방식을 개괄적으로 보여줘요:

클라우드 제공자가 액세스 토큰과 JSON 웹 토큰 클라우드 역할 ID를 통해 GitHub Actions와 통합되는 방식 다이어그램.

클라우드 제공자에서 OIDC 신뢰 관계를 설정해 특정 GitHub 워크플로가 정의된 클라우드 역할을 대신해 클라우드 액세스 토큰을 요청할 수 있게 해요.
작업이 실행될 때마다 GitHub의 OIDC 제공자가 OIDC 토큰을 자동 생성해요. 이 토큰은 인증하려는 특정 워크플로에 대한 보안 강화되고 검증 가능한 신원을 확립하는 여러 클레임(claim)을 포함해요.
워크플로 작업의 단계나 액션은 GitHub의 OIDC 제공자에게 토큰을 요청할 수 있고, 그 토큰을 워크플로 신원의 증거로 클라우드 제공자에 제시할 수 있어요.
클라우드 제공자가 토큰에 제시된 클레임을 성공적으로 검증하면 작업 기간 동안만 사용할 수 있는 단기 클라우드 액세스 토큰을 제공해요.

OIDC 토큰 이해하기

각 작업은 GitHub의 OIDC 제공자에게 OIDC 토큰을 요청하고, 제공자는 생성된 각 워크플로 작업마다 고유한 자동 생성 JSON 웹 토큰(JWT)으로 응답해요. 작업이 실행되면 OIDC 토큰이 클라우드 제공자에 제시돼요. 토큰을 검증하기 위해 클라우드 제공자는 OIDC 토큰의 주체(subject)와 기타 클레임이 클라우드 역할의 OIDC 신뢰 정의에 사전 구성된 조건과 일치하는지 확인해요.

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

{
  "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",
  "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
}

[!NOTE] 이 예시의 sub 클레임은 이전 형식을 사용해요. 2026년 7월 15일 이후 생성된 리포지토리는 소유자와 리포지토리 ID를 포함하는 불변 기본 주체 형식(immutable default subject format)을 사용해요(GitHub Enterprise Server에는 없음). 자세한 내용은 OpenID Connect 참조를 참고하세요.

사용자 지정 액션을 OIDC로 인증하기

사용자 지정 액션은 Actions 툴킷의 getIDToken() 메서드나 curl 명령을 사용해 OIDC로 인증해요.

자세한 내용은 OpenID Connect 참조를 참고하세요.

워크플로를 OIDC용으로 업데이트하기

GitHub Actions 워크플로는 클라우드 제공자와 인증할 때 비밀 대신 OIDC 토큰을 사용할 수 있어요. 많은 인기 클라우드 제공자가 워크플로에서 OIDC 사용을 간소화하는 공식 로그인 액션을 제공해요. 특정 클라우드 제공자로 워크플로를 업데이트하는 방법은 배포 보안 강화하기를 참고하세요.

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

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

사용자 지정 속성 클레임이 동작하는 방식

사용자 지정 속성을 OIDC 클레임으로 사용하는 엔드 투 엔드 흐름은 다음과 같아요:

사용자 지정 속성 정의하기. 조직 또는 엔터프라이즈 관리자가 사용자 지정 속성(예: business_unit, data_classification, environment_tier)을 만들고 리포지토리에 값을 할당해요. 자세한 내용은 조직의 리포지토리 사용자 지정 속성 관리하기와 OpenID Connect 참조를 참고하세요.
OIDC 토큰에서 속성 활성화하기. 조직 또는 엔터프라이즈 관리자가 설정 UI 또는 REST API를 사용해 OIDC 토큰에 포함할 사용자 지정 속성을 선택해요.
클레임이 자동으로 나타나요. 활성화된 속성에 대해 값이 설정된 리포지토리의 모든 워크플로 실행은 repo_property_ 접두사와 함께 그 값을 OIDC 토큰에 포함해요. 워크플로 수준 구성 변경은 필요 없어요.
클라우드 신뢰 정책 업데이트하기. 클라우드 제공자의 신뢰 조건을 업데이트해 새 repo_property_* 클레임을 평가하도록 해서 세밀한 속성 기반 접근 결정을 가능하게 해요.

이 방식은 GitHub의 기존 OIDC 단기 자격 증명 모델 위에 구축되므로 장기 보존 비밀이 필요 없고, 모든 토큰이 범위가 제한되고 감사 가능하며 워크플로 실행마다 자동으로 회전돼요.

사전 요구사항

사용자 지정 속성이 조직 또는 엔터프라이즈 수준에서 이미 정의되어 있어야 해요. 자세한 내용은 조직의 리포지토리 사용자 지정 속성 관리하기를 참고하세요.
조직 관리자 또는 엔터프라이즈 관리자여야 해요.

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

사용자 지정 속성을 OIDC 토큰에 포함하려면 조직이나 엔터프라이즈의 REST API 또는 설정 UI를 사용하세요.

설정 UI 사용하기: 조직 또는 엔터프라이즈의 Actions OIDC 설정 페이지로 이동해 OIDC 토큰에 포함할 사용자 지정 속성을 보고 관리하세요.
REST API 사용하기: OIDC 토큰 클레임에 사용자 지정 속성을 추가하려면 /orgs/{org}/actions/oidc/customization/properties/repo 엔드포인트에 POST 요청을 보내세요. 요청 파라미터와 전체 내용은 OIDC 사용자 지정 속성 관리용 REST API 문서인 GitHub Actions OIDC용 REST API 엔드포인트를 참고하세요.

사용자 지정 속성이 포함된 예시 OIDC 토큰

다음 예시는 두 개의 사용자 지정 속성이 포함된 OIDC 토큰을 보여줘요. 단일 선택 속성 business_unit과 문자열 속성 workspace_id예요. 각 사용자 지정 속성은 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 Connect 참조를 참고하세요.

Dependabot용 OIDC 지원

Dependabot은 OIDC를 사용해 비공개 레지스트리와 인증할 수 있어서, 장기 보존 자격 증명을 리포지토리 비밀로 저장할 필요가 없어요. OIDC 기반 인증을 사용하면 Dependabot 업데이트 작업이 클라우드 신원 제공자로부터 단기 자격 증명을 동적으로 얻을 수 있어요.

Dependabot은 레지스트리가 AWS CodeArtifact, Azure DevOps Artifacts, JFrog Artifactory에 호스팅되어 있고 username과 password 인증을 사용하는 모든 레지스트리 유형에 대해 OIDC 인증을 지원해요.

Dependabot용 OIDC 인증의 이점은 다음과 같아요:

보안 강화: 리포지토리에서 정적·장기 보존 자격 증명을 제거해요.
더 간단한 관리: 비공개 레지스트리에 대한 안전하고 정책을 준수하는 접근을 가능하게 해요.
속도 제한 회피: 동적 자격 증명은 정적 토큰과 관련된 속도 제한을 피하는 데 도움이 돼요.

자세한 내용은 Dependabot용 비공개 레지스트리 접근 구성하기를 참고하세요.

다음 단계

OIDC 구성에 대한 자세한 내용은 배포 보안 강화하기를 참고하세요.

OIDC에 대한 참조 정보는 OpenID Connect 참조를 참고하세요.

OpenID Connect 살펴보기