OpenID 연결 참조

OIDC 토큰 클레임

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

다음과 같은 클레임이 OIDC 토큰에 포함됩니다.

표준 대상, 발급자, 주체 클레임

클레임	클레임 유형	설명
`aud`	사용자	기본적으로 이 URL은 리포지토리를 소유한 조직 등 리포지토리 소유자의 URL입니다. 도구 키트 명령을 사용하여 사용자 지정 대상을 설정할 수 있습니다: `core.getIDToken(audience)`
`iss`	Issuer	OIDC 토큰의 발급자: `https://token.actions.githubusercontent.com`
`sub`	제목	클라우드 공급자가 검증해야 하는 주체 클레임을 정의합니다. 이 설정은 액세스 토큰이 예측 가능한 방식으로만 할당되도록 하는 데 필수적입니다.

추가 표준 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`	워크플로 실행에서 끌어오기 요청의 대상 분기입니다.
`check_run_id`	현재 작업의 확인 실행 ID입니다.
`enterprise`	워크플로우가 실행되는 리포지토리를 포함하는 Enterprise의 이름입니다.
`enterprise_id`	워크플로우가 실행되는 리포지토리를 포함하는 Enterprise의 ID입니다.
`environment`	작업에 사용되는 환경의 이름입니다.

          `environment` 클레임이 포함된 경우(`include_claim_keys`를 통해 포함된 경우도 동일), 환경이 필요하며 반드시 제공해야 합니다.                   |

대체된 값 GHE.com에서

예상된 공급자의 클레임은 githubusercontent.com를 SUBDOMAIN.ghe.com로 대체해야 합니다. 여기서 SUBDOMAIN은 엔터프라이즈의 하위 도메인이고, 이는 GHE.com에 위치합니다.
엔터프라이즈 이름 또는 슬러그가 있는 경로를 포함하는 모든 URL의 경우 엔터프라이즈의 하위 도메인을 GHE.com대체해야 합니다.

예를 들어, 서브도메인이 octocorp인 경우 다음과 같이 대체됩니다.

OIDC 공급자가 지원하는 모든 GitHub 클레임을 보기 위한 URL은 https://token.actions.octocorp.ghe.com/.well-known/openid-configuration 다음과 같습니다.
OIDC 토큰에서 iss 값은 https://token.actions.octocorp.ghe.com로 대체됩니다.
Enterprise가 토큰을 수신할 수 있는 위치는 https://token.actions.octocorp.ghe.com/octocorp이며, issuer 값을 사용자 지정하기 위한 REST API 엔드포인트는 /enterprises/octocorp/actions/oidc/customization/issuer입니다.

클라우드 역할의 트러스트 조건을 정의하는 데 사용되는 OIDC 클레임입니다.

대상 클레임 및 주체 클레임은 일반적으로 클라우드 역할/리소스의 조건을 설정하여 GitHub 워크플로에 대한 액세스 범위를 지정할 때 함께 사용됩니다. * 대상: 기본적으로 이 값은 조직 또는 리포지토리 소유자의 URL을 사용합니다. 특정 조직의 워크플로만 클라우드 역할에 액세스할 수 있는 조건을 설정하는 데 사용할 수 있습니다. * 제목: 기본적으로 미리 정의된 형식을 가지며 조직, 리포지토리, 분기 또는 연결된 job 환경과 같은 워크플로에 대한 일부 주요 메타데이터의 연결입니다. 주체 클레임이 조합된 메타데이터로 어떻게 구성되는지 확인하려면 주체 클레임 예시를 참고하세요.

보다 세부적인 신뢰 조건이 필요한 경우 JWT에 포함된 발급자(iss) 및 주체(sub) 클레임을 사용자 지정할 수 있습니다. 더 자세한 내용은 토큰 클레임 사용자 지정을 참조하세요.

이러한 조건을 설정하는 데 사용할 수 있는 OIDC 토큰에서 지원되는 많은 추가 클레임이 있습니다. 또한 클라우드 공급자를 사용하면 액세스 토큰에 역할을 할당할 수 있으므로 보다 세부적인 권한을 지정할 수 있습니다.

참고

클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다.

주체 클레임 예제

다음 예제에서는 "주체"를 조건으로 사용하는 방법과 연결된 메타데이터에서 "주체"가 어셈블되는 방법을 설명합니다. 주체는 job컨텍스트의 정보를 사용하며, 특정 분기나 환경에서 실행되는 워크플로우의 요청에 대해서만 액세스 토큰 요청을 승인하도록 클라우드 공급자에게 지시합니다. 다음 섹션에서는 사용할 수 있는 몇 가지 일반적인 주체에 대해 설명합니다.

특정 환경에 대한 필터링

주체 클레임에는 작업이 환경을 참조할 때의 환경 이름이 포함됩니다.

특정 환경 이름을 필터링하는 주체를 구성할 수 있습니다. 이 예제에서 워크플로 실행은 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 이벤트를 필터링하는 주체를 구성할 수 있습니다. 이 예제에서 워크플로 실행은 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

클라우드 공급자에서 주체 구성

클라우드 공급자의 트러스트 관계에서 주체를 구성하려면 해당 트러스트 구성에 주체 문자열을 추가해야 합니다. 다음 예제에서는 다양한 클라우드 공급자가 서로 다른 방식으로 동일한 repo:octo-org/octo-repo:ref:refs/heads/demo-branch 주체를 수락하는 방법을 보여 줍니다.

클라우드 공급자	예제
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 볼트	`bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"`

특정 클라우드 공급자를 구성하는 방법에 대한 자세한 내용은 배포 보안 강화하기에서 제시하는 지침을 참조하세요.

토큰 클레임 사용자 지정

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

또는 issuer 클레임에 대한 audience 값을 사용자 지정할 수 있습니다.

        [엔터프라이즈의 `issuer` 값 사용자 지정](#customizing-the-issuer-value-for-an-enterprise) 및 [`audience` 값 사용자 지정](#customizing-the-audience-value)을 참조하세요.

주체(sub) 클레임에 조건을 설정하여 JWT 토큰이 특정 리포지토리, 재사용 워크플로우 또는 기타 지정된 소스에서만 생성되도록 요구함으로써 OIDC 구성 형식을 사용자 지정할 수 있습니다.

        `repository_id` 및 `repository_visibility` 등과 같은 추가 OIDC 토큰 클레임을 사용하여 세분화된 OIDC 정책을 정의할 수 있습니다. 
        [AUTOTITLE](/actions/concepts/security/openid-connect#understanding-the-oidc-token)을(를) 참조하세요.

리포지토리 사용자 지정 속성을 OIDC 토큰에 클레임으로 포함하여 특성 기반 액세스 제어 정책을 사용하도록 설정할 수 있습니다. OIDC 토큰에 리포지토리 사용자 지정 속성 포함을 참조하세요.

          `audience` 값 사용자 지정

워크플로에서 사용자 지정 작업을 사용하는 경우 해당 작업은 도구 키트를 GitHub Actions 사용하여 클레임에 대한 audience 사용자 지정 값을 제공할 수 있습니다. 일부 클라우드 공급자는 공식 로그인 액션에서 이를 사용하여 audience 클레임의 기본 값을 적용하기도 합니다. 예를 들어 GitHub Azure 로그인에 대한 작업은 기본 aud 값을 api://AzureADTokenExchange 제공하거나 워크플로에서 사용자 지정 aud 값을 설정할 수 있습니다. 도구 키트에 GitHub Actions 대한 자세한 내용은 설명서의 OIDC 토큰 섹션을 참조하세요.

작업에서 제공하는 기본 aud 값을 사용하고 싶지 않은 경우, audience 클레임에 대한 사용자 지정 값을 제공할 수 있습니다. 이를 통해 특정 리포지토리 또는 조직의 워크플로우만 클라우드 역할에 접근할 수 있도록 조건을 설정할 수 있습니다. 사용 중인 작업이 이를 지원하는 경우, 워크플로우에서 with 키워드를 사용하여 사용자 지정 aud 값을 작업에 전달할 수 있습니다. 자세한 내용은 메타데이터 구문 참조을(를) 참조하세요.

Enterprise의 `issuer` 값 사용자 지정

기본적으로 JWT는 https://token.actions.githubusercontent.com에 있는 GitHub의 OIDC 공급자에 의해 발급됩니다. 이 경로는 JWT의 iss 값을 사용하여 클라우드 공급자에게 표시됩니다.

OIDC 구성을 보안 강화하기 위해, Enterprise 관리자는 https://token.actions.githubusercontent.com/<enterpriseSlug>의 고유한 URL에서 토큰을 수신하도록 enterprise를 구성할 수 있으며, 여기서 <enterpriseSlug>는 enterprise의 슬러그 값으로 대체됩니다.

이 구성은 엔터프라이즈가 고유한 URL에서 OIDC 토큰을 수신하고 해당 URL의 토큰만 수락하도록 클라우드 공급자를 구성할 수 있음을 의미합니다. 이렇게 하면 엔터프라이즈의 리포지토리만 OIDC를 사용하여 클라우드 리소스에 액세스할 수 있습니다.

Enterprise에서 이 설정을 활성화하려면, enterprise 관리자가 /enterprises/{enterprise}/actions/oidc/customization/issuer 엔드포인트를 사용하고 요청 본문에 "include_enterprise_slug": true를 지정해야 합니다. 자세한 내용은 GitHub Actions OIDC에 대한 REST API 엔드포인트을(를) 참조하세요.

이 설정이 적용되면 JWT에 업데이트된 iss 값이 포함됩니다. 다음 예제에서 iss 키는 해당 octocat-inc 값으로 enterpriseSlug를 사용합니다.

{
  "jti": "6f4762ed-0758-4ccb-808d-ee3af5d723a8",
  "sub": "repo:octocat-inc/private-server:ref:refs/heads/main",
  "aud": "http://octocat-inc.example/octocat-inc",
  "enterprise": "octocat-inc",
  "enterprise_id": "123",
  "iss": "https://token.actions.githubusercontent.com/octocat-inc",
  "bf": 1755350653,
  "exp": 1755351553,
  "iat": 1755351253
}

OIDC 토큰에 리포지토리 사용자 지정 속성 포함

참고

이 기능은 현재 공개 미리 보기로 제공되며 변경될 수 있습니다.

조직 및 엔터프라이즈 관리자는 리포지토리 사용자 지정 속성을 선택하여 Actions OIDC 토큰에 클레임으로 포함할 수 있습니다. 사용자 지정 속성이 OIDC 구성에 추가되면 해당 속성에 대한 값이 설정된 조직 또는 엔터프라이즈의 모든 리포지토리가 자동으로 OIDC 토큰에 포함됩니다. 속성 이름이 접두 repo_property_사로 지정된 토큰에 나타납니다.

이렇게 하면 리포지토리 메타데이터에 직접 바인딩하는 ABAC(특성 기반 액세스 제어) 정책을 클라우드 공급자에 만들 수 있으므로 구성 드리프트를 줄이고 각 리포지토리에 대해 별도의 액세스 구성을 관리할 필요가 없습니다.

사용자 지정 속성을 포함하기 위한 필수 구성 요소

사용자 지정 속성은 조직 또는 엔터프라이즈 수준에서 이미 정의되어 있어야 합니다.
조직 관리자 또는 엔터프라이즈 관리자여야 합니다.
OIDC 구성에 사용자 지정 속성을 추가한 후에는 해당 속성에 대한 값이 설정된 조직 또는 엔터프라이즈의 모든 리포지토리가 자동으로 OIDC 토큰에 포함됩니다.

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

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

```
        **설정 UI 사용:** 
```
조직의 작업 OIDC 설정으로 이동하여 OIDC 토큰에 포함되는 사용자 지정 속성을 보고 구성합니다.
```
        **REST API 사용:**
```
조직의 OIDC 토큰 클레임에 사용자 지정 속성을 추가하려면 REST API를 사용합니다. 자세한 내용은 GitHub Actions OIDC에 대한 REST API 엔드포인트을(를) 참조하세요.

사용자 지정 속성이 있는 예제 토큰

사용자 지정 속성이 OIDC 구성에 추가되면, 해당 속성에 값이 설정된 리포지토리들이 그 값을 자신의 토큰에 포함하게 됩니다. 다음 예제에서는 사용자 지정 속성이 토큰에서 workspace_id로 표시됩니다 repo_property_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_workspace_id": "ws-abc123"
}

클라우드 공급자의 신뢰 정책에서 이러한 repo_property_* 클레임을 조건으로 사용할 수 있습니다. 예를 들어 예제: 리포지토리 사용자 지정 속성에 대한 필터링을 참조하세요.

조직 또는 리포지토리의 주체 클레임 사용자 지정.

보안, 규정 준수, 표준화를 강화하기 위해 필요한 접근 조건에 맞게 표준 클레임을 사용자 지정할 수 있습니다. 클라우드 공급자가 주체 클레임에 대한 조건을 지원하는 경우 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 엔드포인트을(를) 참조하세요.

참고

조직 템플릿이 적용되더라도, 해당 리포지토리가 사용자 지정 조직 템플릿 사용을 선택하지 않은 경우 이미 OIDC를 사용 중인 워크플로우에는 영향을 주지 않습니다. 모든 리포지토리(기존 및 신규 포함)에 대해, 리포지토리 소유자는 리포지토리 수준 REST API를 사용하여 use_default 값을 false로 설정함으로써 이 구성을 적용받도록 선택해야 합니다. 또는 리포지토리 소유자는 REST API를 사용해 리포지토리에 특화된 다른 구성을 적용할 수도 있습니다. 자세한 내용은 GitHub Actions OIDC에 대한 REST API 엔드포인트을(를) 참조하세요.

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

참고

          `sub` 클레임은 리포지토리를 참조할 때 `repo` 대신 `repo:ORG-NAME/REPO-NAME`의 축약 형식을 사용합니다(예: `repository`).

컨텍스트 값 내의 모든 : 항목이 %3A로 대체됩니다.

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

이 구성을 적용하려면 API 엔드포인트에 요청을 제출하고 요청 본문에 필요한 구성을 포함합니다. 조직의 경우 GitHub Actions OIDC에 대한 REST API 엔드포인트 항목을 참조하고 리포지토리는 GitHub Actions OIDC에 대한 REST API 엔드포인트 항목을 참조하세요.

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

예: 표시 유형 및 소유자에 따라 리포지토리 허용

이 예제 템플릿을 사용하면 sub 클레임이 repository_owner 및 repository_visibility를 사용하여 새 형식을 가질 수 있습니다.

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

클라우드 공급자의 OIDC 구성에서 클레임에 sub 및 repository_owner에 대한 특정 값을 포함해야 하는 repository_visibility 조건을 구성합니다. 예: "sub": "repository_owner:monalisa:repository_visibility:private". 이 접근 방식을 사용하면 클라우드 역할 액세스를 조직 또는 엔터프라이즈 내의 프라이빗 리포지토리로만 제한할 수 있습니다.

예: 특정 소유자에게 모든 리포지토리에 대한 액세스 허용

이 예제 템플릿을 사용하면 sub 클레임에 repository_owner의 값만 있는 새 형식을 사용할 수 있습니다.

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

클라우드 공급자의 OIDC 구성에서 클레임에 sub에 대한 특정 값을 포함해야 하는 repository_owner 조건을 구성합니다. 예: "sub": "repository_owner:monalisa"

예: 재사용 가능한 워크플로 필요

이 예제 템플릿을 사용하면 sub 클레임에 job_workflow_ref 클레임의 값이 포함된 새 형식을 갖도록 할 수 있습니다. 이를 통해 엔터프라이즈는 재사용 가능한 워크플로를 사용하여 조직 및 리포지토리에 일관된 배포를 적용할 수 있습니다.

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

예: 특정 리포지토리에 대한 액세스 권한 부여

이 예제 템플릿을 사용하면 모든 분기/태그 및 환경에서 특정 리포지토리의 모든 워크플로에 클라우드 액세스 권한을 부여할 수 있습니다. 보안을 강화하기 위해 엔터프라이즈의 값 사용자 지정issuer에 설명된 대로 이 템플릿을 엔터프라이즈에 대한 고유한 발급자 URL과 결합할 수 있습니다.

{
   "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".

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

이 예제 템플릿은 주체 클레임을 기본 형식으로 초기화합니다. 이 템플릿을 사용하면 조직 수준의 모든 사용자 지정 정책에서 사실상 제외됩니다.

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

클라우드 공급자의 OIDC 구성에서 클레임에 sub 및 repo에 대한 특정 값을 포함해야 하는 context 조건을 구성합니다.

리포지토리 템플릿 사용자 지정 재설정

조직의 모든 리포지토리는 (조직 및 리포지토리 수준의) 사용자 지정 sub 클레임 템플릿을 적용하거나 적용하지 않을 수 있습니다.

리포지토리를 옵트아웃하여 기본 sub 클레임 형식으로 되돌리려면, 리포지토리 관리자가 GitHub Actions OIDC에 대한 REST API 엔드포인트의 REST API 엔드포인트를 사용해야 합니다.

다음 요청 본문과 함께 sub REST API 엔드포인트를 사용하면 기본 PUT /repos/{owner}/{repo}/actions/oidc/customization/sub 클레임 형식을 사용하도록 리포지토리를 구성할 수 있습니다.

{
   "use_default": true
}

예시: 조직 템플릿을 사용하도록 리포지토리 구성

조직에서 사용자 지정 sub 클레임 템플릿을 생성한 후에는 REST API를 사용하여 해당 템플릿을 조직 내 리포지토리에 프로그래밍 방식으로 적용할 수 있습니다. 리포지토리 관리자는 조직 관리자에 의해 생성된 템플릿을 자신의 리포지토리에 적용하도록 구성할 수 있습니다.

리포지토리 관리자가 다음 요청 본문과 함께 PUT /repos/{owner}/{repo}/actions/oidc/customization/sub REST API 엔드포인트를 사용하면 조직의 템플릿을 사용하도록 리포지토리를 구성할 수 있습니다. 자세한 내용은 GitHub Actions OIDC에 대한 REST API 엔드포인트을(를) 참조하세요.

{
   "use_default": false
}

작업 또는 워크플로는 id-token: write 권한을 GitHub의 OIDC 공급자가 JSON Web Token(JWT)을 생성할 수 있도록 부여해야 합니다.
```
permissions:
  id-token: write
```

        `id-token: write`이 없으면 OIDC JWT ID 토큰을 요청할 수 없습니다. 이 설정은 OIDC 토큰을 가져오고 설정하는 기능만 활성화하며, 다른 리소스에 대한 쓰기 권한은 부여하지 않습니다.

권한 설정

워크플로우에 대한 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
```
워크플로우 요구 사항에 따라 추가 권한이 필요할 수 있습니다.

재사용 가능한 워크플로

호출자와 동일한 사용자, 조직 또는 Enterprise가 소유한 재사용 워크플로우의 경우, 재사용 워크플로우에서 생성된 OIDC 토큰은 호출자의 컨텍스트에서 접근할 수 있습니다.
Enterprise 또는 조직 외부의 재사용 워크플로우를 사용하는 경우, 호출자 워크플로우 또는 작업 수준에서 permissions 설정의 id-token 값을 명시적으로 write으로 설정하세요. 이 설정은 OIDC 토큰이 의도된 호출자 워크플로우에서만 사용 가능하도록 보장합니다.

OIDC 토큰을 요청하는 방법

사용자 지정 작업은 다음을 사용하여 OIDC 토큰을 요청할 수 있습니다.

작업 도구 키트의 getIDToken() 방법. 자세한 내용은 npm 패키지 문서의 OIDC 토큰을 참고하세요.

러너에서 환경 변수는 다음과 같습니다.

변수	설명
`ACTIONS_ID_TOKEN_REQUEST_URL`

        GitHub의 OIDC 공급자의 URL입니다. |

| ACTIONS_ID_TOKEN_REQUEST_TOKEN | OIDC 공급자에 대한 요청의 전달자 토큰 |

예를 들면 다음과 같습니다.

Shell

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

이 기사에서