Note
GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.
개요
OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로가 수명이 긴 GitHub 비밀로 자격 증명을 저장하지 않고도 클라우드 공급자의 리소스에 액세스할 수 있습니다.
OIDC를 사용하려면 먼저 GitHub의 OIDC를 페더레이션 ID로 신뢰하도록 클라우드 공급자를 구성한 다음 토큰을 사용하여 인증하도록 워크플로를 업데이트해야 합니다.
필수 조건
-
GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.
-
계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보" 항목을 참조하세요.
GitHub Actions 워크플로 업데이트
OIDC에 대한 워크플로를 업데이트하려면 YAML에 두 가지를 변경해야 합니다.
- 토큰에 대한 사용 권한 설정을 추가합니다.
- 클라우드 공급자의 공식 작업을 사용하여 클라우드 액세스 토큰에 대한 OIDC 토큰(JWT)을 교환합니다.
클라우드 공급자가 아직 공식 작업을 제공하지 않는 경우 워크플로를 업데이트하여 해당 단계를 수동으로 수행할 수 있습니다.
Note
워크플로 또는 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 토큰이 의도한 경우에만 호출자 워크플로에서 사용할 수 있게 됩니다.
자세한 내용은 "워크플로 다시 사용"을(를) 참조하세요.
공식 작업 사용
클라우드 공급자가 GitHub Actions와 함께 OIDC를 사용하기 위한 공식 작업을 만든 경우 OIDC 토큰을 액세스 토큰으로 쉽게 교환할 수 있습니다. 그런 다음 클라우드 리소스에 액세스할 때 이 토큰을 사용하도록 워크플로를 업데이트할 수 있습니다.
예를 들어 Alibaba Cloud는 GitHub에서 OIDC를 사용하여 통합할 aliyun/configure-aliyun-credentials-action
을 만들었습니다.
사용자 지정 작업 사용
클라우드 공급자에 공식 작업이 없거나 사용자 지정 스크립트를 만들려는 경우 GitHub의 OIDC 공급자에서 JWT(JSON Web Token)를 수동으로 요청할 수 있습니다.
공식 작업을 사용하지 않는 경우 GitHub에서 Actions 핵심 도구 키트를 사용하는 것이 좋습니다. 또는 다음 환경 변수를 사용하여 ACTIONS_ID_TOKEN_REQUEST_TOKEN``ACTIONS_ID_TOKEN_REQUEST_URL
토큰을 검색할 수 있습니다.
이 방법을 사용하여 워크플로를 업데이트하려면 YAML에 세 가지 변경사항을 적용해야 합니다.
- 토큰에 대한 사용 권한 설정을 추가합니다.
- GitHub의 OIDC 공급자에서 OIDC 토큰을 요청하는 코드를 추가합니다.
- 액세스 토큰을 위해 클라우드 공급자와 OIDC 토큰을 교환하는 코드를 추가합니다.
Actions 핵심 도구 키트를 사용하여 JWT 요청
다음 예제에서는 core
도구 키트와 함께 actions/github-script
사용하여 GitHub의 OIDC 공급자로부터 JWT를 요청하는 방법을 보여줍니다. 자세한 내용은 "JavaScript 작업 만들기"을 참조하세요.
jobs:
job:
environment: Production
runs-on: ubuntu-latest
steps:
- name: Install OIDC Client from Core Package
run: npm install @actions/core@1.6.0 @actions/http-client
- name: Get Id Token
uses: actions/github-script@v6
id: idtoken
with:
script: |
const coredemo = require('@actions/core')
let id_token = await coredemo.getIDToken()
coredemo.setOutput('id_token', id_token)
환경 변수를 사용하여 JWT 요청
다음 예제에서는 환경 변수를 사용하여 JSON 웹 토큰을 요청하는 방법을 보여줍니다.
배포 작업의 경우 core
도구 키트와 함께 actions/github-script
를 사용하여 토큰 설정을 정의해야 합니다. 자세한 내용은 "JavaScript 작업 만들기"을 참조하세요.
예:
jobs:
job:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v6
id: script
timeout-minutes: 10
with:
debug: true
script: |
const token = process.env['ACTIONS_RUNTIME_TOKEN']
const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
core.setOutput('TOKEN', token.trim())
core.setOutput('IDTOKENURL', runtimeUrl.trim())
그런 다음 GitHub OIDC 공급자에서 JWT를 검색하는 데 curl
을 사용할 수 있습니다. 예:
- run: |
IDTOKEN=$(curl -H "Authorization: bearer ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}} -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
echo $IDTOKEN
jwtd() {
if [[ -x $(command -v jq) ]]; then
jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
fi
}
jwtd $IDTOKEN
echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
id: tokenid
클라우드 공급자에서 액세스 토큰 가져오기
액세스 토큰을 얻으려면 클라우드 공급자에게 OIDC JSON 웹 토큰을 제공해야 합니다.
각 배포에 대해 워크플로는 OIDC 토큰을 가져와 클라우드 공급자에게 제공하는 클라우드 로그인 작업(또는 사용자 지정 스크립트)을 사용해야 합니다. 그런 다음 클라우드 공급자는 토큰에서 클레임의 유효성을 검사합니다. 성공하면 해당 작업 실행에만 사용할 수 있는 클라우드 액세스 토큰을 제공합니다. 그러면 제공된 액세스 토큰을 작업의 후속 작업에서 사용하여 클라우드에 연결하고 해당 리소스에 배포할 수 있습니다.
액세스 토큰에 대한 OIDC 토큰을 교환하는 단계는 각 클라우드 공급자에 따라 달라집니다.
클라우드 공급자의 리소스 액세스
액세스 토큰을 가져온 후에는 특정 클라우드 작업 또는 스크립트를 사용하여 클라우드 공급자에 인증하고 해당 리소스에 배포할 수 있습니다. 단계는 각 클라우드 공급자에 따라 다를 수 있습니다.
예를 들어 Alibaba Cloud는 OIDC 인증에 대한 자체 지침을 유지합니다. 자세한 내용은 Alibaba Cloud 설명서의 OIDC 기반 SSO 개요를 참조하세요.
또한 이 액세스 토큰의 기본 만료 시간은 각 클라우드마다 다를 수 있으며 클라우드 공급자 측에서 구성할 수 있습니다.