Microsoft Entra ID에서 단일 테넌트 앱을 다중 테넌트로 변환
SaaS(서비스형 소프트웨어) 애플리케이션을 많은 조직에 제공하는 경우 다중 테넌트로 변환하여 모든 Microsoft Entra 테넌트의 로그인을 허용하도록 애플리케이션을 구성할 수 있습니다. Microsoft Entra 테넌트의 사용자는 애플리케이션에서 자신의 계정을 사용하는 데 동의한 후 애플리케이션에 로그인할 수 있습니다.
자체 계정 시스템(또는 다른 클라우드 공급자의 다른 로그인)이 있는 기존 앱의 경우 OAuth2, OpenID Connect 또는 SAML을 통해 로그인 코드를 추가하고 애플리케이션에 "Microsoft로 로그인" 단추를 배치해야 합니다.
이 방법 가이드에서는 단일 테넌트 앱을 Microsoft Entra 다중 테넌트 앱으로 변환하는 데 필요한 네 단계를 수행합니다.
- 애플리케이션 등록을 다중 테넌트로 업데이트
/common엔드포인트에 요청을 보내도록 코드 업데이트- 여러 발급자 값을 처리하도록 코드 업데이트
- 사용자 및 관리자 동의를 이해하고 적절하게 코드 변경
샘플 중 하나를 사용하려는 경우 Microsoft Entra ID 및 OpenID Connect를 사용하여 Microsoft Graph를 호출하는 다중 테넌트 SaaS 웹 애플리케이션 빌드를 참조하세요.
필수 조건
- Microsoft Entra 테넌트. 없는 경우 Microsoft의 빠른 시작: Microsoft Entra ID에서 새 테넌트 만들기에서 만들 수 있습니다.
- Microsoft ID 플랫폼에 등록된 애플리케이션입니다. 없는 경우 Microsoft의 빠른 시작: Microsoft ID 플랫폼에서 애플리케이션 등록에서 만들 수 있습니다.
- Microsoft Entra ID의 테넌시를 잘 알고 있습니다.
- 애플리케이션 코드를 편집할 수 있는 IDE(통합 개발 환경)입니다.
다중 테넌트로 등록 업데이트
기본적으로 Microsoft Entra ID의 웹앱/API 등록은 만들 때 단일 테넌트입니다. 등록 다중 테넌트를 만들려면 Microsoft Entra 관리 센터 로그인하고 업데이트하려는 앱 등록을 선택합니다. 앱 등록이 열려 있는 상태에서 인증 창을 선택하고 지원되는 계정 유형 섹션으로 이동합니다. 설정을 모든 조직 디렉터리의 계정으로 변경합니다.
Microsoft Entra 관리 센터에서 단일 테넌트 애플리케이션을 만들 때 개요 페이지에 나열된 항목 중 하나는 애플리케이션 ID URI입니다. 이는 프로토콜 메시지에서 애플리케이션을 식별하는 방법 중 하나이며 언제든지 추가할 수 있습니다. 단일 테넌트 앱의 앱 ID URI는 해당 테넌트 내에서 전역적으로 고유할 수 있습니다. 반면, 다중 테넌트 앱의 경우 모든 테넌트에서 전역적으로 고유해야 합니다. 그러면 Microsoft Entra ID가 모든 테넌트에서 앱을 찾을 수 있습니다.
예를 들어, 테넌트의 이름이 contoso.onmicrosoft.com인 경우 유효한 앱 ID URI은 https://contoso.onmicrosoft.com/myapp입니다. 앱 ID URI가 이 패턴을 따르지 않으면 애플리케이션을 다중 테넌트로 설정하지 못합니다.
/common에 요청을 보내도록 코드를 업데이트합니다.
다중 테넌트 애플리케이션을 사용하면 애플리케이션에서 사용자가 어떤 테넌트인지 즉시 알 수 없으므로 요청을 테넌트의 엔드포인트로 보낼 수 없습니다. 대신 모든 Microsoft Entra 테넌트에 걸쳐 요청을 처리하는 중앙 허브 역할을 하는 공통 엔드포인트(https://login.microsoftonline.com/common)로 요청이 전송됩니다.
IDE에서 앱을 열고 코드를 편집하고 테넌트 ID의 값을 /common으로 변경합니다. 이 엔드포인트는 테넌트 또는 발급자 자체가 아닙니다. Microsoft ID 플랫폼은 /common 엔드포인트에서 요청을 받을 때 사용자를 로그인하여 사용자가 속한 테넌트를 검색합니다. 이 엔드포인트는 Microsoft Entra ID(OpenID Connect, OAuth 2.0, SAML 2.0, WS-Federation)에서 지원하는 모든 인증 프로토콜과 함께 작동합니다.
그 경우 애플리케이션에 대한 로그인 응답에는 사용자를 나타내는 토큰이 들어 있습니다. 애플리케이션은 토큰에 든 발급자 값을 보고 사용자가 어떤 테넌트에서 오는지 알게 됩니다. 응답이 /common 엔드포인트에서 반환될 때 토큰의 발급자 값이 사용자의 테넌트에 해당합니다.
참고 항목
다중 테넌트 애플리케이션에 대해 실제로는 다음과 같은 두 가지 권한이 있습니다.
https://login.microsoftonline.com/common조직 디렉터리(Microsoft Entra 디렉터리) 및 개인 Microsoft 계정(예: Skype, XBox)의 계정을 처리하는 애플리케이션의 경우.- 모든 조직 디렉터리(모든 Microsoft Entra 디렉터리)에서 계정을 처리하는 애플리케이션의 경우
https://login.microsoftonline.com/organizations:
이 문서의 설명은 common을(를) 사용합니다. 그러나 애플리케이션이 Microsoft 개인 계정을 지원하지 않는 경우 organizations(으)로 바꿀 수 있습니다.
여러 발급자 값을 처리하는 코드를 업데이트합니다.
웹 애플리케이션 및 웹 API는 Microsoft ID 플랫폼에서 토큰을 수신하고 유효성을 검사합니다. 네이티브 클라이언트 애플리케이션은 액세스 토큰의 유효성을 검사하지 않으며 불투명한 것으로 처리해야 합니다. 대신 Microsoft ID 플랫폼에서 토큰을 요청 및 수신하고 API로 보낸 다음, 유효성을 검사합니다.
다중 테넌트 애플리케이션은 토큰의 유효성을 검사할 때 더 많은 검사를 수행해야 합니다. 다중 테넌트 애플리케이션이 /organizations 또는 /common 키 URL에서 키 메타데이터를 사용하도록 구성되었습니다. 애플리케이션은 토큰의 iss 클레임에 테넌트 ID(tid) 클레임이 포함되어 있는지 확인하는 일반적인 검사 외에도 게시된 메타데이터의 issuer 속성이 토큰의 iss 클레임과 일치하는지 확인해야 합니다. 자세한 내용은 토큰 유효성 검사를 참조하세요.
사용자 및 관리자 동의를 이해하고 적절한 코드 변경을 합니다.
사용자가 Microsoft Entra ID로 애플리케이션에 로그인하려면 애플리케이션이 사용자의 테넌트에 표시되어야 합니다. 이를 통해 조직은 사용자가 테넌트로부터 애플리케이션에 로그인할 때 고유한 정책을 적용하는 것과 같은 작업을 수행할 수 있습니다. 단일 테넌트 애플리케이션의 경우 Microsoft Entra 관리 센터통해 등록을 사용할 수 있습니다.
다중 테넌트 애플리케이션의 경우 애플리케이션의 초기 등록은 개발자가 사용하는 Microsoft Entra 테넌트에 있습니다. 다른 테넌트의 사용자가 처음으로 애플리케이션에 로그인하면 Microsoft Entra ID는 애플리케이션에서 요청하는 사용 권한에 동의하는지 묻습니다. 동의한다면 서비스 주체라는 애플리케이션의 표현이 사용자 테넌트에 생성되고 로그인은 계속 진행할 수 있습니다. 위임이 또한 사용자의 동의를 애플리케이션에 기록하는 디렉토리에 만들어집니다. 애플리케이션의 Application 및 ServicePrincipal 개체와 서로 간의 관계를 설정하는 방법에 대한 자세한 내용은 애플리케이션 개체 및 서비스 주체 개체를 참조하세요.
이 동의 환경이 애플리케이션에서 요청한 사용 권한에 따른 영향을 받습니다. Microsoft ID 플랫폼은 두 가지 종류의 사용 권한을 지원합니다.
- 위임된 권한: 이 권한은 사용자가 할 수 있는 작업의 하위 집합에 대해 로그인한 사용자 역할을 하는 기능을 애플리케이션에 부여합니다. 예를 들어 애플리케이션에 위임된 권한을 부여하여 로그인한 사용자의 일정을 읽게 할 수 있습니다.
- 앱 전용 권한: 이 권한은 애플리케이션의 ID에 직접 부여됩니다. 예를 들어 누가 애플리케이션에 로그인했는지에 상관없이 애플리케이션에 애플리케이션 전용 권한을 부여하여 테넌트의 사용자 목록을 읽게 할 수 있습니다.
일부 사용 권한은 일반 사용자가 동의할 수 있는 반면 또 다른 사용 권한은 테넌트 관리자의 동의가 필요합니다.
사용자 및 관리자 동의에 대한 자세한 내용은 관리자 동의 워크플로 구성을 참조하세요.
관리자 동의
응용 프로그램 전용 권한은 테넌트 관리자의 동의를 항상 필요로 합니다. 애플리케이션이 애플리케이션 전용 사용 권한을 요청하고 사용자가 애플리케이션에 로그인을 시도하는 경우 사용자가 동의할 수 없음을 알리는 오류 메시지가 나타납니다.
위임된 특정 권한은 또한 테넌트 관리자의 동의를 필요로 합니다. 예를 들어, 로그인한 사용자로서 Microsoft Entra ID에 다시 쓰려면 테넌트 관리자의 동의가 필요합니다. 앱 전용 권한과 같이, 일반 사용자가 관리자 동의가 필요한 위임된 권한을 요청하는 애플리케이션에 로그인하려는 경우 애플리케이션에 오류가 발생합니다. 권한에 관리자 동의가 필요한지 여부는 리소스를 게시한 개발자가 결정하며 해당 리스스에 대한 설명서에서 확인할 수 있습니다. Microsoft Graph API에 대한 권한 설명서에는 관리자 동의가 필요한 권한이 나와 있습니다.
애플리케이션에서 관리자 동의가 필요한 권한을 사용할 경우 관리자가 작업을 시작할 수 있는 단추나 링크를 추가하는 것이 좋습니다. 애플리케이션에서 이 작업에 대해 보내는 요청은 prompt=consent 쿼리 문자열 매개 변수도 포함된 일반적인 OAuth2/OpenID Connect 권한 부여 요청입니다. 일단 관리자가 동의했고 서비스 주체가 고객 테넌트에 만들어졌다면 차후의 로그인 요청은 prompt=consent 매개 변수를 필요로 하지 않습니다. 관리자가 요청된 권한이 허용된다고 결정했다면 테넌트의 다른 사용자들에게 그 시점 이후로 동의하라는 메시지가 표시되지 않습니다.
테넌트 관리자는 일반 사용자가 애플리케이션에 동의하는 기능을 사용하지 않도록 설정할 수 있습니다. 이 기능이 사용되지 않는 경우 테넌트에서 애플리케이션을 사용하려면 항상 관리자 동의가 필요합니다. Microsoft Entra 관리 센터에서 최종 사용자 동의를 비활성화하여 애플리케이션을 테스트할 수 있습니다. Enterprise 애플리케이션>동의 및 사용 권한에서 사용자 동의 허용 안 함 옵션을 선택합니다.
prompt=consent 매개 변수는 관리자 동의가 필요하지 않은 권한을 요청하는 애플리케이션에서도 사용할 수 있습니다. 예를 들어 애플리케이션에 테넌트 관리자가 한 번 “등록”한 환경이 필요하고, 해당 시점에서 다른 사용자에게 동의를 요구하지 않는 경우가 있습니다.
애플리케이션에 관리자 동의가 필요하고 관리자가 prompt=consent 매개 변수를 보내지 않고 로그인하는 경우, 관리자가 애플리케이션에 동의할 때 자신의 사용자 계정에만 적용됩니다. 일반 사용자는 여전히 애플리케이션에 로그인하거나 동의할 수 없습니다. 이 기능은 다른 사용자에게 액세스를 허용하기 전에 애플리케이션을 탐색하는 기능을 테넌트 관리자에게 부여하고자 할 때 유용합니다.
동의 및 다중 계층 애플리케이션
애플리케이션에 여러 계층이 있을 수 있으며, 각 계층은 Microsoft Entra ID의 자체 등록으로 표시됩니다. 예를 들어, 웹 API를 호출하는 네이티브 애플리케이션 또는 웹 API를 호출하는 웹 애플리케이션. 두 경우 모두, 클라이언트(네이티브 앱 또는 웹앱)는 리소스(웹 API)를 호출하는 권한을 요청합니다. 클라이언트가 고객의 테넌트로 성공적으로 동의되려면 사용 권한을 요청한 모든 리소스가 고객의 테넌트에 이미 있어야 합니다. 이 조건이 충족되지 않으면 Microsoft Entra ID는 리소스를 먼저 추가해야 한다는 오류를 반환합니다.
단일 테넌트에서 여러 계층
논리 애플리케이션이 예를 들어 별도의 클라이언트와 리소스와 같은 두 개 이상의 애플리케이션 등록으로 구성되어 있다면 이것이 문제일 수 있습니다. 먼저 리소스를 외부 테넌트에 가져오려면 어떻게 해야 하나요? Microsoft Entra ID는 클라이언트와 리소스가 단일 단계로 동의되도록 하여 이 경우를 다룹니다. 동의 페이지에서 클라이언트와 리소스 모두에서 요청한 전체 사용 권한을 사용자에게 표시합니다. 이 동작을 사용하도록 설정하려면 리소스의 애플리케이션 등록에 클라이언트의 앱 ID가 해당 애플리케이션 매니페스트의 knownClientApplications로 포함되어야 합니다. 예시:
"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]
이는 다중 테넌트 애플리케이션 샘플에서 설명합니다. 다음 다이어그램에서는 단일 테넌트에 등록된 다중 계층 응용 프로그램에 대한 동의 개요를 제공합니다.
여러 테넌트에 있는 여러 계층
애플리케이션의 다른 계층이 다른 테넌트에 등록되어 있다면 유사한 사례가 발생합니다. 예를 들어 Exchange Online API를 호출하는 네이티브 클라이언트 애플리케이션을 빌드하는 경우를 생각해 보겠습니다. 네이티브 애플리케이션을 개발하고, 그 후 네이티브 애플리케이션이 고객 테넌트에서 실행되도록 하려면 Exchange Online 서비스 주체가 있어야 합니다. 이 경우에 개발자 및 고객이 자신의 테넌트에 서비스 주체가 생성되도록 하려면 Exchange Online를 구매해야 합니다.
Microsoft 이외의 조직에서 빌드한 API의 경우, API 개발자는 고객이 자신의 테넌트에 대한 애플리케이션에 동의하는 방법을 제공해야 합니다. 타사 개발자가 API를 작성하여 등록을 구현하는 웹 클라이언트로도 기능할 수 있도록 설계하는 것이 좋습니다. 방법:
- 이전 섹션에 따라 API에서 다중 테넌트 애플리케이션 등록/코드 요구 사항을 구현하는지 확인합니다.
- API의 범위/역할을 노출하는 것 외에도, 등록에 "로그인 및 사용자 프로필 읽기" 권한(기본 제공)이 포함되어 있는지 확인합니다.
- 웹 클라이언트에 로그인/등록 페이지를 구현하고 관리자 동의 지침을 따릅니다.
- 사용자가 애플리케이션에 동의하면 서비스 주체 및 동의 위임 링크가 해당 테넌트에 만들어지고 네이티브 애플리케이션에서 API에 대한 토큰을 가져올 수 있습니다.
다음 다이어그램에서는 다른 테넌트에 등록된 다중 계층 응용 프로그램에 대한 동의 개요를 제공합니다.
동의 철회
사용자와 관리자는 언제든지 애플리케이션에 대한 동의를 해지할 수 있습니다.
- 사용자는 자신의 액세스 패널 애플리케이션 목록에서 개별 애플리케이션을 제거하여 해당 애플리케이션에 대한 액세스 권한을 취소합니다.
- 관리자는 Microsoft Entra 관리 센터의 Enterprise 애플리케이션 섹션에서 애플리케이션을 제거함으로써 해당 애플리케이션에 대한 액세스 권한을 철회합니다. 애플리케이션을 선택하고 사용 권한 탭으로 이동하여 액세스를 철회합니다.
관리자가 테넌트의 모든 사용자에 대해 애플리케이션에 동의하는 경우 사용자는 개별적으로 액세스를 해지할 수 없습니다. 관리자만이 액세스를 해지할 수 있으며 전체 애플리케이션에 대해서만 해지할 수 있습니다.
다중 테넌트 애플리케이션 및 액세스 토큰 캐싱
다중 테넌트 애플리케이션은 Microsoft Entra ID로 보호되는 API를 호출하기 위해 액세스 토큰을 가져올 수도 있습니다. 다중 테넌트 애플리케이션에서 MSAL(Microsoft 인증 라이브러리)을 사용하는 경우의 일반적인 오류는 먼저 /common을 사용하여 사용자에 대한 토큰을 요청하고 응답을 받은 다음, 또 다시 /common을 사용하여 동일한 사용자에 대한 후속 토큰을 요청하는 것입니다. Microsoft Entra ID의 응답은 /common이 아닌 테넌트에서 나오므로 MSAL은 토큰을 테넌트에서 오는 것으로 캐시합니다. 사용자에 대한 액세스 토큰을 가져오기 위한 /common에 대한 후속 호출은 캐시 항목이 누락되어, 사용자에게 다시 로그인하라는 메시지가 표시됩니다. 캐시 누락을 방지하려면 이미 로그인한 사용자에 대한 후속 호출이 테넌트의 엔드포인트에 대해 있었는지 확인합니다.