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

개요

OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로가 수명이 긴 GitHub 비밀로 자격 증명을 저장하지 않고도 클라우드 공급자의 리소스에 액세스할 수 있습니다.

OIDC를 사용하려면 먼저 GitHub의 OIDC를 페더레이션 ID로 신뢰하도록 클라우드 공급자를 구성한 다음 토큰을 사용하여 인증하도록 워크플로를 업데이트해야 합니다.

필수 조건

GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.
계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보" 항목을 참조하세요.
GHE.com에서 이 가이드를 따르는 경우 다음 문서의 특정 값을 대체해야 한다는 점을 알아 두세요. "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 토큰을 페치해야 하는 경우 워크플로 수준에서 사용 권한을 설정할 수 있습니다. 예시:

YAML

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 토큰을 가져오기만 하면 되는 경우 해당 작업 내에서 이 권한을 설정할 수 있습니다. 예시:

YAML

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 개요를 참조하세요.

또한 이 액세스 토큰의 기본 만료 시간은 각 클라우드마다 다를 수 있으며 클라우드 공급자 측에서 구성할 수 있습니다.

추가 참고 자료

재사용 가능한 워크플로에서 OpenID Connect 사용 - 자체 호스트형 실행기 정보

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

이 문서의 내용