# OpenID 연결 참조 OIDC(OpenID Connect)를 사용하여 클라우드 공급자의 워크플로를 인증 GitHub Actions하는 방법에 대한 정보를 찾습니다. ## OIDC 토큰 클레임 GitHub의 OIDC 공급자가 지원하는 모든 클레임을 확인하려면, `claims_supported` 항목을 `https://HOSTNAME/_services/token/.well-known/openid-configuration`에서 검토하세요. 다음과 같은 클레임이 OIDC 토큰에 포함됩니다. ### 표준 대상, 발급자, 주체 클레임 | 클레임 | 클레임 유형 | 설명 | | ----- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aud` | 사용자 | 기본적으로 이 URL은 리포지토리를 소유한 조직 등 리포지토리 소유자의 URL입니다. 도구 키트 명령을 사용하여 사용자 지정 대상을 설정할 수 있습니다: [`core.getIDToken(audience)`](https://www.npmjs.com/package/@actions/core/v/1.6.0) | | `iss` | Issuer | OIDC 토큰의 발급자: `https://HOSTNAME/_services/token` | | `sub` | 제목 | 클라우드 공급자가 검증해야 하는 주체 클레임을 정의합니다. 이 설정은 액세스 토큰이 예측 가능한 방식으로만 할당되도록 하는 데 필수적입니다. 변경할 수 없는 주체 클레임을 사용하는 리포지토리의 `sub` 형식에는 변경할 수 없는 소유자 및 리포지토리 ID가 포함되어 있습니다(이는 GitHub Enterprise Server 형식에서는 사용할 수 없습니다). | ### 추가 표준 JOSE 헤더 매개변수 및 클레임 | 헤더 매개 변수 | 매개 변수 형식 | 설명 | | -------- | -------- | -------------------------------------- | | `alg` | 알고리즘 | OIDC 공급자가 사용하는 알고리즘입니다. | | `kid` | 키 식별자 | OIDC 토큰용 고유 키입니다. | | `typ` | Type | 토큰의 유형을 설명합니다. JWT(JSON Web Token)입니다. | | 클레임 | 클레임 유형 | 설명 | | ----- | ---------- | ------------------------------- | | `exp` | 만료 시간 | JWT의 만료 시간을 나타냅니다. | | `iat` | 발급 시간 | JWT가 발급된 시간을 나타냅니다. | | `jti` | JWT 토큰 식별자 | OIDC 토큰의 고유 식별자입니다. | | `nbf` | 유효 시작 시점 | JWT는 이 시점 이전에는 유효하게 사용할 수 없습니다. | ### GitHub에서 제공한 사용자 지정 클레임 | 클레임 | 설명 | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actor` | 워크플로 실행을 시작한 개인 계정입니다. | | `actor_id` | 워크플로 실행을 시작한 개인 계정의 ID입니다. | | `base_ref` | 워크플로 실행에서 끌어오기 요청의 대상 분기입니다. | | | | | | | | `enterprise` | 워크플로우가 실행되는 리포지토리를 포함하는 Enterprise의 이름입니다. | | | | | | | | `enterprise_id` | 워크플로우가 실행되는 리포지토리를 포함하는 Enterprise의 ID입니다. | | | | | `environment` | 작업에 사용되는 환경의 이름입니다. | | `environment` 클레임이 포함된 경우(`include_claim_keys`를 통해 포함된 경우도 동일), 환경이 필요하며 반드시 제공해야 합니다. | | | `event_name` | 워크플로 실행을 트리거한 이벤트의 이름입니다. | | `head_ref` | 워크플로 실행에서 끌어오기 요청의 소스 분기입니다. | | `job_workflow_ref` | 재사용 워크플로우를 사용하는 작업의 경우, 재사용 워크플로우에 대한 참조 경로입니다. 자세한 내용은 [재사용 가능한 워크플로에서 OpenID Connect 사용](/ko/enterprise-server@3.22/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows)을(를) 참조하세요. | | `job_workflow_sha` | 재사용 워크플로우를 사용하는 작업의 경우, 재사용 워크플로우 파일에 대한 커밋 SHA입니다. | | `ref` | | | *(참조)* 워크플로우 실행을 트리거한 Git 참조입니다. | | | `ref_type` | | | `ref`의 유형(예: "branch")입니다. | | | `repository_visibility` | 워크플로가 실행 중인 리포지토리의 표시 여부입니다. 값 `internal`, `private` 또는 `public` 중에서 수락합니다. | | `repository` | 워크플로가 실행 중인 리포지토리입니다. | | `repository_id` | 워크플로가 실행 중인 리포지토리의 ID입니다. | | `repository_owner` | | | `repository`가 저장되는 조직의 이름입니다. | | | `repository_owner_id` | | | `repository`가 저장되는 조직의 ID입니다. | | | | | | `run_id` | 워크플로를 트리거한 워크플로 실행의 ID입니다. | | `run_number` | 이 워크플로가 실행된 횟수입니다. | | `run_attempt` | 이 워크플로가 다시 시도된 횟수입니다. | | `runner_environment` | 작업에 사용되는 러너의 유형입니다. 값 `github-hosted` 또는 `self-hosted` 중에서 수락합니다. | | `workflow` | 워크플로의 이름입니다. | | `workflow_ref` | 워크플로의 참조 경로입니다. 예를 들어 `octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch`입니다. | | `workflow_sha` | 워크플로 파일의 커밋 SHA입니다. | ## 클라우드 역할의 트러스트 조건을 정의하는 데 사용되는 OIDC 클레임입니다. 대상 클레임 및 주체 클레임은 일반적으로 클라우드 역할/리소스의 조건을 설정하여 GitHub 워크플로에 대한 액세스 범위를 지정할 때 함께 사용됩니다. * **대상:** 기본적으로 이 값은 조직 또는 리포지토리 소유자의 URL을 사용합니다. 특정 조직의 워크플로만 클라우드 역할에 액세스할 수 있는 조건을 설정하는 데 사용할 수 있습니다. * **제목:** 기본적으로 미리 정의된 형식을 가지며 조직, 리포지토리, 분기 또는 연결된 GitHub 환경과 같은 `job` 워크플로에 대한 일부 주요 메타데이터의 연결입니다. 주체 클레임이 조합된 메타데이터로 어떻게 구성되는지 확인하려면 [주체 클레임 예시](#example-subject-claims)를 참고하세요. 보다 세부적인 신뢰 조건이 필요한 경우 JWT에 주체(`sub`) 클레임. 더 자세한 내용은 [토큰 클레임 사용자 지정](#customizing-the-token-claims)을 참조하세요. 이러한 조건을 설정하는 데 사용할 수 있는 OIDC 토큰에서 지원되는 많은 추가 클레임이 있습니다. 또한 클라우드 공급자를 사용하면 액세스 토큰에 역할을 할당할 수 있으므로 보다 세부적인 권한을 지정할 수 있습니다. > \[!NOTE] > 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의**해야 합니다**. ## 주체 클레임 예제 다음 예제에서는 "주체"를 조건으로 사용하는 방법과 연결된 메타데이터에서 "주체"가 어셈블되는 방법을 설명합니다. [주체](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)는 [`job`컨텍스트](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#job-context)의 정보를 사용하며, 특정 분기나 환경에서 실행되는 워크플로우의 요청에 대해서만 액세스 토큰 요청을 승인하도록 클라우드 공급자에게 지시합니다. 다음 섹션에서는 사용할 수 있는 몇 가지 일반적인 주체에 대해 설명합니다. ### 특정 환경에 대한 필터링 주체 클레임에는 작업이 환경을 참조할 때의 환경 이름이 포함됩니다. 특정 [환경](/ko/enterprise-server@3.22/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) 이름을 필터링하는 주체를 구성할 수 있습니다. 이 예제에서 워크플로 실행은 `Production` 조직이 소유한 `octo-repo`라는 리포지토리에 `octo-org`이라는 환경이 있는 작업에서 시작되어야 합니다. * 구문: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME` * 예: `repo:octo-org/octo-repo:environment:Production` ### `pull_request` 이벤트 필터링 워크플로가 끌어오기 요청 이벤트에 의해 트리거되는 경우 주체 클레임에 `pull_request` 문자열이 포함됩니다. 단, 작업에서 환경을 참조하지 않아야만 합니다. 사용자는 [`pull_request`](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request) 이벤트를 필터링하는 주체를 구성할 수 있습니다. 이 예제에서 워크플로 실행은 `pull_request` 조직이 소유한 `octo-repo`라는 리포지토리의 `octo-org` 이벤트에 의해 트리거되어야 합니다. * 구문: `repo:ORG-NAME/REPO-NAME:pull_request` * 예: `repo:octo-org/octo-repo:pull_request` ### 특정 분기 필터링 주체 클레임에는 워크플로의 분기 이름이 포함됩니다. 단, 작업이 환경을 참조하지 않고 워크플로가 끌어오기 요청 이벤트에 의해 트리거되지 않는 경우에만 해당됩니다. 특정 분기 이름을 필터링하는 주체를 구성할 수 있습니다. 이 예제에서 워크플로 실행은 `demo-branch` 조직이 소유한 `octo-repo`라는 리포지토리에 `octo-org`라는 분기에서 시작되어야 합니다. * 구문: `repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME` * 예: `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` ### 특정 태그 필터링 주체 클레임에는 워크플로의 태그 이름이 포함됩니다. 단, 작업이 환경을 참조하지 않고 워크플로가 끌어오기 요청 이벤트에 의해 트리거되지 않는 경우에만 해당됩니다. 특정 태그를 필터링하는 주체를 만들 수 있습니다. 이 예제에서 워크플로 실행은 `demo-tag` 조직이 소유한 `octo-repo`라는 리포지토리의 `octo-org` 태그로 시작되어야 합니다. * 구문: `repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME` * 예: `repo:octo-org/octo-repo:ref:refs/tags/demo-tag` ### 포함된 메타데이터 필터링 `:` 메타데이터 값 내의 모든 `:`는 주체 클레임으로 `%3A`으로 대체됩니다. 콜론을 포함하는 메타데이터를 포함하는 제목을 구성할 수 있습니다. 이 예제에서 워크플로 실행은 `Production:V1` 조직이 소유한 `octo-repo`라는 리포지토리에 `octo-org`이라는 환경이 있는 작업에서 시작되어야 합니다. * 구문: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME` * 예: `repo:octo-org/octo-repo:environment:Production%3AV1` ## 변경할 수 없는 주체 클레임 OIDC(OpenID Connect) 사양을 사용하려면 주체(`sub`) 클레임이 로컬에서 고유해야 하며 다시 할당되지 않습니다. 이전에는 기본 `sub` 형식이 조직 및 리포지토리 이름만 사용했습니다. 네임스페이스를 재활용한 경우 다른 소유자가 동일한 주체 값을 만들 수 있습니다. 이 시나리오를 방지하기 위해 2026년 7월 15일 이후에 만든 리포지토리는 이제 소유자 ID와 리포지토리 ID를 모두 포함하는 변경할 수 없는 기본 주체 형식을 사용합니다. 이 롤아웃에는 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` `@` 사용자 이름 또는 리포지토리 이름에 `@` 표시할 수 없으므로 GitHub 이름과 ID 사이에 구분 기호가 사용됩니다. 변경할 수 없는 주체 클레임을 옵트인하지 않는 한 2026년 7월 15일 이전에 만든 리포지토리는 이전 형식을 유지합니다. OIDC 설정 UI 또는 REST API를 사용하여 조직 또는 리포지토리 수준에서 옵트인할 수 있습니다. 2026년 7월 15일 이후에 리포지토리의 이름 바꾸기 및 전송도 변경할 수 없는 제목 형식으로 이동합니다. ## 클라우드 공급자에서 주체 구성 클라우드 공급자의 트러스트 관계에서 주체를 구성하려면 해당 트러스트 구성에 주체 문자열을 추가해야 합니다. 다음 예제에서는 다양한 클라우드 공급자가 서로 다른 방식으로 동일한 `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` 주체를 수락하는 방법을 보여 줍니다. | 클라우드 공급자 | 예제 | | --------------------- | -------------------------------------------------------------------------------------- | | Amazon Web Services | `"HOSTNAME/_services/token: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 볼트 | `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | 2026년 7월 15일 이후에 생성되었거나 불변 주체 클레임을 사용하도록 옵트인한 리포지토리의 경우, 불변 예제에 나와 있는 대로 `sub` 클레임에는 `owner_id` 및 `repo_id`가 포함됩니다. 리포지토리에서 사용하는 형식과 일치하도록 신뢰 정책을 업데이트합니다. 변경할 수 없는 클레임은 GitHub Enterprise Server에서 사용할 수 없습니다. | 클라우드 공급자 | 변경할 수 없는 형식 예제 | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | 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 볼트 | `bound_subject="repo:octo-org@123456/octo-repo@456789:ref:refs/heads/demo-branch"` | 특정 클라우드 공급자를 구성하는 방법에 대한 자세한 내용은 [배포 보안 강화하기](/ko/enterprise-server@3.22/actions/how-tos/secure-your-work/security-harden-deployments)에서 제시하는 지침을 참조하세요. ## 토큰 클레임 사용자 지정 JWT에 포함된 클레임을 사용자 지정하여 OIDC 구성의 보안을 강화할 수 있습니다. 이러한 사용자 지정 기능을 통해 워크플로우가 클라우드에 호스팅된 리소스에 접근하도록 허용할 때, 클라우드 역할에 대해 더 세분화된 트러스트 조건을 정의할 수 있습니다. * 또는 `audience` 값을 사용자 지정할 수 있습니다. [`audience` 값 사용자 지정](#customizing-the-audience-value)을 참조하세요. * 주체(`sub`) 클레임에 조건을 설정하여 JWT 토큰이 특정 리포지토리, 재사용 워크플로우 또는 기타 지정된 소스에서만 생성되도록 요구함으로써 OIDC 구성 형식을 사용자 지정할 수 있습니다. * `repository_id` 및 `repository_visibility` 등과 같은 추가 OIDC 토큰 클레임을 사용하여 세분화된 OIDC 정책을 정의할 수 있습니다. [OpenID Connect](/ko/enterprise-server@3.22/actions/concepts/security/openid-connect#understanding-the-oidc-token)을(를) 참조하세요. ### `audience` 값 사용자 지정 워크플로에서 사용자 지정 작업을 사용하는 경우 해당 작업은 도구 키트를 GitHub Actions 사용하여 클레임에 대한 `audience` 사용자 지정 값을 제공할 수 있습니다. 일부 클라우드 공급자는 공식 로그인 액션에서 이를 사용하여 `audience` 클레임의 기본 값을 적용하기도 합니다. 예를 들어 [GitHub Azure 로그인에 대한 작업](https://github.com/Azure/login/blob/master/action.yml)은 기본 `aud` 값을 `api://AzureADTokenExchange` 제공하거나 워크플로에서 사용자 지정 `aud` 값을 설정할 수 있습니다. 도구 키트에 GitHub Actions 대한 자세한 내용은 설명서의 [OIDC 토큰](https://github.com/actions/toolkit/tree/main/packages/core#oidc-token) 섹션을 참조하세요. 작업에서 제공하는 기본 `aud` 값을 사용하고 싶지 않은 경우, `audience` 클레임에 대한 사용자 지정 값을 제공할 수 있습니다. 이를 통해 특정 리포지토리 또는 조직의 워크플로우만 클라우드 역할에 접근할 수 있도록 조건을 설정할 수 있습니다. 사용 중인 작업이 이를 지원하는 경우, 워크플로우에서 `with` 키워드를 사용하여 사용자 지정 `aud` 값을 작업에 전달할 수 있습니다. 자세한 내용은 [메타데이터 구문 참조](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/metadata-syntax#inputs)을(를) 참조하세요. ### 조직 또는 리포지토리의 주체 클레임 사용자 지정. 보안, 규정 준수, 표준화를 강화하기 위해 필요한 접근 조건에 맞게 표준 클레임을 사용자 지정할 수 있습니다. 클라우드 공급자가 주체 클레임에 대한 조건을 지원하는 경우 `sub`값이 재사용 가능한 워크플로의 경로와 일치하는지 여부를 확인하는 조건을 만들 수 있습니다(예: `"job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"`). 정확한 형식은 클라우드 공급자의 OIDC 구성에 따라 달라집니다. 일치 조건을 GitHub구성하려면 REST API를 사용하여 클레임에 `sub` 항상 특정 사용자 지정 클레임(예: `job_workflow_ref`)을 포함하도록 요구할 수 있습니다. OIDC subject 클레임에 대한 사용자 지정 템플릿은 REST API를 사용하여 적용할 수 있습니다. 예를 들어, OIDC 토큰의 `sub` 클레임에 `job_workflow_ref`와 같은 특정 사용자 지정 클레임이 항상 포함되도록 요구할 수 있습니다. 자세한 내용은 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc)을(를) 참조하세요. > \[!NOTE] > 조직 템플릿이 적용되더라도, 해당 리포지토리가 사용자 지정 조직 템플릿 사용을 선택하지 않은 경우 이미 OIDC를 사용 중인 워크플로우에는 영향을 주지 않습니다. 모든 리포지토리(기존 및 신규 포함)에 대해, 리포지토리 소유자는 리포지토리 수준 REST API를 사용하여 `use_default` 값을 `false`로 설정함으로써 이 구성을 적용받도록 선택해야 합니다. 또는 리포지토리 소유자는 REST API를 사용해 리포지토리에 특화된 다른 구성을 적용할 수도 있습니다. 자세한 내용은 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)을(를) 참조하세요. 클레임을 사용자 지정하면 전체 `sub` 클레임의 형식이 새로 정의되며, 이는 `sub`에 설명된 토큰의 기본 미리 정의된 [](#example-subject-claims) 형식을 대체합니다. > \[!NOTE] > > ``` > `sub` 클레임은 리포지토리를 참조할 때 `repo` 대신 `repo:ORG-NAME/REPO-NAME`의 축약 형식을 사용합니다(예: `repository`). 컨텍스트 값 내의 모든 `:` 항목이 `%3A`로 대체됩니다. > ``` > > 변경 불가능한 주체 클레임을 사용하는 리포지토리의 경우(GitHub Enterprise Server에서 사용할 수 없는 경우), 클레임을 `owner_id` 및 `repo_id`로 사용자 지정하더라도 `repo` 세그먼트에 `sub` 및 `include_claim_keys`가 항상 포함됩니다. 변경할 수 없는 형식에서는 이러한 ID를 제거할 수 없습니다. 다음 예제 템플릿에서는 제목 클레임을 사용자 지정하는 다양한 방법을 보여 줍니다. 이러한 설정을 GitHub구성하려면 관리자는 REST API를 사용하여 주체(`sub`) 클레임에 포함되어야 하는 클레임 목록을 지정합니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. 주체 클레임을 사용자 지정하려면 먼저 REST API를 사용하여 구성을 사용자 지정하기 전에 클라우드 공급자의 OIDC 구성에서 일치하는 조건을 만들어야 합니다. 구성이 완료되면 새 작업이 실행될 때마다 해당 작업 중에 생성된 OIDC 토큰이 새 사용자 지정 템플릿을 따릅니다. 작업이 실행되기 전에 일치하는 조건이 클라우드 공급자의 OIDC 구성에 없는 경우 클라우드 조건이 동기화되지 않을 수 있으므로 생성된 토큰이 클라우드 공급자에 의해 수락되지 않을 수 있습니다. #### 예: 표시 유형 및 소유자에 따라 리포지토리 허용 이 예제 템플릿을 사용하면 `sub` 클레임이 `repository_owner` 및 `repository_visibility`를 사용하여 새 형식을 가질 수 있습니다. ```json { "include_claim_keys": [ "repository_owner", "repository_visibility" ] } ``` 클라우드 공급자의 OIDC 구성에서 클레임에 `sub` 및 `repository_owner`에 대한 특정 값을 포함해야 하는 `repository_visibility` 조건을 구성합니다. 예: `"sub": "repository_owner:monalisa:repository_visibility:private"`. 이 접근 방식을 사용하면 클라우드 역할 액세스를 조직 또는 엔터프라이즈 내의 프라이빗 리포지토리로만 제한할 수 있습니다. #### 예: 특정 소유자에게 모든 리포지토리에 대한 액세스 허용 이 예제 템플릿을 사용하면 `sub` 클레임에 `repository_owner`의 값만 있는 새 형식을 사용할 수 있습니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. ```json { "include_claim_keys": [ "repository_owner" ] } ``` 클라우드 공급자의 OIDC 구성에서 클레임에 `sub`에 대한 특정 값을 포함해야 하는 `repository_owner` 조건을 구성합니다. 예: `"sub": "repository_owner:monalisa"` #### 예: 재사용 가능한 워크플로 필요 이 예제 템플릿을 사용하면 `sub` 클레임에 `job_workflow_ref` 클레임의 값이 포함된 새 형식을 갖도록 할 수 있습니다. 이를 통해 엔터프라이즈는 재사용 가능한 워크플로를 사용하여 조직 및 리포지토리에 일관된 배포를 적용할 수 있습니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. ```json { "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"`. #### 예: 재사용 가능한 워크플로 및 기타 클레임 필요 다음 예제 템플릿은 재사용 가능한 특정 워크플로의 요구 사항을 추가 클레임과 결합합니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. 이 예제에서는 `"context"`를 사용하여 조건을 정의하는 데 사용하는 방법도 보여 줍니다. 이는 기본 `sub` 형식에서 리포지토리 뒤에 이어지는 부분입니다. 예를 들어 작업이 환경을 참조할 때 컨텍스트에는 `environment:ENVIRONMENT-NAME`이 포함됩니다. ```json { "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"` #### 예: 특정 리포지토리에 대한 액세스 권한 부여 이 예제 템플릿을 사용하면 모든 분기/태그 및 환경에서 특정 리포지토리의 모든 워크플로에 클라우드 액세스 권한을 부여할 수 있습니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. ```json { "include_claim_keys": [ "repo" ] } ``` 클라우드 공급자의 OIDC 구성에서 필요한 값과 일치하는 `sub` 클레임을 요구하도록 `repo` 조건을 구성합니다. #### 예: 시스템 생성 GUID 사용 이 예제 템플릿은 엔터티 이름 바꾸기(예: 리포지토리 이름 바꾸기) 간에 변경되지 않는 시스템 생성 GUID를 사용하여 예측 가능한 OIDC 클레임을 사용하도록 설정합니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. ```json { "include_claim_keys": [ "repository_id" ] } ``` 클라우드 공급자의 OIDC 구성에서 필요한 값과 일치하는 `sub` 클레임을 요구하도록 `repository_id` 조건을 구성합니다. 또는: ```json { "include_claim_keys": [ "repository_owner_id" ] } ``` 클라우드 공급자의 OIDC 구성에서 필요한 값과 일치하는 `sub` 클레임을 요구하도록 `repository_owner_id` 조건을 구성합니다. #### 예시: `:`이 있는 컨텍스트 값 이 예시는 `:`을 사용하여 컨텍스트 값을 처리하는 방법을 보여줍니다. 예를 들어, 작업이 `production:eastus`라는 환경을 참조하는 경우입니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. ```json { "include_claim_keys": [ "environment", "repository_owner" ] } ``` 클라우드 공급자의 OIDC 구성에서 `sub` 조건을 설정하여, 클레임에 `environment`와 `repository_owner`에 대한 특정 값이 포함되도록 요구하세요. 예: `"sub": "environment:production%3Aeastus:repository_owner:octo-org"`. #### 조직 템플릿 사용자 지정 재설정 이 예제 템플릿은 주체 클레임을 기본 형식으로 초기화합니다. 이 템플릿을 사용하면 조직 수준의 모든 사용자 지정 정책에서 사실상 제외됩니다. 이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization) 항목을 참조하고 리포지토리는 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository) 항목을 참조하세요. ```json { "include_claim_keys": [ "repo", "context" ] } ``` 클라우드 공급자의 OIDC 구성에서 클레임에 `sub` 및 `repo`에 대한 특정 값을 포함해야 하는 `context` 조건을 구성합니다. #### 리포지토리 템플릿 사용자 지정 재설정 조직의 모든 리포지토리는 (조직 및 리포지토리 수준의) 사용자 지정 `sub` 클레임 템플릿을 적용하거나 적용하지 않을 수 있습니다. 리포지토리를 옵트아웃하여 기본 `sub` 클레임 형식으로 되돌리려면, 리포지토리 관리자가 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)의 REST API 엔드포인트를 사용해야 합니다. 다음 요청 본문과 함께 `sub` REST API 엔드포인트를 사용하면 기본 `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub` 클레임 형식을 사용하도록 리포지토리를 구성할 수 있습니다. ```json { "use_default": true } ``` #### 예시: 조직 템플릿을 사용하도록 리포지토리 구성 조직에서 사용자 지정 `sub` 클레임 템플릿을 생성한 후에는 REST API를 사용하여 해당 템플릿을 조직 내 리포지토리에 프로그래밍 방식으로 적용할 수 있습니다. 리포지토리 관리자는 조직 관리자에 의해 생성된 템플릿을 자신의 리포지토리에 적용하도록 구성할 수 있습니다. 리포지토리 관리자가 다음 요청 본문과 함께 `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub` REST API 엔드포인트를 사용하면 조직의 템플릿을 사용하도록 리포지토리를 구성할 수 있습니다. 자세한 내용은 [GitHub Actions OIDC에 대한 REST API 엔드포인트](/ko/enterprise-server@3.22/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)을(를) 참조하세요. ```json { "use_default": false } ``` ## OIDC 클레임 디버깅하기 클라우드 공급자와 통합하기 전에, [`github/actions-oidc-debugger`](https://github.com/github/actions-oidc-debugger) 작업을 사용하여 전송될 클레임을 시각화할 수 있습니다. 이 작업은 JWT를 요청하고 JWT GitHub Actions에 포함된 클레임을 출력합니다. ## OIDC 토큰을 요청하는 워크플로우 권한 ### 필요한 권한 * 작업 또는 워크플로는 [`id-token: write`](/ko/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#permissions) 권한을 GitHub의 OIDC 공급자가 JSON Web Token(JWT)을 생성할 수 있도록 부여해야 합니다. ```yaml permissions: id-token: write ``` * `id-token: write`이 없으면 OIDC JWT ID 토큰을 요청할 수 없습니다. 이 설정은 OIDC 토큰을 가져오고 설정하는 기능만 활성화하며, 다른 리소스에 대한 쓰기 권한은 부여하지 않습니다. ### 권한 설정 * 워크플로우에 대한 OIDC 토큰을 가져오기 위해서는 워크플로 수준에서 권한을 설정해야 합니다. ```yaml permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout ``` * 단일 작업에서 OIDC 토큰을 가져오려면, 해당 작업 내에서 권한을 설정하세요. ```yaml permissions: id-token: write # This is required for requesting the JWT ``` * 워크플로우 요구 사항에 따라 추가 권한이 필요할 수 있습니다. ### 재사용 가능한 워크플로 * 호출자와 동일한 사용자, 조직 또는 Enterprise가 소유한 재사용 워크플로우의 경우, 재사용 워크플로우에서 생성된 OIDC 토큰은 호출자의 컨텍스트에서 접근할 수 있습니다. * Enterprise 또는 조직 외부의 재사용 워크플로우를 사용하는 경우, 호출자 워크플로우 또는 작업 수준에서 `permissions` 설정의 `id-token` 값을 명시적으로 `write`으로 설정하세요. 이 설정은 OIDC 토큰이 의도된 호출자 워크플로우에서만 사용 가능하도록 보장합니다. ## OIDC 토큰을 요청하는 방법 사용자 지정 작업은 다음을 사용하여 OIDC 토큰을 요청할 수 있습니다. * 작업 도구 키트의 `getIDToken()` 방법. 자세한 내용은 npm 패키지 문서의 [OIDC 토큰](https://www.npmjs.com/package/@actions/core/v/1.6.0#oidc-token)을 참고하세요. * 러너에서 환경 변수는 다음과 같습니다. | 변수 | 설명 | | ------------------------------ | -- | | `ACTIONS_ID_TOKEN_REQUEST_URL` | | GitHub의 OIDC 공급자의 URL입니다. | \| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | OIDC 공급자에 대한 요청의 전달자 토큰 | 예를 들면 다음과 같습니다. ```shell copy curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" ```