Azure에서 임시 자격 증명을 검색하도록 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 토큰을 사용하십시오.

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

시작하려면 GitLab과 Azure 사이의 식별 페더레이션을 위해 OpenID Connect (OIDC)를 구성하십시오. GitLab에서 OIDC를 사용하는 자세한 내용은 클라우드 서비스에 연결을 참조하십시오.

Azure는 조건부 역할의 subjects에 와일드카드 일치를 지원하지 않음. Azure에 액세스해야 하는 각 브랜치마다 별도의 자격 증명 구성을 생성해야 합니다.

필수 사항:

  • Owner 액세스 수준이 있는 기존 Azure 구독에 액세스할 수 있어야 합니다.
  • 최소한 Application Developer 액세스 수준이 있는 해당 Azure Active Directory 테넌트에 액세스할 수 있어야 합니다.
  • Azure CLI의 로컬 설치. 또는 Azure Cloud Shell의 모든 단계를 따를 수 있습니다.
  • Azure는 인터넷을 통해 GitLab OIDC 엔드포인트에 연결해야 하므로 GitLab 인스턴스가 인터넷에서 접근 가능해야 합니다.
  • GitLab 프로젝트.

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

  1. Azure AD application 및 service principal 생성.
  2. Azure AD federated identity 자격 증명 생성.
  3. service principal에 대한 권한 부여.
  4. 임시 자격 증명 검색.

자세한 내용은 Azure의 Workload identity federation 문서를 확인하십시오.

Azure AD 애플리케이션 및 service principal 생성

Azure AD 애플리케이션 및 service principal을 생성하려면:

  1. Azure CLI에서 AD 애플리케이션을 생성하십시오: 

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

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

  2. 해당 Service Principal을 만듭니다: 

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

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

Azure AD federated identity 자격 증명 생성

위의 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 service account federated identity",
  "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 AD 애플리케이션 및 Azure AD federated identity 자격 증명을 Azure Portal에서 확인할 수 있습니다:

  1. Azure Active Directory App Registration 보기에서 gitlab-oidc 표시 이름을 검색하여 해당 앱 등록을 선택하십시오.
  2. 개요 페이지에서 Application (client) ID, Object ID 및 Tenant ID와 같은 세부 정보를 확인할 수 있습니다.
  3. Certificates & secrets 아래로 이동하여 Federated credentials로 이동하여 Azure AD federated identity 자격 증명을 검토할 수 있습니다.

service principal에 대한 권한 부여

자격 증명을 생성한 후에는 role assignment 를 사용하여 위의 service principal에 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: No matching federated identity record found for presented assertion. 오류가 발생하면 다음을 확인해야 합니다:

  • 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 Portal에서 AZURE_CLIENT_ID 및 AZURE_TENANT_ID CI/CD 변수와 함께 이러한 설정을 검토할 수 있습니다.

  1. Azure Active Directory 앱 등록 보기를 열고 디스플레이 이름 gitlab-oidc을 검색하여 적절한 앱 등록을 선택하세요.
  2. 개요 페이지에서 Application (client) ID, 오브젝트 ID 및 테넌트 ID와 같은 세부 정보를 확인할 수 있습니다.
  3. Certificates & secrets에서 Federated credentials로 이동하여 Azure AD 연합 신원 자격 증명을 검토하세요.

자세한 내용은 클라우드 서비스에 연결를 참조하세요.

외부 OIDC 엔드포인트로의 요청 실패 메시지

ERROR: AADSTS501661: Request to External OIDC endpoint failed. 오류가 발생하면 GitLab 인스턴스가 인터넷에서 공개적으로 접근 가능한지 확인해야 합니다.

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

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

방화벽을 업데이트했음에도 이 오류가 발생하는 경우 Redis 캐시를 지워 다시 시도하십시오.

제시된 주장 청중을 위한 일치하는 연합 신원 레코드를 찾을 수 없음 메시지

ERROR: AADSTS700212: No matching federated identity record found for presented assertion audience 'https://gitlab.com' 오류가 발생하면 CI/CD 작업이 올바른 aud 값 사용을 확인해야 합니다.

aud 값은 연합 신원 자격 증명을 생성할 때 사용된 청중과 일치해야 합니다.