참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.
개요
OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로가 Azure 자격 증명을 수명이 긴 GitHub 비밀로 저장할 필요 없이 Azure의 리소스에 액세스할 수 있습니다.
이 가이드에서는 GitHub의 OIDC를 페더레이션된 ID로 신뢰하도록 Azure를 구성하는 방법에 대한 개요를 제공하고, 토큰을 사용하여 Azure에 인증하고 리소스에 액세스하는 azure/login
작업에 대한 워크플로 예제를 포함합니다.
필수 조건
-
GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.
-
계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을(를) 참조하세요.
-
클라우드 공급자가 다음 OIDC 엔드포인트에 액세스할 수 있는지 확인해야 합니다.
https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks
참고: Microsoft Entra ID(이전의 Azure AD)에는 이러한 엔드포인트에 대해 정의된 고정 IP 범위가 없습니다.
-
JWT(JSON 웹 토큰)에 포함된 발급자 클레임의 값이 공개적으로 라우팅 가능한 URL로 설정되어 있는지 확인하세요. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을 참조하세요.
Azure에 페더레이션 자격 증명 추가
GitHub의 OIDC 공급자는 Azure의 워크로드 ID 페더레이션을 사용합니다. 개요는 "워크로드 ID 페더레이션"에서 Microsoft의 설명서를 참조하세요.
Azure에서 OIDC ID 공급자를 구성하려면 다음 구성을 수행해야 합니다. 변경에 대한 지침은 Azure 설명서를 참조하세요.
- Entra ID 애플리케이션 및 서비스 주체 만들기
- Entra ID 애플리케이션에 대한 페더레이션 자격 증명을 추가합니다.
- Azure 구성을 저장하기 위한 GitHub 비밀을 만듭니다.
ID 공급자를 구성하기 위한 추가 지침:
- 보안 강화를 위해 "OpenID Connect를 사용한 보안 강화 정보"을 검토했는지 확인하세요. 예는 "OpenID Connect를 사용한 보안 강화 정보"을 참조하세요.
audience
설정의 경우api://AzureADTokenExchange
가 권장되는 값이지만 여기에 다른 값을 지정할 수도 있습니다.
GitHub Actions 워크플로 업데이트
OIDC에 대한 워크플로를 업데이트하려면 YAML에 두 가지를 변경해야 합니다.
- 토큰에 대한 사용 권한 설정을 추가합니다.
azure/login
작업을 사용하여 클라우드 액세스 토큰에 대한 OIDC 토큰(JWT)을 교환합니다.
참고: 워크플로 또는 OIDC 정책에서 환경을 사용하는 경우 추가 보안을 위해 환경에 보호 규칙을 추가하는 것이 좋습니다. 예를 들어 환경에 배포할 수 있는 분기 및 태그를 제한하거나 환경 비밀에 액세스하도록 환경에 대한 배포 규칙을 구성할 수 있습니다. 자세한 내용은 "배포 환경 관리"을(를) 참조하세요.
사용 권한 설정 추가
작업 또는 워크플로 실행에는 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 토큰이 의도한 경우에만 호출자 워크플로에서 사용할 수 있게 됩니다.
자세한 내용은 "워크플로 다시 사용"을(를) 참조하세요.
액세스 토큰 요청
azure/login
작업은 GitHub OIDC 공급자로부터 JWT를 받은 다음 Azure에서 액세스 토큰을 요청합니다. 자세한 내용은 azure/login
설명서를 참조하세요.
다음 예제에서는 OIDC ID 토큰을 Azure와 교환하여 액세스 토큰을 수신한 다음 클라우드 리소스에 액세스하는 데 사용합니다.
name: Run Azure Login with OIDC on: [push] permissions: id-token: write contents: read jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: 'Az CLI login' uses: azure/login@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 with: client-id: ${{ secrets.AZURE_CLIENT_ID }} tenant-id: ${{ secrets.AZURE_TENANT_ID }} subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} - name: 'Run az commands' run: | az account show az group list
name: Run Azure Login with OIDC
on: [push]
permissions:
id-token: write
contents: read
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: 'Az CLI login'
uses: azure/login@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- name: 'Run az commands'
run: |
az account show
az group list