Azure에서 OpenID Connect 구성하여 임시 자격 증명 가져오기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
caution
CI_JOB_JWT_V2는 GitLab 15.9에서
더 이상 사용되지 않으며 GitLab 17.0에서 제거될 예정입니다. 대신 ID tokens를 사용하세요.

이 튜토리얼은 GitLab CI/CD 작업에서 JSON 웹 토큰(JWT)을 사용하여
Azure에서 임시 자격 증명을 가져오는 방법을 보여줍니다.
비밀을 저장할 필요가 없습니다.

시작하려면 GitLab과 Azure 간의 ID 연합을 위해 OpenID Connect(OIDC)를 구성하세요.
GitLab에서 OIDC를 사용하는 방법에 대한 자세한 내용은 클라우드 서비스에 연결하기를 읽어보세요.

Azure는 조건부 역할의 주제에 대한 와일드카드 일치를 지원하지 않습니다.
Azure에 접근해야 하는 각 브랜치에 대해 별도의 자격 증명 구성을 생성해야 합니다.

전제 조건:

  • Owner 접근 수준이 있는 기존 Azure 구독에 접근할 수 있어야 합니다.
  • 최소한 Application Developer 접근 수준이 있는 해당 Azure Active Directory 테넌트에 접근할 수 있어야 합니다.
  • Azure CLI를 로컬에 설치해야 합니다.
    또는 모든 단계를 Azure Cloud Shell을 사용하여 진행할 수 있습니다.
  • GitLab 인스턴스는 Azure가 GitLab OIDC 엔드포인트에 연결할 수 있도록 인터넷에서 공개적으로 접근 가능해야 합니다.
  • GitLab 프로젝트가 필요합니다.

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

  1. Azure AD 애플리케이션 및 서비스 주체 만들기.
  2. Azure AD 연합된 신원 자격 증명 만들기.
  3. 서비스 주체에 대한 권한 부여.
  4. 임시 자격 증명 검색.

자세한 내용은 Azure의 워크로드 신원 연합 문서를 검토하세요.

Azure AD 애플리케이션 및 서비스 주체 만들기

Azure AD 애플리케이션 및 서비스 주체를 만들려면:

  1. Azure CLI에서 AD 애플리케이션을 생성합니다:

    appId=$(az ad app create --display-name gitlab-oidc --query appId -otsv)

    appId (애플리케이션 클라이언트 ID) 출력을 저장하십시오.
    나중에 GitLab CI/CD 파이프라인을 구성하는 데 필요합니다.

  2. 해당하는 서비스 주체를 생성합니다:

    az ad sp create --id $appId --query appId -otsv

Azure CLI 대신 Azure Portal을 사용하여 이러한 리소스를 생성할 수 있습니다.

Azure AD 연합된 신원 자격 증명 만들기

위의 Azure AD 애플리케이션에 대한 연합된 신원 자격 증명을 만들려면:

objectId=$(az ad app show --id $appId --query id -otsv)  

cat <<EOF > body.json  
{  
  "name": "gitlab-federated-identity",  
  "issuer": "https://gitlab.example.com",  
  "subject": "project_path:<mygroup>/<myproject>:ref_type:branch:ref:<branch>",  
  "description": "GitLab 서비스 계정 연합 신원",  
  "audiences": [  
    "https://gitlab.example.com"  
  ]  
}  
EOF  

az rest --method POST --uri "https://graph.microsoft.com/beta/applications/$objectId/federatedIdentityCredentials" --body @body.json

issuer, subject 또는 audiences의 값과 관련된 문제는
문제 해결 세부 정보를 참조하세요.

선택적으로 Azure Portal에서 Azure AD 애플리케이션과 Azure AD 연합 신원 자격 증명을 확인할 수 있습니다:

  1. Azure Active Directory 앱 등록
    화면을 열고 표시 이름 gitlab-oidc로 검색하여 적절한 앱 등록을 선택합니다.
  2. 개요 페이지에서 Application (client) ID, Object ID 및 Tenant ID와 같은 세부 정보를 확인할 수 있습니다.
  3. Certificates & secrets 섹션에서 Federated credentials로 이동하여
    Azure AD 연합 신원 자격 증명을 검토합니다.

서비스 주체에 대한 권한 부여

자격 증명을 생성한 후, 위의 서비스 주체가 Azure 리소스에 접근할 수 있도록 역할 할당을 사용하여 권한을 부여합니다:

az role assignment create --assignee $appId --role Reader --scope /subscriptions/<subscription-id>

구독 ID는 다음에서 찾을 수 있습니다:

위 명령은 전체 구독에 대해 읽기 전용 권한을 부여합니다. 조직의 맥락에서 최소 권한 원칙을 적용하는 방법에 대한 더 많은 정보는 Azure AD 역할에 대한 모범 사례를 읽어보세요.

임시 자격 증명 가져오기

Azure AD 애플리케이션과 연합 신원 자격 증명을 구성한 후, CI/CD 작업은 Azure CLI를 사용하여 임시 자격 증명을 가져올 수 있습니다:

default:
  image: mcr.microsoft.com/azure-cli:latest

variables:
  AZURE_CLIENT_ID: "<client-id>"
  AZURE_TENANT_ID: "<tenant-id>"

auth:
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com
  script:
    - az login --service-principal -u $AZURE_CLIENT_ID -t $AZURE_TENANT_ID --federated-token $GITLAB_OIDC_TOKEN
    - az account show

CI/CD 변수는 다음과 같습니다:

문제 해결

“일치하는 연합 신원 레코드가 없습니다”

ERROR: AADSTS70021: 제시된 주장에 대한 일치하는 연합 신원 레코드가 없습니다. 오류가 발생하면 다음을 확인하세요:

  • Azure AD 연합 신원 자격 증명에 정의된 Issuer, 예를 들어 https://gitlab.com 또는 귀하의 GitLab URL.
  • Azure AD 연합 신원 자격 증명에 정의된 Subject identifier, 예를 들어 project_path:<mygroup>/<myproject>:ref_type:branch:ref:<branch>.
    • gitlab-group/gitlab-project 프로젝트와 main 브랜치의 경우: project_path:gitlab-group/gitlab-project:ref_type:branch:ref:main.
    • mygroup과 myproject의 올바른 값은 GitLab 프로젝트에 접근할 때 URL을 확인하거나 프로젝트 개요 페이지 오른쪽 상단에서 Code를 선택하여 확인할 수 있습니다.
  • Azure AD 연합 신원 자격 증명에 정의된 Audience, 예를 들어 https://gitlab.com 또는 귀하의 GitLab URL.

이 설정과 함께 AZURE_CLIENT_ID 및 AZURE_TENANT_ID CI/CD 변수를 Azure 포털에서 검토할 수 있습니다:

  1. Azure Active Directory 앱 등록 뷰를 열고 표시 이름 gitlab-oidc를 검색하여 적절한 앱 등록을 선택합니다.
  2. 개요 페이지에서 Application (client) ID, Object ID, 및 Tenant ID와 같은 세부 정보를 확인할 수 있습니다.
  3. Certificates & secrets 아래의 Federated credentials로 이동하여 Azure AD 연합 신원 자격 증명을 검토합니다.

추가 세부 사항은 클라우드 서비스에 연결을 참조하세요.

Request to External OIDC endpoint failed 메시지

ERROR: AADSTS501661: Request to External OIDC endpoint failed.라는 오류가 발생하면

귀하의 GitLab 인스턴스가 인터넷에서 공개적으로 액세스할 수 있는지 확인해야 합니다.

Azure는 OIDC로 인증하기 위해 다음 GitLab 엔드포인트에 접근할 수 있어야 합니다:

  • GET /.well-known/openid-configuration
  • GET /oauth/discovery/keys

방화벽을 업데이트한 후에도 여전히 이 오류가 발생하면, Redis 캐시를 지우세요

그리고 다시 시도해 보세요.

No matching federated identity record found for presented assertion audience 메시지

ERROR: AADSTS700212: No matching federated identity record found for presented assertion audience 'https://gitlab.com'라는 오류가 발생하면

귀하의 CI/CD 작업이 올바른 aud 값을 사용하고 있는지 확인해야 합니다.

aud 값은 연합된 식별 자격 증명을 생성하는 데 사용된 청중과 일치해야 합니다.