이 튜토리얼은 GitLab CI/CD 잡에서 JSON 웹 토큰(JWT)을 사용하여 시크릿을 저장하지 않고 Azure에서 임시 자격 증명을 검색하는 방법을 설명합니다.

시작하려면 GitLab과 Azure 간의 ID 페더레이션을 위한 OpenID Connect(OIDC)를 구성합니다. GitLab과 함께 OIDC를 사용하는 자세한 내용은 클라우드 서비스에 연결을 읽어보세요.

사전 요구사항:

• Owner 접근 수준을 가진 기존 Azure 구독에 대한 접근 권한.
• 최소 Application Developer 접근 수준을 가진 해당 Microsoft Entra ID 테넌트에 대한 접근 권한.
• Azure CLI의 로컬 설치. 또는 Azure Cloud Shell을 사용하여 다음 모든 단계를 수행할 수 있습니다.
• Azure가 GitLab OIDC 엔드포인트에 연결해야 하므로 GitLab 인스턴스가 인터넷을 통해 공개적으로 접근 가능해야 합니다.
• GitLab 프로젝트.

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

1. Entra ID 애플리케이션 및 서비스 주체 생성.
2. Entra ID 페더레이션 ID 자격 증명 생성.
3. 서비스 주체에 대한 권한 부여.
4. 임시 자격 증명 검색.

Azure ID 페더레이션에 대한 자세한 내용은 워크로드 ID 페더레이션을 참조하세요.

Entra ID 애플리케이션 및 서비스 주체 생성#

GitLab을 위한 Entra ID 애플리케이션 및 서비스 주체를 생성하려면:

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

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

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

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

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

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

Entra ID 페더레이션 ID 자격 증명 생성#

<mygroup>/<myproject>의 특정 브랜치에 대한 이전 Entra ID 애플리케이션의 페더레이션 ID 자격 증명을 생성하려면:

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

cat < 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 Portal에서 Entra ID 애플리케이션과 Entra ID 페더레이션 ID 자격 증명을 확인할 수 있습니다:

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

모든 브랜치 또는 태그에 대한 자격 증명 생성#

모든 브랜치 또는 태그에 대한 자격 증명을 생성하려면(와일드카드 매칭) 유연한 페더레이션 ID 자격 증명을 사용할 수 있습니다.

<mygroup>/<myproject>의 모든 브랜치에 대해:

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

cat < body.json
{
  "name": "gitlab-federated-identity",
  "issuer": "https://gitlab.example.com",
  "subject": null,
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'project_path:<mygroup>/<myproject>:ref_type:branch:ref:*'",
    "languageVersion": 1
  },
  "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

<mygroup>/<myproject>의 모든 태그에 대해:

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

cat < body.json
{
  "name": "gitlab-federated-identity",
  "issuer": "https://gitlab.example.com",
  "subject": null,
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'project_path:<mygroup>/<myproject>:ref_type:tag:ref:*'",
    "languageVersion": 1
  },
  "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

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

자격 증명을 생성한 후 role assignment를 사용하여 이전 서비스 주체에 권한을 부여하여 Azure 리소스에 접근할 수 있도록 합니다:

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

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

• Azure Portal.
• Azure CLI.

이전 명령은 전체 구독에 읽기 전용 권한을 부여합니다. 조직의 컨텍스트에서 최소 권한 원칙을 적용하는 방법에 대한 자세한 내용은 Entra ID 역할 모범 사례를 읽어보세요.

임시 자격 증명 검색#

Entra ID 애플리케이션 및 페더레이션 ID 자격 증명을 구성한 후 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 변수는:

• AZURE_CLIENT_ID: 이전에 저장한 애플리케이션 클라이언트 ID.
• AZURE_TENANT_ID: Microsoft Entra ID 테넌트 ID. Azure CLI 또는 Azure Portal을 사용하여 찾을 수 있습니다.
• GITLAB_OIDC_TOKEN: OIDC ID 토큰.

트러블슈팅#

오류: No matching federated identity record found#

ERROR: AADSTS70021: No matching federated identity record found for presented assertion. 오류가 발생하면 다음을 확인해야 합니다:

• Entra ID 페더레이션 ID 자격 증명에 정의된 Issuer, 예를 들어 https://gitlab.com 또는 자체 GitLab URL.
• Entra ID 페더레이션 ID 자격 증명에 정의된 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를 선택하여 검색할 수 있습니다.
• Entra ID 페더레이션 ID 자격 증명에 정의된 Audience, 예를 들어 https://gitlab.com 또는 자체 GitLab URL.

Azure Portal에서 이러한 설정 및 AZURE_CLIENT_ID와 AZURE_TENANT_ID CI/CD 변수를 검토할 수 있습니다:

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

자세한 내용은 클라우드 서비스에 연결을 검토하세요.

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 값은 페더레이션 ID 자격 증명을 생성할 때 사용된 audience와 일치해야 합니다.