OpenID Connect 참조(OpenID Connect reference)

OpenID Connect(OIDC)를 사용해서 GitHub Actions 워크플로를 클라우드 공급자에 인증하는 방법에 대한 정보를 확인할 수 있어요. 장기 유효 시크릿 대신 단기 토큰으로 안전하게 인증하고 싶다면 꼭 알아두세요.

출처: 문서

본문

OpenID Connect(OIDC)를 사용해서 GitHub Actions 워크플로를 클라우드 공급자에 인증하는 방법에 대한 정보를 확인할 수 있습니다.

OIDC 토큰 클레임

GitHub의 OIDC 공급자가 지원하는 모든 클레임을 보려면 https://token.actions.githubusercontent.com/.well-known/openid-configuration에서 claims_supported 항목을 검토하세요.

OIDC 토큰에는 다음 클레임이 포함됩니다.

표준 audience, issuer, subject 클레임

Claim	Claim type	Description
`aud`	Audience	기본적으로 저장소를 소유한 조직 같은 저장소 소유자의 URL입니다. 툴킷 커맨드로 사용자 지정 audience를 설정할 수 있습니다: `core.getIDToken(audience)`
`iss`	Issuer	OIDC 토큰의 발급자: `https://token.actions.githubusercontent.com`
`sub`	Subject	클라우드 공급자가 검증할 subject 클레임을 정의합니다. 이 설정은 액세스 토큰이 예측 가능한 방식으로만 할당되도록 하는 데 중요합니다. 불변 subject 클레임을 사용하는 저장소의 경우 `sub` 형식은 불변 소유자 및 저장소 ID를 포함합니다(GitHub Enterprise Server에서는 사용할 수 없음).

추가 표준 JOSE 헤더 파라미터와 클레임

Header Parameter	Parameter type	Description
`alg`	Algorithm	OIDC 공급자가 사용하는 알고리즘.
`kid`	Key identifier	OIDC 토큰의 고유 키.
`typ`	Type	토큰의 유형을 설명합니다. JSON Web Token(JWT)입니다.

Claim	Claim type	Description
`exp`	Expires at	JWT의 만료 시간을 식별.
`iat`	Issued at	JWT가 발급된 시간.
`jti`	JWT token identifier	OIDC 토큰의 고유 식별자.
`nbf`	Not before	JWT가 이 시간 전에는 유효하지 않음.

GitHub가 제공하는 사용자 지정 클레임

Claim	Description
`actor`	워크플로 실행을 시작한 개인 계정.
`actor_id`	워크플로 실행을 시작한 개인 계정의 ID.
`base_ref`	워크플로 실행에서 풀 리퀘스트의 대상 브랜치.

`check_run_id`	현재 잡의 체크 실행 ID.



`environment`	잡이 사용하는 환경의 이름. `environment` 클레임이 포함되면(`include_claim_keys` 통해서도) 환경이 필수이며 제공되어야 합니다.
`event_name`	워크플로 실행을 트리거한 이벤트의 이름. Dependabot 업데이트 잡을 위해 요청된 OIDC 토큰은 값으로 `dynamic`을 사용합니다.
`head_ref`	워크플로 실행에서 풀 리퀘스트의 소스 브랜치.
`job_workflow_ref`	재사용 가능한 워크플로를 사용하는 잡의 경우 재사용 가능한 워크플로에 대한 ref 경로. 자세한 내용은 Using OpenID Connect with reusable workflows를 참고하세요.
`job_workflow_sha`	재사용 가능한 워크플로를 사용하는 잡의 경우 재사용 가능한 워크플로 파일의 커밋 SHA.
`ref`	(참조) 워크플로 실행을 트리거한 git ref.
`ref_type`	`ref`의 유형, 예: "branch".
`repository_visibility`	워크플로가 실행 중인 저장소의 가시성. 다음 값을 허용합니다: `internal`, `private`, `public`.
`repository`	워크플로가 실행 중인 저장소.
`repository_id`	워크플로가 실행 중인 저장소의 ID.
`repository_owner`	`repository`가 저장된 조직의 이름.
`repository_owner_id`	`repository`가 저장된 조직의 ID.

`repo_property_*`	조직 또는 엔터프라이즈 레벨에서 정의된 사용자 지정 속성으로, `repo_property_` 접두사가 붙어 OIDC 토큰의 클레임으로 포함됩니다. 자세한 내용은 Including repository custom properties in OIDC tokens을 참고하세요.

`run_id`	워크플로를 트리거한 워크플로 실행의 ID.
`run_number`	이 워크플로가 실행된 횟수.
`run_attempt`	이 워크플로 실행이 재시도된 횟수.
`runner_environment`	잡이 사용하는 러너의 유형. 다음 값을 허용합니다: `github-hosted` 또는 `self-hosted`.
`workflow`	워크플로의 이름.
`workflow_ref`	워크플로에 대한 ref 경로. 예를 들어 `octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch`.
`workflow_sha`	워크플로 파일의 커밋 SHA.

클라우드 역할의 신뢰 조건을 정의하는 데 사용되는 OIDC 클레임

Audience와 subject 클레임은 일반적으로 클라우드 역할/리소스에 조건을 설정할 때 결합해서 사용되어, GitHub 워크플로에 대한 접근을 스코프로 지정합니다.

Audience: 기본적으로 이 값은 조직이나 저장소 소유자의 URL을 사용합니다. 이 값을 사용해서 특정 조직의 워크플로만 클라우드 역할에 접근할 수 있다는 조건을 설정할 수 있습니다.
Subject: 기본적으로 미리 정의된 형식을 가지며 GitHub 조직, 저장소, 브랜치, 또는 연결된 job 환경 같은 워크플로에 대한 핵심 메타데이터 일부의 연결(concatenation)입니다. subject 클레임이 연결된 메타데이터로 조합되는 방식을 보려면 Example subject claims를 참고하세요.

더 세밀한 신뢰 조건이 필요하다면 JWT에 포함된 subject(sub) 클레임을 사용자 지정할 수 있습니다. 자세한 내용은 Customizing the token claims를 참고하세요.

이러한 조건을 설정하는 데 사용할 수 있는 추가 클레임이 OIDC 토큰에 많이 지원됩니다. 또한 클라우드 공급자가 액세스 토큰에 역할을 할당하게 해서 더 세밀한 권한을 지정할 수 있게 할 수도 있습니다.

Dependabot 업데이트 잡을 위해 요청된 OIDC 토큰은 event_name 클레임이 dynamic입니다. 신뢰 정책이 GitHub Actions 워크플로만 승인하도록 의도되었고 클라우드 공급자가 event_name에 대한 조건을 지원한다면, 워크플로가 기대하는 이벤트 이름만 허용하세요.

[!NOTE] 클라우드 공급자가 액세스 토큰을 발급하는 방식을 제어하려면 반드시 최소한 하나의 조건을 정의해야 합니다. 그래야 신뢰할 수 없는 저장소가 클라우드 리소스용 액세스 토큰을 요청할 수 없습니다.

예시 subject 클레임

다음 예시는 "Subject"를 조건으로 사용하는 방법을 보여주고, "Subject"가 연결된 메타데이터에서 어떻게 조합되는지 설명합니다. subject는 job 컨텍스트의 정보를 사용하며, 클라우드 공급자에게 특정 브랜치, 환경에서 실행되는 워크플로의 요청에만 액세스 토큰이 부여될 수 있음을 지시합니다. 다음 섹션은 사용할 수 있는 몇 가지 일반적인 subject를 설명합니다.

특정 환경 필터링

잡이 환경을 참조하면 subject 클레임에는 환경 이름이 포함됩니다.

특정 환경 이름을 필터링하는 subject를 구성할 수 있습니다. 이 예시에서 워크플로 실행은 octo-org 조직이 소유한 octo-repo라는 저장소에서 Production이라는 환경을 가진 잡에서 시작되어야 합니다:

구문: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
예시: repo:octo-org/octo-repo:environment:Production

`pull_request` 이벤트 필터링

잡이 환경을 참조하지 않는 경우에만 워크플로가 풀 리퀘스트 이벤트로 트리거되면 subject 클레임에 pull_request 문자열이 포함됩니다.

pull_request 이벤트를 필터링하는 subject를 구성할 수 있습니다. 이 예시에서 워크플로 실행은 octo-org 조직이 소유한 octo-repo라는 저장소에서 pull_request 이벤트로 트리거되어야 합니다:

구문: repo:ORG-NAME/REPO-NAME:pull_request
예시: repo:octo-org/octo-repo:pull_request

특정 브랜치 필터링

잡이 환경을 참조하지 않고 워크플로가 풀 리퀘스트 이벤트로 트리거되지 않는 경우에만 subject 클레임에 워크플로의 브랜치 이름이 포함됩니다.

특정 브랜치 이름을 필터링하는 subject를 구성할 수 있습니다. 이 예시에서 워크플로 실행은 octo-org 조직이 소유한 octo-repo라는 저장소에서 demo-branch라는 브랜치에서 시작되어야 합니다:

구문: repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
예시: repo:octo-org/octo-repo:ref:refs/heads/demo-branch

특정 태그 필터링

잡이 환경을 참조하지 않고 워크플로가 풀 리퀘스트 이벤트로 트리거되지 않는 경우에만 subject 클레임에 워크플로의 태그 이름이 포함됩니다.

특정 태그를 필터링하는 subject를 만들 수 있습니다. 이 예시에서 워크플로 실행은 octo-org 조직이 소유한 octo-repo라는 저장소에서 demo-tag라는 태그로 시작되어야 합니다:

구문: repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
예시: repo:octo-org/octo-repo:ref:refs/tags/demo-tag

`:`을 포함하는 메타데이터 필터링

메타데이터 값 안의 :은 subject 클레임에서 %3A로 대체됩니다.

콜론을 포함하는 메타데이터가 포함된 subject를 구성할 수 있습니다. 이 예시에서 워크플로 실행은 octo-org 조직이 소유한 octo-repo라는 저장소에서 Production:V1이라는 환경을 가진 잡에서 시작되어야 합니다:

구문: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
예시: repo:octo-org/octo-repo:environment:Production%3AV1

불변 subject 클레임

OpenID Connect(OIDC) 사양은 subject(sub) 클레임이 로컬에서 고유하고 절대로 재할당되지 않도록 요구합니다. 이전에는 기본 sub 형식이 조직 및 저장소 이름만 사용했습니다. 네임스페이스를 재활용하면 다른 소유자가 같은 subject 값을 만들 수 있었습니다.

이 시나리오를 방지하기 위해 2026년 7월 15일 이후에 생성된 저장소는 소유자 ID와 저장소 ID를 모두 포함하는 불변 기본 subject 형식을 사용합니다. 이 롤아웃은 GitHub Enterprise Server를 포함하지 않습니다.

구문: repo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/BRANCH
이전 형식 예시: repo:octo-org/octo-repo:ref:refs/heads/main
불변 형식 예시: repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main

@는 이름과 ID 사이의 구분자로 사용됩니다. @는 GitHub 사용자 이름이나 저장소 이름에 나타날 수 없기 때문입니다.

2026년 7월 15일 이전에 생성된 저장소는 불변 subject 클레임을 옵트인하지 않는 한 이전 형식을 유지합니다. OIDC 설정 UI나 REST API를 사용해서 조직 또는 저장소 레벨에서 옵트인할 수 있습니다.

2026년 7월 15일 이후의 저장소 이름 변경과 이전(transfer)도 불변 subject 형식으로 이동합니다.

클라우드 공급자에서 subject 구성하기

클라우드 공급자의 신뢰 관계에서 subject를 구성하려면 신뢰 구성에 subject 문자열을 추가해야 합니다. 다음 예시는 다양한 클라우드 공급자가 같은 repo:octo-org/octo-repo:ref:refs/heads/demo-branch subject를 서로 다른 방식으로 받을 수 있는 방법을 보여줍니다:

Cloud provider	Example
Amazon Web Services	`"token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"`
Azure	`repo:octo-org/octo-repo:ref:refs/heads/demo-branch`
Google Cloud Platform	`(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')`
HashiCorp Vault	`bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"`

2026년 7월 15일 이후에 생성되었거나 불변 subject 클레임을 옵트인한 저장소의 경우 sub 클레임에는 불변 예시에 표시된 것처럼 owner_id와 repo_id가 포함됩니다. 저장소가 사용하는 형식에 맞게 신뢰 정책을 업데이트하세요. 불변 subject 클레임은 GitHub Enterprise Server에서 사용할 수 없습니다.

Cloud provider	Immutable format example
Amazon Web Services	`"token.actions.githubusercontent.com:sub": "repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch"`
Azure	`repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch`
Google Cloud Platform	`(assertion.sub=='repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch')`
HashiCorp Vault	`bound_subject="repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch"`

특정 클라우드 공급자 구성에 대한 자세한 내용은 Security hardening your deployments에 나열된 가이드를 참고하세요.

토큰 클레임 사용자 지정하기

JWT에 포함되는 클레임을 사용자 지정해서 OIDC 구성을 보안 강화할 수 있습니다. 이러한 사용자 지정을 통해 워크플로가 클라우드에 호스팅된 리소스에 접근하도록 허용할 때 클라우드 역할에 대한 더 세밀한 신뢰 조건을 정의할 수 있습니다:

audience 클레임 값을 사용자 지정할 수 있습니다. Customizing the audience value를 참고하세요.
subject(sub) 클레임에 조건을 설정해서 JWT 토큰이 특정 저장소, 재사용 가능한 워크플로, 또는 다른 소스에서 시작되도록 요구함으로써 OIDC 구성의 형식을 사용자 지정할 수 있습니다.
repository_id와 repository_visibility 같은 추가 OIDC 토큰 클레임을 사용해서 세밀한 OIDC 정책을 정의할 수 있습니다. OpenID Connect를 참고하세요.
저장소 사용자 지정 속성을 OIDC 토큰의 클레임으로 포함시켜 속성 기반 접근 제어(ABAC) 정책을 활성화할 수 있습니다. Including repository custom properties in OIDC tokens를 참고하세요.

`audience` 값 사용자 지정하기

워크플로에서 사용자 지정 액션을 사용할 때 해당 액션은 GitHub Actions Toolkit을 사용해서 audience 클레임의 사용자 지정 값을 제공할 수 있습니다. 일부 클라우드 공급자는 공식 로그인 액션에서도 이를 사용해서 audience 클레임의 기본값을 강제합니다. 예를 들어 GitHub Action for Azure Login은 기본 aud 값을 api://AzureADTokenExchange로 제공하거나 워크플로에서 사용자 지정 aud 값을 설정할 수 있게 합니다. GitHub Actions Toolkit에 대한 자세한 내용은 문서의 OIDC token 섹션을 참고하세요.

액션이 제공하는 기본 aud 값을 사용하고 싶지 않다면 audience 클레임에 사용자 지정 값을 제공할 수 있습니다. 이렇게 하면 특정 저장소나 조직의 워크플로만 클라우드 역할에 접근할 수 있는 조건을 설정할 수 있습니다. 사용 중인 액션이 이를 지원한다면 워크플로의 with 키워드를 사용해서 액션에 사용자 지정 aud 값을 전달할 수 있습니다. 자세한 내용은 Metadata syntax reference를 참고하세요.

저장소 사용자 지정 속성을 OIDC 토큰에 포함시키기

조직 및 엔터프라이즈 관리자는 GitHub Actions OIDC 토큰에 클레임으로 포함할 저장소 사용자 지정 속성을 선택할 수 있습니다. OIDC 구성에 사용자 지정 속성이 추가되면 조직이나 엔터프라이즈에서 해당 속성에 값이 설정된 모든 저장소가 자동으로 OIDC 토큰에 포함합니다. 속성 이름은 repo_property_ 접두사가 붙어 토큰에 나타납니다.

이를 통해 클라우드 공급자에서 저장소 메타데이터에 직접 바인딩되는 ABAC(Attribute-Based Access Control) 정책을 만들어 구성 드리프트를 줄이고 각 저장소에 대한 별도 접근 구성을 관리할 필요를 없앨 수 있습니다.

클레임 형식

활성화된 각 사용자 지정 속성은 OIDC 토큰에서 별도의 클레임으로 나타납니다. 클레임 이름은 repo_property_ 접두사가 붙은 속성 이름입니다.

Custom property name	Claim name in OIDC token
`business_unit`	`repo_property_business_unit`
`workspace_id`	`repo_property_workspace_id`
`data_classification`	`repo_property_data_classification`

지원되는 속성 유형

다음 사용자 지정 속성 유형이 OIDC 클레임으로 지원됩니다. 토큰의 값 표현은 속성 유형에 따라 다릅니다.

Property type	Example value in OIDC token	Notes
String	`"repo_property_team": "platform-eng"`	값이 일반 문자열로 나타남.
Single select	`"repo_property_env_tier": "production"`	선택된 옵션이 일반 문자열로 나타남.
Multi select	`"repo_property_regions": "us-east-1,eu-west-1"`	선택된 여러 값이 단일 쉼표로 구분된 문자열로 결합됨.
True/false	`"repo_property_pci_compliant": "true"`	Boolean 값이 문자열 `"true"` 또는 `"false"`로 나타남.

멀티 선택 값 표현

저장소에 값을 여러 개 선택한 멀티 선택 사용자 지정 속성이 있으면 값들이 OIDC 토큰에서 단일 쉼표로 구분된 문자열로 결합됩니다. 예를 들어 저장소에 us-east-1과 eu-west-1 값을 가진 regions 속성이 있으면 클레임은 다음과 같이 나타납니다:

{
  "repo_property_regions": "us-east-1,eu-west-1"
}

클라우드 공급자에서 신뢰 정책을 구성할 때 문자열 매칭이나 포함(contains) 검사를 사용해서 멀티 선택 클레임을 평가하세요.

사용자 지정 속성 포함을 위한 사전 요구 사항

사용자 지정 속성은 조직 또는 엔터프라이즈 레벨에서 이미 정의되어 있어야 합니다. 자세한 내용은 Managing custom properties for repositories in your organization을 참고하세요.
조직 관리자 또는 엔터프라이즈 관리자여야 합니다.
OIDC 구성에 사용자 지정 속성을 추가한 후 조직이나 엔터프라이즈에서 해당 속성에 값이 설정된 모든 저장소가 자동으로 OIDC 토큰에 포함합니다.

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

설정 UI 또는 REST API를 사용해서 OIDC 토큰에 포함되는 사용자 지정 속성을 관리할 수 있습니다.

설정 UI 사용:

조직 또는 엔터프라이즈의 Actions OIDC 설정으로 이동해서 OIDC 토큰에 포함되는 사용자 지정 속성을 보고 구성합니다.
REST API 사용:

조직의 OIDC 토큰 클레임에 사용자 지정 속성을 추가하려면 적절한 OIDC 사용자 지정 속성 포함 엔드포인트에 POST 요청을 보냅니다. 예를 들어:
- 조직: POST /orgs/{org}/actions/oidc/customization/properties/repo
- 엔터프라이즈: POST /enterprises/{enterprise}/actions/oidc/customization/properties/repo 요청 파라미터와 전체 세부 정보는 OIDC 사용자 지정 속성 관리에 대한 REST API 문서를 참고하세요: REST API endpoints for GitHub Actions OIDC.

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

OIDC 구성에 사용자 지정 속성이 추가된 후 해당 속성에 값이 설정된 저장소는 토큰에 포함합니다. 다음 예시에서 두 개의 사용자 지정 속성(business_unit과 workspace_id)이 토큰에 포함됩니다:

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

repo_property_* 클레임을 클라우드 공급자의 신뢰 정책에서 조건으로 사용할 수 있습니다. 예시는 Example: Filtering on a repository custom property를 참고하세요.

조직 또는 저장소에 대한 subject 클레임 사용자 지정하기

보안, 규정 준수, 표준화를 개선하기 위해 표준 클레임을 필요한 접근 조건에 맞게 사용자 지정할 수 있습니다. 클라우드 공급자가 subject 클레임에 대한 조건을 지원한다면, sub 값이 "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main" 같은 재사용 가능한 워크플로의 경로와 일치하는지 확인하는 조건을 만들 수 있습니다. 정확한 형식은 클라우드 공급자의 OIDC 구성에 따라 다릅니다. GitHub에서 매칭 조건을 구성하려면 REST API를 사용해서 sub 클레임이 job_workflow_ref 같은 특정 사용자 지정 클레임을 항상 포함하도록 요구할 수 있습니다. REST API를 사용해서 OIDC subject 클레임에 대한 사용자 지정 템플릿을 적용할 수 있습니다. 예를 들어 OIDC 토큰 내의 sub 클레임이 job_workflow_ref 같은 특정 사용자 지정 클레임을 항상 포함하도록 요구할 수 있습니다. 자세한 내용은 REST API endpoints for GitHub Actions OIDC를 참고하세요.

[!NOTE] 조직 템플릿을 적용할 때는 저장소가 사용자 지정 조직 템플릿에 옵트인하지 않는 한 이미 OIDC를 사용하는 워크플로에는 영향을 주지 않습니다. 모든 저장소(기존 및 신규)에서 저장소 소유자는 저장소 레벨 REST API를 사용해서 use_default를 false로 설정하고 이 구성을 받도록 옵트인해야 합니다. 또는 저장소 소유자는 REST API를 사용해서 저장소에 특정한 다른 구성을 적용할 수 있습니다. 자세한 내용은 REST API endpoints for GitHub Actions OIDC를 참고하세요.

클레임을 사용자 지정하면 전체 sub 클레임에 대해 새 형식이 생성되며, 이는 Example subject claims에 설명된 토큰의 기본 미리 정의된 sub 형식을 대체합니다.

[!NOTE] sub 클레임은 저장소를 참조할 때 repository 대신 짧은 형태의 repo(예: repo:ORG-NAME/REPO-NAME)를 사용합니다. 컨텍스트 값 안의 :은 %3A로 대체됩니다. 불변 subject 클레임을 사용하는 저장소(GitHub Enterprise Server에서는 사용할 수 없음)의 경우, include_claim_keys로 클레임을 사용자 지정하더라도 owner_id와 repo_id는 항상 sub 클레임의 repo 세그먼트에 포함됩니다. 불변 형식에서 이 ID를 제거할 수 없습니다.

다음 예시 템플릿은 subject 클레임을 사용자 지정하는 다양한 방법을 보여줍니다. GitHub에서 이러한 설정을 구성하려면 관리자가 REST API를 사용해서 subject(sub) 클레임에 포함되어야 하는 클레임 목록을 지정합니다.

이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함하세요. 조직은 REST API endpoints for GitHub Actions OIDC를, 저장소는 REST API endpoints for GitHub Actions OIDC를 참고하세요.

subject 클레임을 사용자 지정하려면 REST API로 구성을 사용자 지정하기 전에 먼저 클라우드 공급자의 OIDC 구성에서 매칭 조건을 만들어야 합니다. 구성이 완료되면 새 잡이 실행될 때마다 해당 잡 중에 생성된 OIDC 토큰이 새 사용자 지정 템플릿을 따릅니다. 잡이 실행되기 전에 클라우드 공급자의 OIDC 구성에 매칭 조건이 없으면 클라우드 조건이 동기화되지 않을 수 있으므로 생성된 토큰이 클라우드 공급자에게 받아들여지지 않을 수 있습니다.

예시: 가시성과 소유자를 기준으로 저장소 허용하기

이 예시 템플릿은 repository_owner와 repository_visibility를 사용해서 sub 클레임이 새 형식을 갖도록 허용합니다:

{
   "include_claim_keys": [
       "repository_owner",
       "repository_visibility"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 repository_owner와 repository_visibility에 대한 특정 값을 포함하도록 요구하세요. 예: "sub": "repository_owner:monalisa:repository_visibility:private". 이 접근 방식은 클라우드 역할 접근을 조직이나 엔터프라이즈 내의 비공개 저장소로만 제한할 수 있게 해줍니다.

예시: 특정 소유자의 모든 저장소에 접근 허용하기

이 예시 템플릿은 repository_owner의 값만 있는 새 형식을 sub 클레임이 가질 수 있게 합니다.

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 repository_owner에 대한 특정 값을 포함하도록 요구하세요. 예: "sub": "repository_owner:monalisa"

예시: 재사용 가능한 워크플로 요구하기

이 예시 템플릿은 job_workflow_ref 클레임의 값을 포함하는 새 형식을 sub 클레임이 가질 수 있게 합니다. 이를 통해 엔터프라이즈가 재사용 가능한 워크플로를 사용해서 조직과 저장소 전반에 걸쳐 일관된 배포를 시행할 수 있습니다.

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 job_workflow_ref에 대한 특정 값을 포함하도록 요구하세요. 예: "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main".

예시: 재사용 가능한 워크플로와 다른 클레임 요구하기

다음 예시 템플릿은 특정 재사용 가능한 워크플로에 대한 요구 사항을 추가 클레임과 결합합니다.

이 예시는 또한 조건을 정의하기 위해 "context"를 사용하는 방법을 보여줍니다. 이는 기본 sub 형식에서 저장소 다음에 오는 부분입니다. 예를 들어 잡이 환경을 참조할 때 컨텍스트에는 environment:ENVIRONMENT-NAME이 포함됩니다.

{
   "include_claim_keys": [
       "repo",
       "context",
       "job_workflow_ref"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 repo, context, job_workflow_ref에 대한 특정 값을 포함하도록 요구하세요.

이 사용자 지정 템플릿은 sub가 다음 형식을 사용하도록 요구합니다: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH. 예: "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

예시: 특정 저장소에 접근 부여하기

이 예시 템플릿은 모든 브랜치/태그와 환경에 걸쳐 특정 저장소의 모든 워크플로에 클라우드 접근을 부여할 수 있게 합니다.

{
   "include_claim_keys": [
       "repo"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 필요한 값과 일치하는 repo 클레임을 요구하세요.

예시: 시스템 생성 GUID 사용하기

이 예시 템플릿은 엔터티의 이름 변경(예: 저장소 이름 변경) 간에 변경되지 않는 시스템 생성 GUID로 예측 가능한 OIDC 클레임을 활성화합니다.

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 필요한 값과 일치하는 repository_id 클레임을 요구하세요.

또는:

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 필요한 값과 일치하는 repository_owner_id 클레임을 요구하세요.

예시: `:`이 있는 컨텍스트 값

이 예시는 :이 있는 컨텍스트 값을 처리하는 방법을 보여줍니다. 예를 들어 잡이 production:eastus라는 환경을 참조할 때입니다.

{
   "include_claim_keys": [
       "environment",
       "repository_owner"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 environment와 repository_owner에 대한 특정 값을 포함하도록 요구하세요. 예: "sub": "environment:production%3Aeastus:repository_owner:octo-org".

예시: 저장소 사용자 지정 속성 필터링하기

이 예시 템플릿은 sub 클레임이 저장소 사용자 지정 속성 클레임을 포함하도록 허용합니다. OIDC 토큰에 포함된 사용자 지정 속성은 토큰에서 repo_property_ 접두사가 붙어 나타나지만, include_claim_keys 값은 토큰에 나타나는 전체 클레임 이름을 사용합니다.

{
   "include_claim_keys": [
       "repo_property_workspace_id"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 repo_property_workspace_id에 대한 특정 값을 포함하도록 요구하세요. 예: "sub": "repo_property_workspace_id:ws-abc123".

조직 템플릿 사용자 지정 재설정하기

이 예시 템플릿은 subject 클레임을 기본 형식으로 재설정합니다. 이 템플릿은 조직 레벨 사용자 지정 정책에서 효과적으로 옵트아웃합니다.

{
   "include_claim_keys": [
       "repo",
       "context"
   ]
}

클라우드 공급자의 OIDC 구성에서 sub 조건을 구성해서 클레임이 repo와 context에 대한 특정 값을 포함하도록 요구하세요.

저장소 템플릿 사용자 지정 재설정하기

조직의 모든 저장소는 (조직 및 저장소 레벨의) 사용자 지정된 sub 클레임 템플릿에 옵트인하거나 옵트아웃할 수 있습니다.

저장소를 옵트아웃하고 기본 sub 클레임 형식으로 재설정하려면 저장소 관리자가 REST API endpoints for GitHub Actions OIDC의 REST API 엔드포인트를 사용해야 합니다.

저장소가 기본 sub 클레임 형식을 사용하도록 구성하려면 다음 요청 본문과 함께 PUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API 엔드포인트를 사용하세요.

{
   "use_default": true
}

예시: 저장소가 조직 템플릿을 사용하도록 구성하기

조직이 사용자 지정된 sub 클레임 템플릿을 만들면 REST API를 사용해서 조직 내 저장소에 템플릿을 프로그래밍 방식으로 적용할 수 있습니다. 저장소 관리자는 조직 관리자가 만든 템플릿을 사용하도록 저장소를 구성할 수 있습니다.

저장소가 조직의 템플릿을 사용하도록 구성하려면 저장소 관리자가 다음 요청 본문과 함께 PUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API 엔드포인트를 사용해야 합니다. 자세한 내용은 REST API endpoints for GitHub Actions OIDC를 참고하세요.

{
   "use_default": false
}

OIDC 클레임 디버깅하기

클라우드 공급자와 통합하기 전에 전송될 클레임을 시각화하려면 github/actions-oidc-debugger 액션을 사용할 수 있습니다. 이 액션은 JWT를 요청하고 GitHub Actions에서 받은 JWT에 포함된 클레임을 출력합니다.

OIDC 토큰 요청을 위한 워크플로 권한

필수 권한

잡이나 워크플로는 GitHub의 OIDC 공급자가 JSON Web Token(JWT)을 만들 수 있도록 id-token: write 권한을 부여해야 합니다:
```
permissions:
  id-token: write
```
id-token: write 없이는 OIDC JWT ID 토큰을 요청할 수 없습니다. 이 설정은 OIDC 토큰을 가져오고 설정하는 것만 활성화하며 다른 리소스에 대한 write 접근을 부여하지 않습니다.

권한 설정

워크플로용 OIDC 토큰을 가져오려면 워크플로 레벨에서 권한을 설정하세요:

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

단일 잡용 OIDC 토큰을 가져오려면 해당 잡 내에서 권한을 설정하세요:
```
permissions:
  id-token: write # This is required for requesting the JWT
```
워크플로 요구 사항에 따라 추가 권한이 필요할 수 있습니다.

재사용 가능한 워크플로

호출자와 같은 사용자, 조직, 또는 엔터프라이즈가 소유한 재사용 가능한 워크플로의 경우 재사용 가능한 워크플로에서 생성된 OIDC 토큰은 호출자의 컨텍스트에서 접근할 수 있습니다.
엔터프라이즈나 조직 밖에 있는 재사용 가능한 워크플로의 경우 호출자 워크플로 또는 잡 레벨에서 id-token에 대한 permissions 설정을 write로 명시적으로 설정하세요. 이렇게 하면 의도된 호출자 워크플로에서만 OIDC 토큰을 사용할 수 있습니다.

OIDC 토큰 요청 방법

사용자 지정 액션은 다음을 사용해서 OIDC 토큰을 요청할 수 있습니다:

Actions 툴킷의 getIDToken() 메서드. 자세한 내용은 npm 패키지 문서의 OIDC Token을 참고하세요.
러너의 다음 환경 변수.

Variable Description

ACTIONS_ID_TOKEN_REQUEST_URL GitHub OIDC 공급자의 URL.

ACTIONS_ID_TOKEN_REQUEST_TOKEN OIDC 공급자에 대한 요청의 Bearer 토큰.

예를 들어:
```
curl -H "Authorization: bearer $ACTIO...OKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"
```

Variable	Description
`ACTIONS_ID_TOKEN_REQUEST_URL`	GitHub OIDC 공급자의 URL.
`ACTIONS_ID_TOKEN_REQUEST_TOKEN`	OIDC 공급자에 대한 요청의 Bearer 토큰.

OpenID Connect 참조(OpenID Connect reference)