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