공지사항 📌

마지막 업데이트 날짜: 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 진단 계정 등록 (Portal)

개요

이 가이드는 **Azure Portal (GUI)**을 사용하여 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

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

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

2-1. Azure Portal 접속

  1. Azure Portal 접속
  2. 상단 검색창에 "Azure Active Directory" 또는 "Microsoft Entra ID" 입력
  3. 클릭하여 Azure AD 관리 페이지로 이동

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

  1. 왼쪽 메뉴에서 "앱 등록" 클릭
  2. 상단의 "+ 새 등록" 버튼 클릭
  3. 다음 정보 입력:
항목 값
Name CQI-Workload-Identity (또는 원하는 이름)
Supported account types 단일 테넌트만 - Accounts in this organizational directory 선택
Redirect URI 비워두기 (필요 없음)
  1. "등록" 버튼 클릭

2-3. 필수 정보 기록

애플리케이션이 등록되면 개요 페이지에서 다음 정보를 기록합니다:

항목 예시 용도
Application (client) ID 8339577f-971b-4d85-a206-c6c7eb654fcf CQI 계정 등록에 사용
Directory (tenant) ID c5cb8008-8404-4eb7-99d2-c12f067410c1 CQI 계정 등록에 사용

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

가이드 사진 접기 / 펼치기

먼저 Microsoft Entra ID 페이지로 접속합니다.

Guide-Azure-Portal-1
Guide-Azure-Portal-2

  • 다음 정보를 입력:
항목 값
Name CQI-Workload-Identity (또는 원하는 이름)
Supported account types 단일 테넌트만 - Accounts in this organizational directory 선택
Redirect URI 비워두기 (필요 없음)

Guide-Azure-Portal-3
Guide-Azure-Portal-4


3. Federated Credentials 추가

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

3-1. 인증서 및 암호 메뉴 이동

  1. 생성한 애플리케이션 (예: CQI-Workload-Identity) 클릭
  2. 왼쪽 메뉴에서 "인증서 및 암호" 클릭
  3. 상단 탭에서 "페더레이션 자격 증명" 선택
  4. "+ 자격 증명 추가" 버튼 클릭

3-2. Federated Credential 설정

페더레이션된 자격 증명 시나리오 선택:

  • "Azure 리소스에 엑세스하려는 Kubernetes" 선택
  • 또는 "Other issuer" 선택 (더 유연함)

입력 값:

필드 값 설명
Federated credential scenario Azure 리소스에 엑세스하려는 Kubernetes 시나리오 선택
Cluster issuer URL https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27 CQI 서비스 제공 EKS OIDC Issuer URL
Namespace cqi-prod-app-ns EKS Namespace
Service account cqi-prod-app-sa EKS Service Account 이름
Name cqi-eks-federation Credential 식별 이름 (자유롭게 작성)
Description Federated credential for EKS workload identity Credential 설명 (선택 사항)

중요: Namespace와 Service account는 정확히 위 값과 일치해야 합니다!

입력을 완료하면 주체 식별자(Subject) 및 대상 그룹(Audience) 필드는 자동으로 값이 설정됩니다:

  • system:serviceaccount:cqi-prod-app-ns:cqi-prod-app-sa

  • api://AzureADTokenExchange

    이 값이 올바른지 확인하세요.


3-3. Federated Credential 추가

모든 값을 확인한 후 "추가" 버튼을 클릭하여 저장합니다.

가이드 사진 접기 / 펼치기

앱 등록 페이지에서 앞서 생성한 애플리케이션을 클릭하여 이동한 후 아래 절차를 수행합니다.

Guide-Azure-Portal-5

다음 정보를 입력:

필드 값 설명
Federated credential scenario Azure 리소스에 엑세스하려는 Kubernetes 시나리오 선택
Cluster issuer URL https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27 CQI 서비스 제공 EKS OIDC Issuer URL
Namespace cqi-prod-app-ns EKS Namespace
Service account cqi-prod-app-sa EKS Service Account 이름
Name cqi-eks-federation Credential 식별 이름 (자유롭게 작성)
Description Federated credential for EKS workload identity Credential 설명 (선택 사항)

Guide-Azure-Portal-6


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. 역할 할당

  1. Azure Portal에서 "구독" 검색
  2. 진단 대상 구독 선택
  3. 왼쪽 메뉴에서 "액세스 제어 (IAM)" 클릭
  4. "+ 추가" → "역할 할당 추가" 클릭
  5. 다음 정보 입력:

  • 역할 탭:

    • 역할: "독자" 선택
    • "다음" 클릭

  • 구성원 탭:

    • 선택한 역할: 독자
    • 다음에 대한 엑세스 할당: "사용자, 그룹 또는 서비스 주체" 선택
    • "+ 구성원 선택" 클릭
    • 검색창에 애플리케이션 이름 입력 (예: CQI-Workload-Identity)
    • 나타난 항목 선택
    • "선택" 클릭
    • "다음" 클릭

  • 검토 + 할당 탭:

    • 설정 확인 후 "검토 + 할당" 클릭

4-2. 역할 할당 확인

  1. 구독의 "액세스 제어 (IAM)" 페이지
  2. "역할 할당" 탭 클릭
  3. 검색창에 애플리케이션 이름 입력하여 확인
가이드 사진 접기 / 펼치기

진단하려는 구독 페이지로 이동한 후 액세스 제어(IAM) 메뉴에서 아래 절차를 수행합니다.

Guide-Azure-Portal-7
Guide-Azure-Portal-8
Guide-Azure-Portal-9
Guide-Azure-Portal-10
Guide-Azure-Portal-11


5. 설정 검증

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


5-1. Azure Portal에서 확인

  1. 애플리케이션 개요:

    • Application (client) ID 확인
    • Directory (tenant) ID 확인

  2. 페더레이션 자격 증명:

    • Credential 이름: cqi-eks-federation
    • Issuer: https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27
    • Subject: system:serviceaccount:cqi-prod-app-ns:cqi-prod-app-sa
    • Audience: api://AzureADTokenExchange

  3. 역할 할당 확인 (구독 레벨):

    • Reader 역할 할당됨

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. Azure Portal에서 Federated Credential의 Subject 확인:
    system:serviceaccount:<namespace>:<service-account-name>
  2. 다음 값과 정확히 일치하는지 확인:
    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 확인
  2. 다음 값과 정확히 일치하는지 확인:
    https://oidc.eks.ap-northeast-2.amazonaws.com/id/0397AF77891627E02A9621B2FB966E27

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

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

해결:

  1. Azure Portal에서 애플리케이션 존재 여부 확인
  2. Application (client) ID 재확인
  3. 올바른 Tenant에서 작업하고 있는지 확인

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

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

해결:

  1. Azure Portal → Subscription → Access control (IAM) → Role assignments 확인
  2. 애플리케이션에 필요한 역할이 할당되었는지 확인
  3. 역할이 Subscription 레벨에 할당되었는지 확인 (Resource Group 레벨이 아님)

참고: Subject 패턴

Federated Credential의 Subject는 다음 패턴을 따릅니다:

system:serviceaccount:<namespace>:<service-account-name>

CQI 서비스의 경우:

system:serviceaccount:cqi-prod-app-ns:cqi-prod-app-sa

이 패턴은 Kubernetes의 표준이며 변경할 수 없습니다.


참고: 여러 환경 지원

Dev, Staging, Production 등 여러 환경을 지원하려면:

옵션 1: 환경별 애플리케이션 생성

  • CQI-Workload-Identity-Dev
  • CQI-Workload-Identity-Staging
  • CQI-Workload-Identity-Prod

옵션 2: 하나의 애플리케이션에 여러 Federated Credential 추가

  • Credential 1: cqi-eks-dev (Namespace: cqi-dev-ns, SA: cqi-prod-app-sa)
  • Credential 2: cqi-eks-staging (Namespace: cqi-staging-ns, SA: cqi-prod-app-sa)
  • Credential 3: cqi-eks-prod (Namespace: cqi-prod-app-ns, SA: cqi-prod-app-sa)

참고: 보안 모범 사례

  1. 최소 권한 원칙:

    • 필요한 최소한의 역할만 할당
    • Subscription 전체가 아닌 Resource Group 레벨로 제한 가능

  2. 감사 로그 활성화:

    • Azure AD Sign-in logs 확인
    • Service Principal activity 모니터링

  3. 주기적 검토:

    • 사용하지 않는 Federated Credential 삭제
    • 불필요한 역할 할당 제거

  4. 네이밍 컨벤션:

    • 애플리케이션 이름에 용도와 환경 포함
    • 예: CQI-Workload-Identity-Prod-APNortheast2

참조


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

진단 계정 등록 가이드