AWS에서 임시 자격 증명을 가져오도록 OpenID Connect를 구성

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated
caution
CI_JOB_JWT_V2는 GitLab 15.9에서 Deprecated되었으며, GitLab 17.0에서 제거 예정입니다. ID 토큰를 대신 사용하십시오.

이 튜토리얼에서는 AWS에서 보안 비밀을 저장하지 않고 GitLab CI/CD 작업을 사용하여 임시 자격 증명을 가져오는 방법을 보여드리겠습니다. 이를 위해 GitLab과 AWS 간에 ID 연맹을 위해 OpenID Connect(OIDC)를 구성해야 합니다. OIDC를 사용하여 GitLab을 통합하는 데 필요한 배경 및 요구 사항은 클라우드 서비스에 연결를 참조하십시오.

이 튜토리얼을 완료하려면:

  1. 신원 제공자 추가
  2. 역할 및 신뢰 구성
  3. 임시 자격 증명 검색

신원 제공자 추가

다음 지침에 따라 AWS에서 IAM OIDC 제공자로서 GitLab을 생성합니다.

다음 정보를 포함합니다:

  • 공급자 URL: https://gitlab.com 또는 http://gitlab.example.com과 같은 GitLab 인스턴스의 주소. 이 주소는 공개적으로 접근 가능해야 합니다.
  • 청중(감흥): https://gitlab.com 또는 http://gitlab.example.com과 같은 GitLab 인스턴스의 주소.
    • 주소에는 https://를 포함해야 합니다.
    • 뒷부분에는 슬래시를 포함하지 마십시오.

역할 및 신뢰 구성

신원 제공자를 생성한 후에 웹 신원 역할을 구성하여 GitLab 리소스에 대한 액세스를 제한하는 조건을 설정합니다. 임시 자격은 AWS Security Token Service를 사용하여 얻으므로 Action을 sts:AssumeRoleWithWebIdentity로 설정합니다.

역할에 대한 권한을 제한하기 위해 그룹, 프로젝트, 브랜치 또는 태그로 인증을 제한하기 위해 사용자 지정 신뢰 정책을 작성할 수 있습니다. 지원되는 필터 유형의 전체 디렉터리은 클라우드 서비스에 연결를 참조하십시오. 

{
  "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 토큰.

작동하는 예시

문제 해결

sts:AssumeRoleWithWebIdentity 작업 수행 시 An error occurred (AccessDenied) 오류

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

  • 클라우드 관리자가 프로젝트를 GitLab과 OIDC를 사용하도록 구성하지 않은 경우.
  • 역할이 브랜치나 태그에서 실행이 제한되어 있는 경우. 조건부 역할 구성 시를 참조하십시오.
  • 와일드카드 조건을 사용할 때 StringEquals가 사용되었기 때문입니다. 관련 이슈를 확인하려면 여기를 참조하십시오.

identity provider의 openid 구성에 연결할 수 없습니다

AWS IAM에 신원 제공자를 추가한 후에 다음과 같은 오류가 발생할 수 있습니다: 

요청에 문제가 있습니다. 다음 세부 사항을 참조하십시오.
  - 신원 제공자의 openid 구성에 연결할 수 없습니다: `https://gitlab.example.com`

이 오류는 OIDC 신원 제공자의 발급자에서 순서가 잘못된 인증서 체인 또는 중복 또는 추가 인증서가 포함된 경우 발생합니다.

GitLab 인스턴스의 인증서 체인을 확인합니다. 체인은 도메인 또는 발급자 URL로 시작하여 중간 인증서로 이어지고 루트 인증서로 끝나야 합니다. 인증서 체인을 검토하려면 GitLab 호스트 이름을 사용하여 다음 명령을 사용하십시오: 

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

identity provider에서 검증 키를 검색할 수 없음

다음과 유사한 오류를 받을 수 있습니다:

  • An error occurred (InvalidIdentityToken) when calling the AssumeRoleWithWebIdentity operation: Couldn't retrieve verification key from your identity provider, please reference AssumeRoleWithWebIdentity documentation for requirements

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

  • identity provider(IdP)의 .well_known URL 및 jwks_uri가 공개 인터넷에서 접근할 수 없음.
  • 사용자 정의 방화벽이 요청을 차단하고 있음.
  • IdP에서 AWS STS 엔드포인트에 도달하는 API 요청의 지연이 5초 이상 발생함.
  • STS가 .well_known URL 또는 IdP의 jwks_uri로 너무 많은 요청을 수행함.

이 오류에 대한 AWS Knowledge Center 기사에 기록된 바에 따르면 GitLab 인스턴스는 .well_known URL 및 jwks_uri를 해결할 수 있도록 공개적으로 접근 가능해야 합니다. 이게 불가능한 경우, 예를 들어 GitLab 인스턴스가 오프라인 환경에 있는 경우, 현재 문제를 해결하고 보다 지속적인 솔루션을 조사 중인 이슈 #391928를 참조하십시오.