OpenID Connect를 사용한 보안 강화 정보

OpenID Connect 개요

GitHub Actions 워크플로는 종종 소프트웨어를 배포하거나 클라우드의 서비스를 사용하기 위해 클라우드 공급자(예시: AWS, Azure, GCP 또는 HashiCorp Vault)에 액세스하도록 설계되었습니다. 워크플로가 이러한 리소스에 액세스하기 전에 클라우드 공급자에게 암호 또는 토큰과 같은 자격 증명을 제공합니다. 이러한 자격 증명은 일반적으로 GitHub에 비밀로 저장되며 워크플로는 실행될 때마다 클라우드 공급자에게 이 비밀을 제공합니다.

그러나 하드 코딩된 비밀을 사용하려면 클라우드 공급자에서 자격 증명을 만든 다음, GitHub에서 비밀로 복제해야 합니다.

OIDC(OpenID Connect)를 사용하면 클라우드 공급자에게 직접 수명이 짧은 액세스 토큰을 요청하도록 워크플로를 구성하여 다른 접근 방식을 취할 수 있습니다. 또한 클라우드 공급자는 OIDC를 지원해야 하며, 액세스 토큰을 요청할 수 있는 워크플로를 제어하는 트러스트 관계를 구성해야 합니다. 현재 OIDC를 지원하는 공급자로는 Amazon Web Services, Azure, Google Cloud Platform 및 HashiCorp Vault 등이 있습니다.

OIDC 사용의 장점

OIDC 토큰을 사용하도록 워크플로를 업데이트하면 다음과 같은 적절한 보안 사례를 채택할 수 있습니다.

• 클라우드 비밀 없음: 수명이 긴 GitHub 비밀로 클라우드 자격 증명을 복제할 필요가 없습니다. 대신 클라우드 공급자에서 OIDC 트러스트를 구성한 다음, 워크플로를 업데이트하여 OIDC를 통해 클라우드 공급자로부터 단기 액세스 토큰을 요청할 수 있습니다.
• 인증 및 권한 부여 관리: 워크플로가 자격 증명을 사용하고 클라우드 공급자의 인증(authN) 및 권한 부여(authZ) 도구를 사용하여 클라우드 리소스에 대한 액세스를 제어하는 방법을 보다 세부적으로 제어할 수 있습니다.
• 자격 증명 순환: OIDC를 사용하면 클라우드 공급자가 단일 작업에만 유효한 수명이 짧은 액세스 토큰을 발급한 다음, 자동으로 만료됩니다.

OIDC 시작

다음 다이어그램에서는 GitHub의 OIDC 공급자가 워크플로 및 클라우드 공급자와 통합되는 방법에 대한 개요를 제공합니다.

1. 클라우드 공급자에서 클라우드에 액세스해야 하는 클라우드 역할과 GitHub 워크플로 간에 OIDC 트러스트를 만듭니다.
2. 작업이 실행될 때마다 GitHub의 OIDC 공급자는 OIDC 토큰을 자동으로 생성합니다. 이 토큰에는 인증하려는 특정 워크플로에 대해 보안이 강화되고 확인 가능한 ID를 설정하는 여러 클레임이 포함되어 있습니다.
3. GitHub의 OIDC 공급자에서 이 토큰을 요청하고 클라우드 공급자에게 표시하는 단계 또는 동작을 작업에 포함할 수 있습니다.
4. 클라우드 공급자가 토큰에 제공된 클레임의 유효성을 성공적으로 검사하면 작업 기간 동안에만 사용할 수 있는 수명이 짧은 클라우드 액세스 토큰을 제공합니다.

클라우드를 사용하여 OIDC 트러스트 구성

GitHub의 OIDC 공급자를 신뢰하도록 클라우드를 구성하는 경우 신뢰할 수 없는 리포지토리 또는 워크플로가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 들어오는 요청을 필터링하는 조건을 추가해야 합니다.

• 액세스 토큰을 부여하기 전에 클라우드 공급자는 트러스트 설정에서 조건을 설정하는 데 사용되는 subject 및 기타 클레임이 요청의 JWT(JSON Web Token)의 클레임과 일치하는지 확인합니다. 따라서 클라우드 공급자에서 주체 및 기타 조건을 올바르게 정의하기 위해 주의해야 합니다.
• OIDC 트러스트 구성 단계 및 클라우드 역할에 대한 조건을 설정(주체 및 기타 클레임 사용)하는 구문은 사용 중인 클라우드 공급자에 따라 달라집니다. 몇 가지 예시는 "주체 클레임 예시"를 참조하세요.

OIDC 토큰 이해

각 작업은 GitHub의 OIDC 공급자로부터 OIDC 토큰을 요청합니다. 이 공급자는 생성된 각 워크플로 작업에 대해 고유한 자동으로 생성된 JWT(JSON Web Token)로 응답합니다. 작업이 실행되면 클라우드 공급자에게 OIDC 토큰이 표시됩니다. 토큰의 유효성을 검사하기 위해 클라우드 공급자는 OIDC 토큰의 주체 및 기타 클레임이 클라우드 역할의 OIDC 트러스트 정의에 미리 구성된 조건과 일치하는지 확인합니다.

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

{
  "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",
  "enterprise": "avocado-corp",
  "enterprise_id": "2",
  "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
}

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

토큰에는 표준 대상 그룹, 발급자, 주체 클레임이 포함됩니다.

OIDC 토큰에는 추가 표준 JOSE 머리글 매개 변수와 클레임도 포함됩니다.

토큰에는 GitHub이(가) 제공하는 사용자 지정 클레임도 포함됩니다.

OIDC 클레임을 사용하여 클라우드 역할에 대한 트러스트 조건 정의

OIDC를 사용하면 클라우드 공급자의 리소스에 액세스하기 위해 GitHub Actions 워크플로에 토큰이 필요합니다. 워크플로는 클라우드 공급자로부터 JWT에서 제공하는 세부 정보를 확인하는 액세스 토큰을 요청합니다. JWT의 트러스트 구성이 일치하는 경우 클라우드 공급자는 워크플로에 임시 토큰을 발급하여 응답합니다. 그러면 클라우드 공급자의 리소스에 액세스하는 데 이 임시 토큰을 사용할 수 있습니다. 특정 조직의 리포지토리에서 시작된 요청에만 응답하도록 클라우드 공급자를 구성할 수 있습니다. 아래에 설명된 추가 조건을 지정할 수도 있습니다.

대상 그룹 및 주체 클레임은 일반적으로 클라우드 역할/리소스에 대한 조건을 설정하여 GitHub 워크플로에 대한 액세스 범위를 지정할 때 함께 사용됩니다.

• 대상 그룹: 기본적으로 이 값은 조직 또는 리포지토리 소유자의 URL을 사용합니다. 특정 조직의 워크플로만 클라우드 역할에 액세스할 수 있는 조건을 설정하는 데 사용할 수 있습니다.
• 주체: 기본적으로 미리 정의된 형식을 가지며 GitHub 조직, 리포지토리, 분기 또는 연결된 job 환경과 같은 워크플로에 대한 일부 주요 메타데이터를 연결한 것입니다. 연결된 메타데이터에서 주체 클레임이 어셈블되는 방법을 보려면 "주체 클레임 예시"를 참조하세요.

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

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

주체 클레임 예시

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

특정 환경에 대한 필터링

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

특정 환경 이름을 필터링하는 주체를 구성할 수 있습니다. 이 예시에서 워크플로 실행은 octo-org 조직이 소유한 octo-repo라는 리포지토리에 Production이라는 환경이 있는 작업에서 시작되어야 합니다.

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

pull_request 이벤트 필터링

워크플로가 끌어오기 요청 이벤트에 의해 트리거되는 경우 주체 클레임에 pull_request 문자열이 포함됩니다. 단, 작업에서 환경을 참조하지 않아야만 합니다.

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

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

특정 분기 필터링

주체 클레임에는 워크플로의 분기 이름이 포함됩니다. 단, 작업이 환경을 참조하지 않고 워크플로가 끌어오기 요청 이벤트에 의해 트리거되지 않는 경우에만 해당됩니다.

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

특정 태그 필터링

주체 클레임에는 워크플로의 태그 이름이 포함됩니다. 단, 작업이 환경을 참조하지 않고 워크플로가 끌어오기 요청 이벤트에 의해 트리거되지 않는 경우에만 해당됩니다.

특정 태그를 필터링하는 주체를 만들 수 있습니다. 이 예시에서 워크플로 실행은 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

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

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

자세한 내용은 "클라우드 공급자에 대해 OpenID Connect 사용"에 나열된 지침을 참조하세요.

OIDC에 대한 작업 업데이트

OIDC를 사용하여 인증하도록 사용자 지정 작업을 업데이트하려면 작업 도구 키트에서 getIDToken()을 사용하여 GitHub의 OIDC 공급자로부터 JWT를 요청할 수 있습니다. 자세한 내용은 npm 패키지 설명서에서 "OIDC 토큰"을 참조하세요.

다음 환경 변수를 사용하여 curl 명령을 사용하여 JWT를 요청할 수도 있습니다.

예시:

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"

사용 권한 설정 추가

작업 또는 워크플로 실행에는 GitHub의 OIDC 공급자가 모든 실행에 대한 JSON 웹 토큰을 만들 수 있는 id-token: write가 있는 permissions 설정이 필요합니다. id-token에 대한 permissions가 write로 설정되지 않으면 OIDC JWT ID 토큰을 요청할 수 없습니다. 그러나 이 값은 리소스에 대한 쓰기 액세스 권한을 부여하는 것을 의미하지 않으며, 수명이 짧은 액세스 토큰으로 인증할 수 있도록 작업 또는 단계에 대한 OIDC 토큰을 페치하고 설정할 수만 있습니다. 실제 신뢰 설정은 OIDC 클레임을 사용하여 정의됩니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을(를) 참조하세요.

이 id-token: write 설정을 통해 다음 방법 중 하나를 사용하여 GitHub의 OIDC 공급자에서 JWT를 요청할 수 있습니다.

• 실행기(ACTIONS_ID_TOKEN_REQUEST_URL 및 ACTIONS_ID_TOKEN_REQUEST_TOKEN)에서 환경 변수 사용
• Actions 도구 키트에서 getIDToken() 사용

워크플로에 대한 OIDC 토큰을 페치해야 하는 경우 워크플로 수준에서 사용 권한을 설정할 수 있습니다. 예시:

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

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

permissions:
  id-token: write # This is required for requesting the JWT

워크플로의 요구 사항에 따라 여기에서 추가 권한을 지정해야 할 수 있습니다.

호출자 워크플로와 동일한 사용자, 조직 또는 엔터프라이즈가 소유한 재사용 가능한 워크플로의 경우, 호출자의 컨텍스트에서 재사용 가능한 워크플로에서 생성된 OIDC 토큰에 액세스할 수 있습니다. 엔터프라이즈 또는 조직 외부에서 재사용 가능한 워크플로의 경우, 호출자 워크플로 수준 또는 재사용 가능한 워크플로를 호출하는 특정 작업에서 write에 id-token의 permissions 설정을 명시적으로 설정해야 합니다. 이렇게 설정하면 재사용 가능한 워크플로에서 생성된 OIDC 토큰이 의도한 경우에만 호출자 워크플로에서 사용할 수 있게 됩니다.

자세한 내용은 "워크플로 다시 사용"을(를) 참조하세요.

토큰 클레임 사용자 지정

JWT에 포함된 클레임을 사용자 지정하여 OIDC 구성의 보안을 강화할 수 있습니다. 다음 사용자 지정을 사용하면 워크플로가 클라우드에서 호스팅되는 리소스에 액세스할 수 있도록 허용할 때 클라우드 역할에 대해 보다 세부적인 신뢰 조건을 정의할 수 있습니다.

• issuer 또는 audience 클레임에 대한 값을 사용자 지정할 수 있습니다. "엔터프라이즈의 issuer 값 사용자 지정" 및 "audience 값 사용자 지정"을 참조하세요.
• 특정 리포지토리, 재사용 가능한 워크플로 또는 기타 소스에서 발생하는 데 JWT 토큰이 필요한 주체(sub) 클레임에 대한 조건을 설정하여 OIDC 구성의 형식을 사용자 지정할 수 있습니다.
• repository_id 및 repository_visibility 등과 같은 추가 OIDC 토큰 클레임을 사용하여 세분화된 OIDC 정책을 정의할 수 있습니다. “OIDC 토큰 이해”를 참조하세요.

audience 값 사용자 지정

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

작업에서 제공하는 기본 aud 값을 사용하지 않으려는 경우 audience 클레임에 대한 사용자 지정 값을 제공할 수 있습니다. 그러면 특정 리포지토리 또는 조직의 워크플로만 클라우드 역할에 액세스할 수 있도록 조건을 설정할 수 있습니다. 사용 중인 작업이 이를 지원하는 경우 워크플로에 with 키워드를 사용하여 사용자 지정 aud 값을 작업에 전달할 수 있습니다. 자세한 내용은 "GitHub Actions에 대한 메타데이터 구문"을 참조하세요.

엔터프라이즈의 issuer 값 사용자 지정

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

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

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

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

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

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

조직 또는 리포지토리에 대한 주체 클레임 사용자 지정

보안, 규정 준수, 표준화를 개선하기 위해 필요한 액세스 조건에 맞게 표준 클레임을 사용자 지정할 수 있습니다. 클라우드 공급자가 주체 클레임에 대한 조건을 지원하는 경우 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 주체 클레임에 대한 사용자 지정 템플릿을 적용할 수 있습니다. 예를 들어, OIDC 토큰 내의 sub 클레임에 항상 특정 사용자 지정 클레임(예시: job_workflow_ref)을 포함하도록 요구할 수 있습니다. 자세한 내용은 "GitHub Actions OIDC에 대한 REST API 엔드포인트"을(를) 참조하세요.

클레임을 사용자 지정하면 전체 sub 클레임에 대한 새 형식이 생성되며, 이는 "OpenID Connect를 사용한 보안 강화 정보"에 설명된 토큰의 미리 정의된 기본값인 sub 형식을 대체합니다.

다음 예시 템플릿에서는 제목 클레임을 사용자 지정하는 다양한 방법을 보여줍니다. 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 구성에서 클레임에 repository_owner 및 repository_visibility에 대한 특정 값을 포함해야 하는 sub 조건을 구성합니다. 예시: "sub": "repository_owner:monalisa:repository_visibility:private" 이 접근 방식을 사용하면 클라우드 역할 액세스를 조직 또는 엔터프라이즈 내의 프라이빗 리포지토리로만 제한할 수 있습니다.

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

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

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

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

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

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

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

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

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

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

예시: 재사용 가능한 워크플로 및 기타 클레임 필요

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

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

이 예시에서는 "context"를 사용하여 조건을 정의하는 방법도 보여줍니다. 이 부분은 리포지토리를 기본 sub 형식으로 따르는 부분입니다. 예를 들어 작업이 환경을 참조할 때 컨텍스트에는 environment:ENVIRONMENT-NAME이 포함됩니다.

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

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

이 사용자 지정 템플릿을 사용하려면 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과 결합할 수 있습니다.

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

{
   "include_claim_keys": [
       "repo"
   ]
}

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

예시: 시스템 생성 GUID 사용

이 예시 템플릿은 엔터티 이름 바꾸기(예시: 리포지토리 이름 바꾸기) 간에 변경되지 않는 시스템 생성 GUID를 사용하여 예측 가능한 OIDC 클레임을 사용하도록 설정합니다.

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

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

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

또는:

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

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

예: :이 있는 컨텍스트 값

이 예제에서는 :을 사용하여 컨텍스트 값을 처리하는 방법을 보여 줍니다. 예를 들어 작업이 production:eastus라고 명명된 환경을 참조하는 경우입니다.

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

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

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

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

이 예시 템플릿은 주체 클레임을 기본 형식으로 초기화합니다. 이 템플릿은 조직 수준 사용자 지정 정책을 효과적으로 옵트아웃합니다.

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

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

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

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

조직의 모든 리포지토리에는 사용자 지정 sub 클레임 템플릿을 옵트인 또는 옵트아웃(조직 및 리포지토리 수준)할 수 있는 기능이 있습니다.

리포지토리를 옵트아웃하고 기본 sub 클레임 형식으로 재설정하려면 리포지토리 관리자가 "GitHub Actions OIDC에 대한 REST API 엔드포인트"의 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 엔드포인트를 사용해야 합니다. 자세한 내용은 "GitHub Actions OIDC에 대한 REST API 엔드포인트"을(를) 참조하세요.

{
   "use_default": false
}

OIDC에 대한 워크플로 업데이트

이제 비밀 대신 OIDC 액세스 토큰을 사용하도록 YAML 워크플로를 업데이트할 수 있습니다. 인기 있는 클라우드 공급자는 OIDC를 쉽게 시작할 수 있도록 하는 공식 로그인 작업을 게시했습니다. 워크플로 업데이트에 대한 자세한 내용은 "클라우드 공급자에 OpenID Connect 사용"에 나열된 클라우드 관련 가이드를 참조하세요.

Python 패키지 게시를 위해 OpenID Connect 사용 설정

리포지토리의 GitHub Actions 워크플로를 PyPI 프로젝트의 신뢰할 수 있는 게시자로 사용할 수 있습니다. 워크플로를 신뢰할 수 있는 게시자로 사용하면 OIDC 액세스 토큰을 임시 PyPI API 토큰으로 교환할 수 있습니다. 자세한 내용은 PyPI 설명서에서 "PyPI에서 OpenID Connect 구성하기" 및 "신뢰할 수 있는 게시자를 사용하여 PyPI에 게시"를 참조하세요.

클라우드 공급자에 OpenID Connect 사용

특정 클라우드 공급자에 대해 OIDC를 사용하도록 설정하고 구성하려면 다음 가이드를 참조하세요.

• "Amazon Web Services에서 OpenID Connect 구성"
• "Azure에서 OpenID Connect 구성"
• "Google Cloud Platform에서 OpenID Connect 구성"
• "HashiCorp 자격 증명 모음에서 OpenID Connect 구성"

다른 클라우드 공급자에 대해 OIDC를 사용하도록 설정하고 구성하려면 다음 가이드를 참조하세요.

• "클라우드 공급자에서 OpenID Connect 구성"

GHE.com에서 다음 가이드 수행

데이터 보존 기능을 갖춘 GitHub Enterprise Cloud를 사용하는 엔터프라이즈의 일부로서 GHE.com에서 OIDC를 설정하는 경우 연결된 문서의 특정 값을 대체해야 합니다.

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

예를 들어 하위 도메인이 octocorp인 경우 다음 대체 사항이 적용됩니다.

• GitHub의 OIDC 공급자가 지원하는 모든 클레임을 확인하는 URL은 https://token.actions.octocorp.ghe.com/.well-known/openid-configuration입니다.
• OIDC 토큰의 iss 값은 https://token.actions.octocorp.ghe.com입니다.
• 엔터프라이즈는 https://token.actions.octocorp.ghe.com/octocorp에서 토큰을 받을 수 있으며 issuer 값을 사용자 지정하기 위한 REST API 엔드포인트는 /enterprises/octocorp/actions/oidc/customization/issuer입니다.

OIDC 클레임 디버깅

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