멀티 테넌트 Entra ID 앱 등록 완전 정복: SPFx 편

By Mirko Peters · 2026-08-11

팟캐스트에 다시 오신 것을 환영합니다! 내 개발 테넌트에서 정성껏 만든 SharePoint Framework(SPFx) 솔루션을 고객 환경에 배포해 본 적이 있다면, 완전히 깨져 버렸을 때 느끼는 아찔함을 이미 아실 겁니다. 아무것도 나오지 않고, 웹 파트는 비어 있으며, 로그인 루프는 끝나지 않습니다. 테넌트 간 인증은 Microsoft 365 개발자에게 가장 가혹한 시험대이며, 이를 제대로 해내려면 Entra ID 앱 등록의 세부 사항, 동적 범위, 최소 권한 보안을 확실히 익혀야 합니다.

Automatically translated with AI from the original post. Read the English original

Titelbild: Mastering Multi-Tenant Entra ID App Registrations for SPFx

이번 종합 가이드에서는 최신 에피소드에서 다룬 내용을 더 자세히 풀어 봅니다. 오디오 대화를 더 깊이 있게 듣고 싶으시다면 Fix Multi-Tenant SPFx Authentication 상세 해설을 들어 보시기 바랍니다.

서론: 멀티 테넌트 SPFx가 어려운 이유

SPFx 애플리케이션을 신원 경계 너머로 옮기는 일은 흔히 "하드 모드"라고 불리며, 그럴 만한 이유가 있습니다. 단일 테넌트 안에서 개발할 때는 Entra ID, SharePoint 사이트 구조, API 권한이 대體로 암묵적이거나 전역 관리자 권한으로 쉽게 우회할 수 있습니다. 그러나 멀티 테넌트 모델에 들어서는 순간, 즉 웹 파트를 제품으로 만드는 독립 소프트웨어 공급업체(ISV)이든 여러 자회사 테넌트를 관리하는 내부 IT 팀이든, 이러한 지름길은 사라집니다.

이제는 엄격한 디렉터리 경계, 명시적인 관리자 승인이 필요한 동의 체계, 그리고 독특한 사이트 토폴로지를 다루게 됩니다. 앱 등록이 단일 테넌트로 잠겨 있거나 코드가 하드코딩된 환경 매개 변수에 의존한다면, 운영 환경 배포는 반드시 실패합니다.

대상 독자

기술적인 세부 사항을 살펴보기 전에, 이 아키텍처 패턴을 익혀야 할 사람이 누구인지 짚어 보겠습니다.

여러 테넌트에 배포하는 SPFx 개발자 및 Microsoft 365 컨설턴트로, 고객사마다 수동으로 재구성하는 일을 피하고자 하는 분들.
고객 SharePoint Online 환경을 지원하는 IT 관리자 및 MSP로, 최신 개발자 솔루션을 제공하면서도 엄격한 보안 태세를 유지해야 하는 분들.
SPFx 웹 파트 및 확장을 제품화하는 파트너 및 ISV로, 수많은 고객 테넌트에 걸쳐 반복 가능하고 확장 가능한 시장 진출 경로가 필요한 분들.

핵심 요약

멀티 테넌트 배포를 성공적으로 진행하려면 아키텍처의 최우선 원칙으로 다음 사항을 기억하십시오.

인증은 보일러플레이트가 아닙니다: 멀티 테넌트 Entra ID 앱을 사용하고 테넌트별 관리자 동의를 요구하며, 이러한 보안 상태를 런타임에 검증하십시오.
테넌트 정보를 절대 하드코딩하지 마십시오: URL, ID, 범위를 테넌트를 인식하는 구성 소스에서 동적으로 로드하고, 필요한 백엔드 비밀 값은 Azure Key Vault에 안전하게 저장하십시오.
Graph "빈 결과"가 곧 코드 오류는 아닙니다: Microsoft Graph가 빈 배열을 반환할 때는 거의 항상 동의 누락이나 디렉터리 데이터 및 필터 불일치 때문이며, 코드베이스의 구문 오류인 경우는 드뭅니다.
하나의 패키지, 여러 테넌트: SPFx 솔루션을 완전히 테넌트에 구애받지 않도록 설계하고, 테넌트 범위의 배포와 짝을 지어 고객마다 맞춤 빌드를 없애십시오.
실패를 일찍 발견하십시오: 테넌트별로 맞춘 Application Insights 또는 Azure Monitor를 사용해 텔레메트리와 상태 확인을 한곳에 모으십시오.

주요 내용

기술 탐구 과정에서 개발 수명 주기 전반에 걸쳐 반드시 다뤄야 할 몇 가지 핵심 이정표를 확인했습니다.

테넌트 간 롤아웃을 망치는 세 가지 인증 실수, 즉 단일 테넌트 앱 등록, 일회성 동의에 대한 오해, 그리고 비밀 값을 클라이언트 측 코드에 직접 넣는 문제를 다룹니다.
Microsoft Graph가 개발 테넌트에서는 문제없이 동작하지만 고객 환경에서는 결과가 전혀 나오지 않는 이유, 그리고 실제 운영 전에 이를 검증하는 방법을 설명합니다.
한 번 패키징하고 어디에나 구성하기: 진정으로 테넌트에 구애받지 않는 SPFx를 위한 아키텍처 청사진.
고객이 눈치채기 전에 조용한 구성 문제를 잡아내는 로깅 및 모니터링 전략.
높은 전달 속도를 유지하면서도 조직을 규정 준수 상태로 유지하는 거버넌스 구조.

빠른 시작 체크리스트(복사/붙여넣기)

Entra ID 앱 등록
- 지원되는 계정 유형: 다중 테넌트로 설정합니다.
- 최소 권한 원칙에 따라 필요한 위임된 Graph 범위를 정확히 정의합니다.
- SharePoint Online과 로컬 개발 환경을 모두 포함하도록 유효한 리디렉션 URI를 구성합니다.
SPFx 프로젝트 강화
- 위임된 API 호출에는 모두 MSGraphClient 또는 AadHttpClient를 사용합니다.
- 테넌트별 구성(엔드포인트, 대상 사이트 ID 등)은 전용 SharePoint 구성 목록이나 보안이 적용된 API에서 읽어오고, 프런트엔드 코드에는 비밀 값이 전혀 없도록 합니다.
- 런타임에 권한을 검사하여 권한이 없을 때는 직접 이동 링크가 포함된 "관리자 동의 필요" 배너를 자연스럽게 표시하도록 구현합니다.
동의 흐름
- 필요한 범위, 정확한 관리자 동의 URL, 검증 단계를 보여 주는 전용 테넌트 온보딩 페이지를 제공합니다.
- 조직 전체 롤아웃과 대상 파일럿 그룹을 구분하여, 대상 그룹별 동의 모델을 지원합니다.
패키징 및 배포
- 솔루션을 표준 .sppkg 파일로 한 번만 패키징하고, 적절한 경우 테넌트 범위 배포를 사용하도록 설정합니다.
- 중앙 앱 카탈로그를 통해 게시하고, 사이트 수준에서 앱을 추가하는 단계를 철저히 문서화합니다.
- 견고한 CI/CD 파이프라인(빌드, 번들, 패키지, 업로드, 배포)으로 릴리스 주기를 자동화합니다.
모니터링 및 지원
- 테넌트 ID, 상관 ID, 특정 기능, 오류 코드를 포함한 상세한 텔레메트리를 내보냅니다.
- 실행 가능한 경고와 함께 Application Insights 또는 Azure Monitor 대시보드를 연결합니다.
- 이전 패키지 버전을 사용하는 명확한 롤백 절차와 테넌트별 상세 버전 맵을 문서화합니다.

흔한 함정과 해결 방법

숙련된 개발자도 다중 테넌트 애플리케이션을 구성할 때 예측 가능한 함정에 빠지곤 합니다. 다음은 이러한 문제를 신속하게 진단하고 해결하는 방법입니다.

증상: 로그인이 반복되거나, "내 환경에서는 되는데 고객 환경에서는 안 되는" 답답한 상황이 발생합니다.
원인: Entra ID 앱 등록이 여전히 단일 테넌트로 구성되어 있거나, 응답 URL이 대상 환경과 일치하지 않습니다.
해결: 앱 등록을 다중 테넌트로 전환하고, 리디렉션 URI를 수정한 다음 새로운 동의 요청을 실행합니다.
증상: Microsoft Graph가 완전히 빈 데이터 집합을 반환합니다.
원인: 테넌트 관리자 동의가 누락되었거나 디렉터리 필터가 지나치게 제한적입니다.
해결: 올바른 관리자 동의 흐름을 실행하고, 고객 테넌트의 실제 사용자로 Graph Explorer에서 쿼리를 직접 테스트한 다음, 코드에 있는 엄격한 가정이나 필터를 완화합니다.
증상: 사용자가 페이지에 웹 파트를 추가할 수 없습니다.
원인: 패키지가 테넌트 앱 카탈로그에 올바르게 배포되지 않았거나, 조직의 앱 정책이 이를 차단하고 있습니다.
해결: 앱 카탈로그 배포 상태를 확인하고, 테넌트 앱 설정과 정책을 검토합니다.
증상: 고객사마다 사소한 구성 변경이 있을 때마다 패키지를 다시 빌드해야 합니다.
원인: 하드코딩된 ID, URL 또는 비밀 값이 번들에 직접 포함되어 있습니다.
해결: 구성을 외부로 분리하고, SharePoint 구성 목록 또는 Azure Key Vault를 활용하여 런타임에 이 값을 동적으로 읽어옵니다.

거버넌스 및 보안 필수 사항

외부 고객 디렉터리에 코드를 배포할 때 보안은 나중에 고려할 사항이 될 수 없습니다. 신뢰를 유지하려면 다음 거버넌스 필수 사항을 구현하십시오.

최소 권한 범위를 적용하고, 정기적인 범위 검토를 통해 사용하지 않는 권한을 제거합니다.
백엔드 애플리케이션 비밀 값은 Azure Key Vault에 안전하게 저장하고, 정기적인 순환 일정을 수립합니다.
Teams 및 SharePoint 앱 권한 정책을 활용하여 대상 사용자를 엄격하게 제한하고 무단 사용을 방지합니다.
누가 동의했는지, 언제 동의가 부여되었는지, 어떤 범위가 승인되었는지를 추적하는 포괄적인 동의 기록부를 유지합니다.
테넌트별 스타일 자산을 코드에 포함하는 대신, Microsoft 365 테마 API를 통해 웹 파트 브랜딩을 동적으로 맞춥니다.

검증 계획(고객 운영 전환 전)

절대로 무작정 배포하지 마십시오. 고객에게 솔루션을 선보이기 전에 다음 검증 계획을 진행합니다.

정확히 동일한 사용자 계정과 위임된 범위를 사용하여, 고객 테넌트 안에서 Graph Explorer로 모든 Microsoft Graph 호출을 직접 테스트합니다.
소수의 대상 사용자와 함께 격리된 단일 사이트 컬렉션에서 현지화된 파일럿 배포를 실행합니다.
SharePoint App Catalog에서 버전 기록과 롤백 기능을 직접 확인하십시오.
오프라인 상태와 만료된 토큰 시나리오를 실제로 테스트하여 오류 메시지와 자동 복구 흐름이 의도대로 동작하는지 확인하십시오.

자주 묻는 질문

SPFx에 애플리케이션 권한이 필요합니까?
일반적으로는 필요하지 않습니다. SPFx 솔루션은 위임된 사용자 컨텍스트에서 실행됩니다. 애플리케이션 권한은 추가적인 관리자 승인과 특수한 아키텍처 패턴을 요구하므로, 달리 실용적인 대안이 전혀 없는 경우에만 엄격하게 사용하십시오.

테넌트별 동의를 생략할 수 있습니까?
아니요. 각 고객 테넌트의 관리자가 애플리케이션이 요청한 범위(scope)를 명시적으로 승인해야 합니다. 다만 안내형 온보딩 화면과 런타임 알림 배너를 구현하면 이 과정을 훨씬 간소화할 수 있습니다.

여러 고객사를 위해 하나의 코드베이스를 어떻게 유지합니까?
솔루션을 테넌트에 종속되지 않도록 완전히 설계하고, 환경별 구성은 모두 외부화하며, 패키징과 배포 파이프라인을 자동화하십시오. 고객별 설정은 기능 플래그(feature flag)를 활용해 안전하게 관리하십시오.

"데이터가 비어 있음" 문제를 더 빨리 진단하려면 어떻게 합니까?
범위 검증 점검과 함께 Graph 원시 응답을 기록하십시오. 실패가 발생하면 "동의 누락 또는 범위 부족"이라는 문구와 함께, 문제를 즉시 해결할 수 있는 직접 딥 링크를 포함한 인라인 알림을 표시하십시오.

결론

SharePoint Framework 솔루션을 위한 다중 테넌트 Entra ID 앱 등록을 제대로 익히는 것이 취미 수준의 스크립트와 엔터프라이즈급 소프트웨어 제품을 가르는 기준입니다. 테넌트에 종속되지 않는 패키징, 동적 구성 로드, 견고한 런타임 동의 검증으로 사고방식을 전환하면 조용히 실패하는 배포를 없애고, 모든 고객에게 매끄러운 경험을 제공할 수 있습니다.

이 솔루션의 실제 사례와 아키텍처 결정 배경을 더 알고 싶다면 관련 팟캐스트 에피소드 Fix Multi-Tenant SPFx Authentication도 꼭 확인해 보십시오. 읽어 주셔서 감사합니다. 즐거운 코딩 되십시오!