Amazon Web Services에서 OpenID Connect 구성

참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.

개요

OIDC(OpenID Connect)를 사용하면 GitHub Actions 워크플로가 AWS 자격 증명을 수명이 긴 GitHub 비밀로 저장할 필요 없이 AWS(Amazon Web Services)의 리소스에 액세스할 수 있습니다.

이 가이드에서는 GitHub의 OIDC를 페더레이션된 ID로 신뢰하도록 AWS를 구성하는 방법에 대해 설명하고, 토큰을 사용하여 AWS에 인증하고 리소스에 액세스하는 aws-actions/configure-aws-credentials 워크플로 예제를 포함합니다.

참고: AWS에서는 OIDC에 대한 사용자 지정 청구와 관련된 지원을 사용할 수 없습니다.

필수 조건

GitHub가 OIDC(OpenID Connect)를 사용하는 방법과 아키텍처 및 이점에 대한 기본 개념을 알아보려면 “OpenID Connect를 사용한 보안 강화 정보”를 참조하세요.
계속하기 전에 액세스 토큰이 예측 가능한 방식으로만 할당되도록 보안 전략을 계획해야 합니다. 클라우드 공급자가 액세스 토큰을 발급하는 방법을 제어하려면 신뢰할 수 없는 리포지토리가 클라우드 리소스에 대한 액세스 토큰을 요청할 수 없도록 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을(를) 참조하세요.
클라우드 공급자가 다음 OIDC 엔드포인트에 액세스할 수 있는지 확인해야 합니다.
- https://HOSTNAME/_services/token/.well-known/openid-configuration
- https://HOSTNAME/_services/token/.well-known/jwks
참고: AWS IP 주소 범위만 허용하여 OIDC 엔드포인트에 대한 액세스를 제한할 수 있습니다.

참고: {data variables.product.prodname_dotcom %}은 기본적으로 AWS 세션 태그를 지원하지 않습니다.

AWS에 ID 공급자 추가

GitHub OIDC 공급자를 IAM에 추가하려면 AWS 설명서를 참조하세요.

공급자 URL: https://HOSTNAME/_services/token
"대상 그룹"의 경우: 공식 작업을 사용하는 경우 sts.amazonaws.com을 사용합니다.

역할 및 신뢰 정책 구성

IAM에서 역할 및 신뢰를 구성하려면 AWS 설명서 "GitHub 작업을 위한 AWS 자격 증명 구성" 및 "GitHub OIDC ID 공급자에 대한 역할 구성"을 참조하세요.

참고: AWS IAM(신원 및 액세스 관리)은 사용자가 GitHub의 OIDC ID 공급자(IdP)를 신뢰하는 모든 역할의 신뢰 정책에서 IAM 조건 키, token.actions.githubusercontent.com:sub를 평가할 것을 권장합니다. 역할 트러스트 정책에서 이 조건 키를 평가하면 역할을 맡을 수 있는 GitHub 작업이 제한됩니다.

유효성 검사 조건에 sub 필드를 추가하여 신뢰 정책을 편집합니다. 예:

JSON

"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

환경과 함께 워크플로를 사용하는 경우 sub 필드에 환경 이름 repo:OWNER/REPOSITORY:environment:NAME를 참조해야 합니다. 자세한 내용은 "OpenID Connect를 사용한 보안 강화 정보"을(를) 참조하세요.

참고: 워크플로 또는 OIDC 정책에서 환경을 사용하는 경우 추가 보안을 위해 환경에 보호 규칙을 추가하는 것이 좋습니다. 예를 들어 환경에 배포할 수 있는 분기 및 태그를 제한하거나 환경 비밀에 액세스하도록 환경에 대한 배포 규칙을 구성할 수 있습니다. 자세한 내용은 "배포에 환경 사용"을(를) 참조하세요.

JSON

"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

다음 예제에서는 StringLike을 와일드카드 연산자(*)와 함께 사용하여 octo-org/octo-repo 조직 및 리포지토리의 모든 브랜치, 풀리퀘스트 병합 브랜치 또는 환경이 AWS에서 역할을 맡을 수 있도록 합니다.

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

GitHub Actions 워크플로 업데이트

OIDC에 대한 워크플로를 업데이트하려면 YAML에 두 가지를 변경해야 합니다.

토큰에 대한 사용 권한 설정을 추가합니다.
aws-actions/configure-aws-credentials 작업을 사용하여 클라우드 액세스 토큰에 대한 OIDC 토큰(JWT)을 교환합니다.

사용 권한 설정 추가

작업 또는 워크플로 실행에는 id-token: write 관련 permissions 설정이 필요합니다. id-token에 대한 permissions 설정이 read 또는 none으로 설정된 경우 OIDC JWT ID 토큰을 요청할 수 없습니다.

이 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

액세스 토큰 요청

aws-actions/configure-aws-credentials 작업은 GitHub OIDC 공급자로부터 JWT를 받은 다음 AWS에서 액세스 토큰을 요청합니다. 자세한 내용은 AWS 설명서를 참조하세요.

<example-bucket-name>: S3 버킷의 이름을 여기에 추가합니다.
<role-to-assume>: 예제를 AWS 역할로 바꿉니다.
<example-aws-region>: 여기에 AWS 지역의 이름을 추가합니다.

YAML

# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "<example-bucket-name>"
  AWS_REGION : "<example-aws-region>"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v3
        with:
          role-to-assume: arn:aws:iam::1234567890:role/example-role
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name:  Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/

# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "<example-bucket-name>"
  AWS_REGION : "<example-aws-region>"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v3
        with:
          role-to-assume: arn:aws:iam::1234567890:role/example-role
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name:  Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/

추가 참고 자료

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

이 문서의 내용