공지사항 📌

마지막 업데이트 날짜: 2026-03-01

공통 변경사항

보안 권고 사항에 따라, 진단 계정 등록 시 CSP사에서 자체적으로 발급받은 엑세스 키 사용을 중지하고 최소 권한만을 갖는 서비스 계정 생성 후 워크로드 인증 절차를 따를 것을 권고드립니다.

  • CSP별 진단 계정 등록 방법
    • AWS: Access Key + Secret Key -> IAM Role ARN 등록 (IRSA 인증) - 기존과 동일
    • GCP: Service Account Key File 업로드 -> Credential Configuration File 업로드 (Workload Identity Federation 구성)
    • Azure: Client Secret Key 미사용 (Workload Identity Federation 구성)

또한 진단 계정 등록 시 아래와 같이 인증 방식을 선택(택1)하도록 변경되었으며, 계정 진단 시 선택한 인증 방식으로만 진행됩니다.

Guide-Account-Authentication-1

미사용 엑세스 키는 추후 삭제될 예정이며, 기간은 별도 공지드리겠습니다.

감사합니다.


Azure 진단 계정 등록 (Cloud Shell)

개요

이 가이드는 Azure Cloud Shell 또는 Azure CLI를 사용하여 CQI 진단을 위한 Azure Workload Identity Federation을 설정하는 방법을 단계별로 안내합니다.

1. 사전 요구사항

1-1. CQI 서비스 제공 정보

다음 정보는 CQI 서비스에서 제공하는 고정 값입니다:

항목 값
EKS OIDC Issuer URL https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27
EKS Namespace cqi-prod-app-ns
EKS Service Account cqi-prod-app-sa

위 정보는 Federated Credential 설정 시 그대로 사용하세요.


1-2. 필요한 권한

  • Azure:
    • Azure AD에서 애플리케이션 생성 권한
    • Subscription에서 RBAC 역할 할당 권한 (예: Owner, User Access Administrator)

1-3. 필요한 정보

아래 정보를 미리 수집해두세요:

  • Azure Subscription ID

1-4. Azure CLI 설정

Azure Cloud Shell 또는 로컬 환경에서 Azure CLI를 사용합니다.

# Azure CLI 버전 확인
az --version

# Azure 로그인 (로컬 환경인 경우)
az login

# 구독 설정
az account set --subscription "<Subscription ID>"

# 현재 구독 확인
az account show --output table

2. Azure AD 애플리케이션 등록

CQI 서비스가 Azure 리소스에 접근할 수 있도록 Azure AD에 애플리케이션 신원을 등록합니다. 이 단계에서 생성되는 Application (client) ID와 Directory (tenant) ID가 CQI 진단 계정 등록에 사용됩니다.

2-1. 변수 설정

# 변수 설정 (환경에 맞게 수정)
APP_NAME="CQI-Workload-Identity"

2-2. 애플리케이션 등록

# 애플리케이션 (Single Tenant)
az ad app create \
  --display-name "$APP_NAME" \
  --sign-in-audience AzureADMyOrg

출력 예시:

{
  "appId": "8339577f-971b-4d85-a206-c6c7eb654fcf",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "displayName": "CQI-Workload-Identity",
  ...
}

2-3. 필수 정보 기록

# Application (client) ID 조회
APP_ID=$(az ad app list --display-name "$APP_NAME" --query "[0].appId" --output tsv)
echo "Application (client) ID: $APP_ID"

# Directory (tenant) ID 조회
TENANT_ID=$(az account show --query "tenantId" --output tsv)
echo "Directory (tenant) ID: $TENANT_ID"
항목 예시 용도
Application (client) ID 8339577f-971b-4d85-a206-c6c7eb654fcf CQI 계정 등록에 사용
Directory (tenant) ID c5cb8008-8404-4eb7-99d2-c12f067410c1 CQI 계정 등록에 사용

참고: 이 두 값은 공개 정보이므로 안전하게 공유 가능합니다. Secret이 아닙니다.


2-4. Service Principal 생성

애플리케이션에 연결된 Service Principal을 생성합니다.

# Service Principal 생성
az ad sp create --id $APP_ID

3. Federated Credentials 추가

이 단계에서 CQI 서비스(AWS EKS)가 Azure AD App을 인증할 수 있도록 신뢰 관계를 설정합니다.

3-1. 변수 설정

# CQI 서비스 제공 정보 (고정 값)
EKS_OIDC_ISSUER="https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27"
EKS_NAMESPACE="cqi-prod-app-ns"
EKS_SERVICE_ACCOUNT="cqi-prod-app-sa"
CREDENTIAL_NAME="cqi-eks-federation"

3-2. Federated Credential JSON 생성

# Federated Credential 설정 파일 생성
cat > federated-credential.json << EOF
{
  "name": "$CREDENTIAL_NAME",
  "issuer": "$EKS_OIDC_ISSUER",
  "subject": "system:serviceaccount:$EKS_NAMESPACE:$EKS_SERVICE_ACCOUNT",
  "audiences": ["api://AzureADTokenExchange"],
  "description": "Federated credential for EKS workload identity"
}
EOF
필드 값 설명
name cqi-eks-federation Federated Credential 식별 이름
issuer CQI EKS OIDC Issuer URL CQI EKS 클러스터의 OIDC 발급자 URL (고정 값)
subject system:serviceaccount:cqi-prod-app-ns:cqi-prod-app-sa 신뢰할 Kubernetes Service Account (고정 값)
audiences api://AzureADTokenExchange Azure AD 토큰 교환 대상 (고정 값)
description Federated credential for EKS workload identity 설명 (선택 사항)

3-3. Federated Credential 추가

# Application Object ID 조회
APP_OBJECT_ID=$(az ad app list --display-name "$APP_NAME" --query "[0].id" --output tsv)

# Federated Credential 추가
az ad app federated-credential create \
  --id $APP_OBJECT_ID \
  --parameters federated-credential.json

출력 예시:

{
  "audiences": ["api://AzureADTokenExchange"],
  "description": "Federated credential for EKS workload identity",
  "id": "12345678-1234-1234-1234-123456789012",
  "issuer": "https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27",
  "name": "cqi-eks-federation",
  "subject": "system:serviceaccount:cqi-prod-app-ns:cqi-prod-app-sa"
}

3-4. Federated Credential 확인

# 등록된 Federated Credential 목록 확인
az ad app federated-credential list --id $APP_OBJECT_ID --output table

4. Azure RBAC 역할 할당

애플리케이션에 Azure 리소스에 접근할 수 있는 권한을 부여합니다.

참고: 필요한 역할

CQI 서비스가 호출하는 Azure API에 따라 다음 역할이 필요합니다:

Azure API 필요 역할 Scope
Security Assessment API Security Reader Subscription
Advisor API Reader Subscription
Cognitive Services API Reader Subscription

권장: Reader 역할 하나만 Subscription 레벨에 할당하면 모든 API 호출 가능

4-1. 역할 할당

# 변수 설정
SUBSCRIPTION_ID=$(az account show --query "id" --output tsv)

# Reader 역할 할당
az role assignment create \
  --role "Reader" \
  --assignee $APP_ID \
  --scope /subscriptions/$SUBSCRIPTION_ID

# Security Reader 역할 할당 (Security Assessment API 사용 시)
az role assignment create \
  --role "Security Reader" \
  --assignee $APP_ID \
  --scope /subscriptions/$SUBSCRIPTION_ID

4-2. 역할 할당 확인

# 할당된 역할 확인
az role assignment list \
  --assignee $APP_ID \
  --subscription $SUBSCRIPTION_ID \
  --output table

출력 예시:

Principal                             Role             Scope
------------------------------------  ---------------  ----------------------------------------
8339577f-971b-4d85-a206-c6c7eb654fcf  Reader           /subscriptions/12345678-1234-...
8339577f-971b-4d85-a206-c6c7eb654fcf  Security Reader  /subscriptions/12345678-1234-...

5. 설정 검증

Azure 설정이 완료되었습니다. 이제 설정을 검증해봅시다.

5-1. Azure CLI에서 확인

# 애플리케이션 정보 확인
echo "=== 애플리케이션 정보 ==="
echo "Application (client) ID: $APP_ID"
echo "Directory (tenant) ID: $TENANT_ID"
echo "App Name: $APP_NAME"

# 페더레이션 자격 증명 확인
echo ""
echo "=== Federated Credentials ==="
az ad app federated-credential list --id $APP_OBJECT_ID --query "[].{Name:name, Issuer:issuer, Subject:subject}" --output table

# 역할 할당 확인
echo ""
echo "=== Role Assignments ==="
az role assignment list --assignee $APP_ID --output table

5-2. 정보 정리

다음 정보를 CQI 계정 등록에 사용합니다:

# Azure Federated Identity 정보
Tenant ID: <생성된 Tenant ID>
Client ID: <생성된 Client ID>
Subscription ID: <Subscription ID>

Client Secret 없음: Federated Identity는 Client Secret이 필요하지 않습니다!


CQI 진단 계정 등록

위에서 수집한 정보를 CQI 서비스에 등록합니다.

  1. CQI에 로그인
  2. 진단 계정 목록(Account List) 페이지로 이동
  3. 진단 계정 추가(Add Account) 버튼 클릭
  4. CSP로 Azure 선택
  5. 인증 방식에서 Workload Identity Federation 선택
  6. 다음 정보 입력:
    • Tenant ID: 생성된 Tenant ID
    • Client ID: 생성된 Client ID
    • Subscription ID: Subscription ID
  7. 필요한 정보 입력 후 등록

진단 계정 등록


참고: 트러블슈팅

문제 1: "AADSTS70021: No matching federated identity record found"

원인: Federated Credential의 Subject가 실제 EKS Service Account Token과 일치하지 않음

해결:

  1. Federated Credential의 Subject 확인:
    az ad app federated-credential list --id $APP_OBJECT_ID --query "[].subject" --output tsv
  2. Subject가 정확히 다음 값인지 확인:
    system:serviceaccount:cqi-prod-app-ns:cqi-prod-app-sa

문제 2: "AADSTS50107: The requested federation realm object does not exist"

원인: Cluster issuer URL이 잘못됨

해결:

  1. Federated Credential의 Issuer 확인:
    az ad app federated-credential list --id $APP_OBJECT_ID --query "[].issuer" --output tsv
  2. Issuer가 정확히 다음 값인지 확인:
    https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27

문제 3: "AADSTS700016: Application with identifier was not found"

원인: Client ID가 잘못되었거나 애플리케이션이 삭제됨

해결:

  1. 애플리케이션 존재 여부 확인:
    az ad app list --display-name "$APP_NAME" --output table
  2. Application (client) ID 재확인:
    az ad app list --display-name "$APP_NAME" --query "[0].appId" --output tsv
  3. 올바른 Tenant에서 작업하고 있는지 확인:
    az account show --query "{Tenant:tenantId, Subscription:name}" --output table

문제 4: Token exchange는 성공하지만 Azure API 호출 실패

원인: RBAC 역할이 할당되지 않았거나 부족함

해결:

  1. 역할 할당 확인:
    az role assignment list --assignee $APP_ID --output table
  2. 필요한 역할이 할당되었는지 확인
  3. 역할이 Subscription 레벨에 할당되었는지 확인 (Resource Group 레벨이 아님)

참고: 전체 스크립트 (One-Shot)

#!/bin/bash
# Azure Workload Identity Federation 설정 스크립트

set -e

# === 변수 설정 ===
APP_NAME="CQI-Workload-Identity"

# CQI 서비스 제공 정보 (고정 값)
EKS_OIDC_ISSUER="https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27"
EKS_NAMESPACE="cqi-prod-app-ns"
EKS_SERVICE_ACCOUNT="cqi-prod-app-sa"
CREDENTIAL_NAME="cqi-eks-federation"

# === 1. 애플리케이션 생성 ===
echo "Creating 애플리케이션..."
az ad app create --display-name "$APP_NAME" --sign-in-audience AzureADMyOrg

# === 2. 필수 정보 조회 ===
APP_ID=$(az ad app list --display-name "$APP_NAME" --query "[0].appId" --output tsv)
APP_OBJECT_ID=$(az ad app list --display-name "$APP_NAME" --query "[0].id" --output tsv)
TENANT_ID=$(az account show --query "tenantId" --output tsv)
SUBSCRIPTION_ID=$(az account show --query "id" --output tsv)

echo "Application (client) ID: $APP_ID"
echo "Directory (tenant) ID: $TENANT_ID"

# === 3. Service Principal 생성 ===
echo "Creating Service Principal..."
az ad sp create --id $APP_ID

# === 4. Federated Credential 추가 ===
echo "Adding Federated Credential..."
cat > federated-credential.json << EOF
{
  "name": "$CREDENTIAL_NAME",
  "issuer": "$EKS_OIDC_ISSUER",
  "subject": "system:serviceaccount:$EKS_NAMESPACE:$EKS_SERVICE_ACCOUNT",
  "audiences": ["api://AzureADTokenExchange"]
}
EOF
az ad app federated-credential create --id $APP_OBJECT_ID --parameters federated-credential.json
rm -f federated-credential.json

# === 5. RBAC 역할 할당 ===
echo "Assigning RBAC roles..."
az role assignment create --role "Reader" --assignee $APP_ID --scope /subscriptions/$SUBSCRIPTION_ID
az role assignment create --role "Security Reader" --assignee $APP_ID --scope /subscriptions/$SUBSCRIPTION_ID

# === 6. 설정 확인 ===
echo ""
echo "=== 설정 완료 ==="
echo "Application (client) ID: $APP_ID"
echo "Directory (tenant) ID: $TENANT_ID"
echo "Subscription ID: $SUBSCRIPTION_ID"
echo ""
echo "Federated Credentials:"
az ad app federated-credential list --id $APP_OBJECT_ID --output table
echo ""
echo "Role Assignments:"
az role assignment list --assignee $APP_ID --output table

참조


문서 버전: 1.1 최종 수정일: 2026-03-01 담당자: CQI AX운영최적화팀(cloud-tech@lgcns.com)

진단 계정 등록 가이드