AWS에서 일시적 자격 증명을 검색하도록 AWS에서 OpenID Connect 구성

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

경고: CI_JOB_JWT_V2는 GitLab 15.9에서 폐기되었습니다 그리고 GitLab 17.0에서 제거될 예정입니다. ID 토큰을 대신 사용하십시오.

이 튜토리얼에서는 GitLab CI/CD 작업을 사용하여 AWS에서 일시적 자격 증명을 가져오는 방법을 보여드리겠습니다. 이를 위해 GitLab과 AWS 간에 ID 페더레이션을 구성해야 합니다. OIDC(OpenID Connect)를 구성해야 합니다. OIDC를 사용하여 GitLab을 통합하는 백그라운드 및 요구 사항은 cloud services에 연결을 참조하십시오.

이 튜토리얼을 완료하려면 다음을 수행하십시오:

  1. Identity provider 추가
  2. Role 및 신뢰 구성
  3. 일시적 자격 증명 검색

Identity provider 추가

AWS에서 GitLab을 IAM OIDC 제공자로 만들려면 다음 지침을 따르세요.

다음 정보를 포함하세요:

  • Provider URL: GitLab 인스턴스의 주소, 예: https://gitlab.com 또는 http://gitlab.example.com. 이 주소는 공개적으로 액세스 가능해야 합니다.
  • Audience: GitLab 인스턴스의 주소, 예: https://gitlab.com 또는 http://gitlab.example.com.
    • 주소에는 https://를 포함해야 합니다.
    • 슬래시로 끝나지 않아야 합니다.

Role 및 신뢰 구성

Identity provider를 생성한 후 웹 신원 역할을 구성하여 GitLab 리소스에 대한 액세스를 제한하는 조건을 설정하세요. 일시적 자격 증명은 AWS Security Token Service를 사용하여 얻으므로 Action을 sts:AssumeRoleWithWebIdentity로 설정하세요.

특정 그룹, 프로젝트, 브랜치 또는 태그로 권한을 제한하기 위해 역할에 대한 사용자 지정 신뢰 정책을 만들 수 있습니다. 지원되는 필터링 유형의 전체 목록은 cloud services에 연결를 참조하십시오. 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::AWS_ACCOUNT:oidc-provider/gitlab.example.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "gitlab.example.com:sub": "project_path:mygroup/myproject:ref_type:branch:ref:main"
        }
      }
    }
  ]
}

역할이 생성된 후 AWS 서비스(S3, EC2, Secrets Manager)에 대한 권한을 정의하는 정책을 첨부하세요.

일시적 자격 증명 검색

OIDC 및 역할을 구성한 후 GitLab CI/CD 작업에서 AWS Security Token Service (STS)에서 일시적 자격 증명을 검색할 수 있습니다. 

assume role:
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com
  script:
    - >
      export $(printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s"
      $(aws sts assume-role-with-web-identity
      --role-arn ${ROLE_ARN}
      --role-session-name "GitLabRunner-${CI_PROJECT_ID}-${CI_PIPELINE_ID}"
      --web-identity-token ${GITLAB_OIDC_TOKEN}
      --duration-seconds 3600
      --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]'
      --output text))
    - aws sts get-caller-identity
  • ROLE_ARN: 이 단계에서 정의한 역할 ARN입니다.
  • GITLAB_OIDC_TOKEN: OIDC ID 토큰.

작동하는 예시

문제 해결

에러: Not authorized to perform sts:AssumeRoleWithWebIdentity

이 오류가 표시되는 경우: 

An error occurred (AccessDenied) when calling the AssumeRoleWithWebIdentity operation:
Not authorized to perform sts:AssumeRoleWithWebIdentity

다음과 같은 이유로 발생할 수 있습니다:

  • 클라우드 관리자가 프로젝트를 GitLab을 사용하여 OIDC로 구성하지 않았습니다.
  • 역할이 브랜치 또는 태그에 실행을 제한했습니다. 조건부 역할 구성을 참조하십시오.
  • 와일드카드 조건을 사용할 때 StringEquals 대신 StringLike을 사용했습니다. 관련 이슈를 참조하십시오.

Openid Configuration of Provider 연결 오류

AWS IAM에 신원 공급자를 추가한 후 다음과 같은 오류 메시지를 받을 수 있습니다. 

요청에 문제가 있습니다. 다음 세부 정보를 확인하세요.
  - 신원 공급자(issuer)의 OpenID 구성에 연결할 수 없음: `https://gitlab.example.com`

이 오류는 OIDC 신원 공급자의 발행자가 순서가 잘못된 인증서 체인을 제공하거나 중복 또는 추가 인증서를 포함할 때 발생합니다.

GitLab 인스턴스의 인증서 체인을 확인하십시오. 체인은 도메인 또는 발행자 URL로 시작하고 중간 인증서로 끝나야 합니다. 다음 명령을 사용하여 인증서 체인을 검토하십시오. gitlab.example.com을(를) GitLab 호스트 이름으로 바꿔 사용하십시오. 

echo | /opt/gitlab/embedded/bin/openssl s_client -connect gitlab.example.com:443

신원 공급자(Identity Provider)에서 확인 키를 검색할 수 없음 오류

다음과 유사한 오류 메시지를 받을 수 있습니다.

  • AssumeRoleWithWebIdentity 작업 호출 시 An error occurred (InvalidIdentityToken): 신원 공급자에서 확인 키를 검색할 수 없음. 요구 사항에 대한 자세한 내용은 AssumeRoleWithWebIdentity documentation을 참조하십시오.

이 오류는 다음과 같은 이유로 발생할 수 있습니다:

  • .well_known URL 및 jwks_uri가 공개 인터넷에서 접근할 수 없습니다.
  • 사용자 정의 방화벽이 요청을 차단하고 있습니다.
  • IdP(신원 공급자)에서 AWS STS 엔드포인트에 도달하기까지 API 요청에 5초 이상의 대기 시간이 있습니다.
  • STS가 .well_known URL이나 IdP의 jwks_uri로 너무 많은 요청을 수행합니다.

이 오류와 관련된 AWS 지식 센터 문서에 기록된 바에 따르면 GitLab 인스턴스는 인증서 확인 키(.well_known URL 및 jwks_uri)를 해결할 수 있을 정도로 공개적으로 접근 가능해야 합니다. 이를 불가능하게 할 경우 예를 들어 GitLab 인스턴스가 오프라인 환경에 있는 경우, issue #391928을 참고하여 조치 방법과 지속적인 해결책을 연구 중인 사안을 확인할 수 있습니다.