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 토큰을 사용하십시오.

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

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

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

신원 공급자 추가

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

다음 정보를 포함하세요:

  • 공급자 URL: https://gitlab.com 또는 http://gitlab.example.com과 같이 귀하의 GitLab 인스턴스 주소. 이 주소는 공개적으로 접근 가능해야 합니다.
  • 수신자: https://gitlab.com 또는 http://gitlab.example.com과 같이 귀하의 GitLab 인스턴스 주소.
    • 주소에 https://를 포함해야 합니다.
    • 슬래시(‘/’)로 끝나도록 하지 마십시오.

역할 및 신뢰 구성

신원 공급자를 생성한 후, GitLab 자원에 대한 액세스를 제한하는 조건으로 웹 신원 역할을 구성합니다. 임시 자격 증명은 AWS 보안 토큰 서비스를 사용하여 얻으므로 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 보안 토큰 서비스 (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

실제 예시

Troubleshooting

AssumeRoleWithWebIdentity 작업을 호출할 때 오류가 발생했습니다 (AccessDenied): sts:AssumeRoleWithWebIdentity를 수행할 권한이 없습니다

이 오류는 여러 이유로 발생할 수 있습니다:

  • 클라우드 관리자가 프로젝트를 OIDC와 GitLab을 사용하도록 구성하지 않았을 수 있습니다.
  • 역할이 브랜치 또는 태그에서 실행되는 것을 제한될 수 있습니다. 조건부 역할을 구성을 참조하세요.
  • 와일드카드 조건 사용 시 StringEquals가 아닌 StringLike를 사용한 경우 해당 관련 이슈를 참조하세요.

openid 구성에 대한 Identity Provider에 연결할 수 없는 오류

AWS IAM에서 Identity Provider를 추가한 후 다음과 같은 오류가 발생할 수 있습니다: 

요청에 문제가 있습니다. 다음 세부 정보를 확인하세요.
  - Identity Provider의 `https://gitlab.example.com` openid 구성에 연결할 수 없습니다.

이 오류는 OIDC Identity Provider의 발행자가 순서가 잘못된 인증서 체인이거나 중복 또는 추가적인 인증서를 포함하는 경우 발생합니다.

GitLab 인스턴스의 인증서 체인을 확인하세요. 체인은 도메인 또는 발행자 URL로 시작하고 중간 인증서로 계속되며 루트 인증서로 끝나야 합니다. 다음 명령을 사용하여 인증서 체인을 확인하세요. gitlab.example.com을 GitLab 호스트 이름으로 바꿔 사용하세요: 

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

Identity Provider로부터 검증 키를 검색할 수 없는 오류

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

  • AssumeRoleWithWebIdentity 작업을 호출할 때 오류가 발생했습니다(InvalidIdentityToken): Identity Provider로부터 검증 키를 검색할 수 없습니다. 요구 사항에 대한 자세한 내용은 AssumeRoleWithWebIdentity 문서를 참조하세요.

이 오류의 이유는 다음과 같을 수 있습니다:

  • Identity Provider (IdP)의 .well_known URL 및 jwks_uri가 공개 인터넷에서 접근할 수 없음
  • 사용자 정의 방화벽이 요청을 차단하는 경우
  • IdP에서 AWS STS 엔드포인트에 도달하는 API 요청에 5초 이상의 대기시간이 있음
  • STS가 IdP의 .well_known URL이나 IdP의 jwks_uri로 너무 많은 요청을 수행함

이 오류에 대한 AWS Knowledge Center 기사에 기록된 대로 GitLab 인스턴스는 .well_known URL 및 jwks_uri를 해결할 수 있도록 공개적으로 접근 가능해야 합니다. 이게 불가능한 경우 예를 들어 GitLab 인스턴스가 오프라인 환경에 있는 경우 이슈 #391928를 참조하여 현재 수립 중인 해결책 및 더 영구적인 해결 방법을 따를 수 있습니다.