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

워크플로우에서 OpenID Connect를 사용해 클라우드 공급자에 인증해보세요.

출처: 문서

본문

워크플로우에서 OpenID Connect를 사용해 클라우드 공급자에 인증할 수 있어요.

개요

OpenID Connect(OIDC)를 사용하면 GitHub Actions 워크플로우가 자격 증명을 장기 보존형 GitHub 시크릿으로 저장하지 않고도 클라우드 공급자의 리소스에 접근할 수 있어요.

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

사전 요구 사항

GitHub가 OpenID Connect(OIDC)를 사용하는 방법, 그 아키텍처와 이점에 대한 기본 개념을 배우려면 OpenID Connect를 참고하세요.
진행하기 전에 보안 전략을 계획해 접근 토큰이 예측 가능한 방식으로만 할당되도록 해야 해요. 클라우드 공급자가 접근 토큰을 발급하는 방식을 제어하려면 신뢰할 수 없는 저장소가 클라우드 리소스에 대한 접근 토큰을 요청할 수 없도록 반드시 최소 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 OpenID Connect reference를 참고하세요.
Dependabot 업데이트 작업을 위해 요청된 OIDC 토큰은 event_name 클레임이 dynamic입니다. 신뢰 정책이 GitHub Actions 워크플로우만 승인하도록 의도되었고 클라우드 공급자가 event_name에 대한 조건을 지원한다면, 워크플로우가 기대하는 이벤트 이름만 허용하세요. 자세한 내용은 OpenID Connect reference를 참고하세요.

GitHub Actions 워크플로우 업데이트하기

워크플로우를 OIDC용으로 업데이트하려면 YAML을 두 가지 변경해야 해요:

토큰에 대한 권한 설정을 추가하세요.
클라우드 공급자의 공식 액션을 사용해 OIDC 토큰(JWT)을 클라우드 접근 토큰으로 교환하세요.

클라우드 공급자가 아직 공식 액션을 제공하지 않는다면, 워크플로우를 업데이트해 이 단계를 수동으로 수행할 수 있어요.

[!NOTE] 워크플로우나 OIDC 정책에서 환경을 사용할 때는 추가 보안을 위해 환경에 보호 규칙을 추가하는 것을 권장합니다. 예를 들어 환경에 배포 규칙을 구성해 어떤 브랜치와 태그가 환경에 배포하거나 환경 시크릿에 접근할 수 있는지 제한할 수 있어요. 자세한 내용은 Managing environments for deployment를 참고하세요.

권한 설정 추가하기

작업 또는 워크플로우 실행에는 GitHub의 OIDC 공급자가 매 실행마다 JSON Web Token을 만들 수 있도록 id-token: write가 있는 permissions 설정이 필요합니다.

[!NOTE] 워크플로우의 권한에 id-token: write를 설정해도 워크플로우가 리소스를 수정하거나 쓰기 권한을 얻는 것은 아닙니다. 대신 액션이나 단계를 위해 OIDC 토큰을 요청(가져오기)하고 사용(설정)할 수만 있게 해줍니다. 이 토큰은 이후 단기 접근 토큰으로 외부 서비스에 인증하는 데 사용됩니다.

필요한 권한, 구성 예시, 고급 시나리오에 대한 자세한 정보는 OpenID Connect reference를 참고하세요.

공식 액션 사용하기

클라우드 공급자가 GitHub Actions와 함께 OIDC를 사용하기 위한 공식 액션을 만들었다면, OIDC 토큰을 접근 토큰으로 쉽게 교환할 수 있게 해줍니다. 그런 다음 워크플로우를 업데이트해 클라우드 리소스에 접근할 때 이 토큰을 사용할 수 있어요.

예를 들어 Alibaba Cloud는 GitHub와 함께 OIDC를 사용하도록 통합하는 aliyun/configure-aliyun-credentials-action을 만들었습니다.

커스텀 액션 사용하기

클라우드 공급자에 공식 액션이 없거나 커스텀 스크립트를 만들고 싶다면, GitHub의 OIDC 공급자에서 JSON Web Token(JWT)을 수동으로 요청할 수 있어요.

공식 액션을 사용하지 않는다면 GitHub는 Actions core 툴킷 사용을 권장합니다. 또는 다음 환경 변수를 사용해 토큰을 검색할 수 있어요: ACTIONS_ID_TOKEN_REQUEST_TOKEN, ACTIONS_ID_TOKEN_REQUEST_URL.

이 방식으로 워크플로우를 업데이트하려면 YAML을 세 가지 변경해야 해요:

토큰에 대한 권한 설정을 추가하세요.
GitHub의 OIDC 공급자에서 OIDC 토큰을 요청하는 코드를 추가하세요.
OIDC 토큰을 클라우드 공급자와 교환해 접근 토큰을 얻는 코드를 추가하세요.

Actions core 툴킷으로 JWT 요청하기

다음 예시는 actions/github-script를 core 툴킷과 함께 사용해 GitHub의 OIDC 공급자에서 JWT를 요청하는 방법을 보여줍니다. 자세한 내용은 Creating a JavaScript action을 참고하세요.

jobs:
  job:
    environment: Production
    runs-on: ubuntu-latest
    steps:
    - name: Install OIDC Client from Core Package
      run: npm install @actions/[email protected] @actions/http-client
    - name: Get Id Token
      uses: actions/github-script@v8
      id: idtoken
      with:
        script: |
          let id_token = await core.getIDToken()
          core.setOutput('id_token', id_token)

환경 변수로 JWT 요청하기

다음 예시는 환경 변수를 사용해 JSON Web Token을 요청하는 방법을 보여줍니다.

배포 작업을 위해서는 actions/github-script를 core 툴킷과 함께 사용해 토큰 설정을 정의해야 해요. 자세한 내용은 Creating a JavaScript action을 참고하세요.

예:

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/github-script@v8
      id: script
      timeout-minutes: 10
      with:
        debug: true
        script: |
          const token = process.env['ACTIONS_ID_TOKEN_REQUEST_TOKEN']
          const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
          core.setOutput('TOKEN', token.trim())
          core.setOutput('IDTOKENURL', runtimeUrl.trim())

그런 다음 curl을 사용해 GitHub OIDC 공급자에서 JWT를 검색할 수 있어요. 예:

    - run: |
        IDTOKEN=$(curl -H "Authorization: Bearer ${{ste...EN}}" ${{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 web token을 클라우드 공급자에게 제시해야 해요.

각 배포에 대해 워크플로우는 OIDC 토큰을 가져와 클라우드 공급자에게 제시하는 클라우드 로그인 액션(또는 커스텀 스크립트)을 사용해야 합니다. 클라우드 공급자는 토큰의 클레임을 검증하고, 성공하면 해당 작업 실행에만 사용할 수 있는 클라우드 접근 토큰을 제공해요. 제공된 접근 토큰은 이후 작업의 후속 액션들이 클라우드에 연결하고 리소스에 배포하는 데 사용할 수 있습니다.

OIDC 토큰을 접근 토큰으로 교환하는 단계는 클라우드 공급자마다 다릅니다.

클라우드 공급자의 리소스에 접근하기

접근 토큰을 얻은 후에는 특정 클라우드 액션이나 스크립트를 사용해 클라우드 공급자에 인증하고 리소스에 배포할 수 있어요. 이 단계는 클라우드 공급자마다 다를 수 있습니다.

예를 들어 Alibaba Cloud는 OIDC 인증에 대한 자체 지침을 관리합니다. 자세한 내용은 Alibaba Cloud 문서의 Overview of OIDC-based SSO를 참고하세요.

또한 이 접근 토큰의 기본 만료 시간은 클라우드마다 다를 수 있으며 클라우드 공급자 측에서 구성할 수 있어요.

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