Exchange Online 관리 API에 대한 인증 및 권한 부여

참고

이 문서에 설명된 기능은 현재 미리 보기로 제공되며, 모든 조직에서 사용할 수 없으며 변경될 수 있습니다.

이 문서에서는 Exchange Online 관리 API에 엔드포인트를 사용하기 위한 인증 및 권한 부여 요구 사항을 설명합니다.

Exchange Online 관리 API는 특정 PowerShell cmdlet을 실행하는 REST 기반 방법을 제공하여 레거시 EWS(Exchange Web Services) 시나리오를 대체합니다. 자세한 내용은 Exchange Online 관리 API 개요를 참조하세요.

관리 API에 액세스하려면 앱이 ID를 설정하고, 올바른 권한을 얻고, 보안 토큰 처리를 위한 모범 사례를 따라야 합니다. 높은 수준에서 프로세스에는 다음 주요 단계가 포함됩니다.

Microsoft Entra ID 앱 등록

앱 등록을 만들어 앱에 대한 ID를 설정하고 자격 증명(클라이언트 암호 또는 인증서)을 구성합니다. 이 등록을 사용하면 앱이 Microsoft Entra ID 토큰을 요청할 수 있습니다.
필요한 API 권한 할당

앱 등록에 필요한 OAuth 범위를 추가합니다.
- 위임된 흐름: Exchange.ManageV2.
- 앱 전용 흐름: Exchange.ManageAsAppV2.
3단계: RBAC 권한 할당

Exchange Online RBAC(역할 기반 액세스 제어)를 사용하여 호출자가 관리할 수 있는 엔드포인트, cmdlet 및 개체를 결정합니다. 사용자(위임된 액세스의 경우) 또는 앱의 서비스 주체(앱 전용 액세스)에 적절한 RBAC 역할을 할당합니다.
4단계: 액세스 토큰 가져오기

OAuth 2.0 흐름을 사용하여 Microsoft Entra ID 토큰을 획득합니다.
- 사용자 기반 액세스를 위한 위임된 흐름입니다.
- 서비스-서비스 액세스를 위한 앱 전용 흐름입니다.
5단계: 액세스 토큰 사용

1단계: Microsoft Entra ID 앱 등록

Exchange Online 관리 API를 호출하려면 먼저 Microsoft Entra ID 앱을 등록해야 합니다. 앱은 클래스 개체와 같습니다. 서비스 주체는 클래스의 instance 같습니다. 자세한 내용은 Microsoft Entra ID 애플리케이션 및 서비스 주체 개체를 참조하세요. Microsoft Entra ID 애플리케이션을 만드는 방법에 대한 자세한 시각적 흐름은 를 참조하세요https://aka.ms/azuread-app.

에서 Microsoft Entra 관리 센터 엽니다https://entra.microsoft.com.
페이지 위쪽의 검색 상자에 앱 등록 입력하고 결과에서 선택합니다.
앱 등록 페이지에서 새 등록을 선택합니다.
애플리케이션 등록 페이지에서 애플리케이션 설정을 구성합니다.
- 이름: 설명이 포함된 이름(예: Exchange 관리 API 클라이언트)을 입력합니다.
- 지원되는 계정 유형: 다음 값 중 하나를 선택합니다.
  - 단일 organization 앱: 이 조직 디렉터리에서만 계정을 선택합니다.
  - 다중 테넌트 위임 시나리오: 모든 조직 디렉터리에서 계정을 선택합니다.
- 리디렉션 URI(선택 사항): 위임된 흐름에 필요합니다.
  - 플랫폼: 웹을 선택합니다.
  - URI: 액세스 토큰이 전송되는 URL(예 https://localhost : 테스트용)을 입력합니다.
애플리케이션 등록 페이지에서 완료되면 등록을 선택합니다.

등록한 앱의 개요 페이지로 이동합니다. 다음 단계를 위해 페이지를 계속 진행하세요.

참고

자동화된 서비스 간 호출에 사용할 수 없으므로 네이티브 애플리케이션에 대한 자격 증명을 만들 수 없습니다.

2단계: 필요한 API 권한 할당

이전 단계에서 만든 앱의 개요 페이지에서 관리 섹션에서 API 권한을 선택합니다.
앱에 대한 API 권한 페이지에서 권한 추가를 선택합니다.
열리는 요청 API 권한 플라이아웃에서 organization 사용하는 API 탭을 선택하고 검색 상자에 Office 365 Exchange Online 입력한 다음 결과에서 선택합니다.
애플리케이션에 필요한 사용 권한 유형은 무엇인가요? 플라이아웃에서 다음 중 하나를 선택합니다.
- 앱 전용 흐름: 애플리케이션 권한을 선택하고, Exchange를 확장하고, Exchange.ManageAsAppV2를 선택한 다음, 권한 추가를 선택합니다.
- 위임된 흐름: 위임된 권한을 선택하고, Exchange를 확장하고, Exchange.ManageV2를 선택한 다음, 권한 추가를 선택합니다.
API 권한 페이지로 돌아가서 이전 단계의 선택 항목이 나열되었는지 확인합니다.
- > Office 365 Exchange Online Exchange.ManageAsApp:
  - 형식: 애플리케이션
  - 관리 동의 필요: 예
- > Office 365 Exchange Online Exchange.ManageV2:
  - 형식: 위임됨
  - 관리 동의 필요: 예
관리자 동의 부여를 선택하고 확인 대화 상자를 검토하고 예를 선택합니다.

3단계: RBAC 권한 할당

앱을 등록하고 API 권한을 부여한 후에는 Exchange RBAC 역할을 구성해야 합니다. OAuth 범위를 사용하면 앱에서 토큰을 가져올 수 있지만 RBAC는 호출자가 관리할 수 있는 cmdlet 및 개체를 결정합니다. 적절한 RBAC 역할 할당이 없으면 403 사용할 수 없음 오류와 함께 유효한 토큰도 실패합니다.

앱의 특성에 따라 다음 하위 섹션 중 하나의 단계를 사용합니다.

위임된(사용자) 흐름에 대한 권한

위임된 시나리오의 경우 앱을 대신하여 토큰을 획득하는 사용자에게는 Exchange Online 할당된 필요한 RBAC 역할이 있어야 합니다. 일반적인 역할 예제:

사서함 및 폴더 작업에 대한 받는 사람 관리.
organization 수준 설정에 대한 조직 관리.
읽기 전용 조직 작업에 대한 보기 전용 조직 관리입니다.

Exchange 관리 센터 또는 Exchange Online PowerShell을 통해 이러한 역할을 할당합니다. 자세한 내용은 Exchange Online 역할 그룹 관리를 참조하세요.

앱 전용 흐름에 대한 권한

앱 전용 시나리오의 경우 앱을 나타내는 서비스 주체에 충분한 권한이 있어야 합니다. 다음과 같은 옵션을 선택할 수 있습니다.

Microsoft Entra 역할 할당(단순성을 위해 권장): 엔터프라이즈 애플리케이션에 기본 제공 Microsoft Entra 역할을 부여합니다. 예를 들어 전체 Exchange Online 권한에 대한 Exchange 관리자:
1. 의 Microsoft Entra 관리 센터 https://entra.microsoft.com역할 & 관리자를 선택합니다.
2. 역할 및 관리자 | 모든 역할 페이지에서 첫 번째 열 옆에 있는 검사 상자 이외의 행의 아무 곳이나 클릭하여 Exchange 관리자 역할을 선택합니다.
3. Exchange 관리자 | 할당 페이지가 열리고, 할당 추가를 선택하고, 앱을 선택한 다음, 확인을 선택합니다.
기본 제공 또는 사용자 지정 Exchange RBAC 역할 그룹 할당(최소 권한): 앱에 필요한 cmdlet만 포함하는 기존 사용자 지정 역할 그룹을 Exchange Online 만들거나 사용하고 해당 그룹에 서비스 주체를 추가합니다. 이 방법은 광범위한 권한을 피하고 최소 권한 보안과 일치합니다. 자세한 내용은 Exchange Online PowerShell의 앱 전용 인증을 참조하세요.

다음 표에는 각 엔드포인트에 필요한 기본 제공 RBAC 역할이 나와 있습니다.

끝점	필수 Exchange 역할 그룹
/OrganizationConfig /AcceptedDomain	보기 전용 Organization Management
/우체통 /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	Recipient Management

보다 세부적인 제어를 위해 애플리케이션에 필요한 특정 관리 역할(cmdlet 집합)만 포함하는 사용자 지정 역할 그룹을 사용하는 것이 좋습니다. 이 방법은 최소 권한 보안을 따르고 일반적인 관리 API 작업에 필요한 scope 초과하는 Exchange 관리자 또는 전역 관리자와 같은 광범위한 역할에 비해 위험을 줄입니다.

4단계: 액세스 토큰 가져오기

Exchange Online 관리 API를 호출하려면 앱이 Microsoft Entra ID OAuth 2.0 액세스 토큰을 가져와야 합니다. 앞에서 설명한 대로 관리 API는 다음 흐름을 지원합니다.

새로 고침 토큰이 있는 권한 부여 코드 흐름(위임됨): 앱은 로그인한 사용자를 대신하여 작동하며 요청에 scope 포함하는 경우 자동 갱신을 위한 새로 고침 토큰을 offline_access 가져올 수도 있습니다.
클라이언트 자격 증명 흐름(앱 전용) : 앱이 그 자체로 작동합니다(사용자 없음). 서비스/백그라운드 시나리오에 사용됩니다. 새로 고침 토큰은 이 흐름에서 발급되지 않습니다.

토큰을 /.default 요청할 때 리소스의 scope 사용합니다(예: https://outlook.office365.com/.default). 이 메서드는 Microsoft Entra ID 해당 리소스에 대해 이전에 부여한 애플리케이션 권한(역할)이 포함된 토큰을 발급하도록 지시합니다.

새로 고침 토큰을 사용하여 권한 부여 코드 흐름(위임)

사용자 컨텍스트가 필요한 경우 이 흐름을 사용합니다. 새로 고침 토큰을 얻으려면 권한 부여 및 토큰 요청에서 요청 offline_access 해야 합니다. 자세한 내용은 Microsoft ID 플랫폼 토큰 새로 고침 및 Microsoft ID 플랫폼 범위 및 권한을 참조하세요.

사용자는 앱을 대신하여 작동하도록 권한을 부여해야 합니다. 앱은 사용자를 /authorize Microsoft ID 플랫폼 엔드포인트로 리디렉션합니다. 이 엔드포인트를 통해 Microsoft Entra ID 사용자를 로그인하고 앱이 요청하는 권한에 대한 동의를 요청합니다. 동의한 후 Microsoft Entra ID 앱에 권한 부여 코드를 반환합니다. 그러면 앱이 액세스 토큰에 /token 대해 Microsoft ID 플랫폼 엔드포인트에서 이 코드를 사용할 수 있습니다.

다음 예제에서는 엔드포인트에 대한 /authorize 요청을 보여줍니다. 요청 URL에서 엔드포인트를 /authorize 호출하고 필수 및 권장 속성을 쿼리 매개 변수로 지정합니다. 예시:

GET https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/authorize
    ?client_id=<ClientID>
    &response_type=code
    &redirect_uri=<RedirectURI> # must exactly match the app registration
    &response_mode=query
    &scope=https://outlook.office365.com/.default offline_access
    &state=12345

매개 변수는 다음 표에 설명되어 있습니다.

매개 변수	필수	설명
TenantID	필수	권한을 요청하는 organization. 값은 TenantID GUID 또는 식별 이름일 수 있습니다.
client_id	필수	등록 포털에서 앱에 할당된 클라이언트 ID입니다. appId라고도 합니다.
response_type	필수	OAuth 2.0 권한 부여 코드 흐름에 대한 값을 `code` 포함해야 합니다.
redirect_uri	권장	앱에서 인증 응답을 보내고 받는 URL로 인코딩된 형식의 앱의 리디렉션 URI입니다. 앱 등록 포털에 등록한 리디렉션 URI 중 하나와 일치해야 합니다.
scope	필수	사용자가 동의할 Exchange Online 관리 API 권한의 공백으로 구분된 목록입니다. 이러한 권한에는 리소스 사용 권한(이 시나리오의 경우) 및 OIDC 범위(`https://outlook.office365.com/.default` 예: `offline_access`)가 포함될 수 있습니다. 이는 앱이 리소스에 대한 수명이 긴 액세스를 위해 새로 고침 토큰이 필요했음을 나타냅니다.
response_mode	권장	결과 토큰을 앱에 다시 보낼 메서드를 지정합니다. 유효한 값은 또는 `form_post`입니다`query`.
상태	권장	토큰 응답에도 반환되는 요청에 포함된 값입니다. 모든 콘텐츠의 문자열일 수 있습니다. 일반적으로 임의 고유 값을 사용하여 사이트 간 요청 위조 공격을 방지합니다. 또한 이 속성은 인증 요청이 발생하기 전에 앱의 사용자 상태에 대한 정보(예: 페이지 또는 보기)를 인코딩합니다.

사용자가 로그인하고 동의합니다. Microsoft Entra ID 을 사용하여 로 redirect_uri?code=<authorization_code>리디렉션합니다.
를 사용하면 offline_access 나중에 새로 고침 토큰을 발급할 수 있습니다. 자세한 내용은 Microsoft ID 플랫폼 토큰 새로 고침 및 Microsoft ID 플랫폼 범위 및 권한을 참조하세요.

2단계: 토큰에 대한 권한 부여 코드 사용

앱은 이전 단계의 권한 부여 코드를 사용하여 엔드포인트에 POST 요청을 전송하여 액세스 토큰을 /token 요청합니다.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                  # confidential clients only
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<RedirectURI>
&scope=https://outlook.office365.com/.default offline_access

매개 변수는 다음 표에 설명되어 있습니다.

매개 변수	필수	설명
TenantID	필수	권한을 요청하는 organization. 값은 TenantID GUID 또는 식별 이름일 수 있습니다.
client_id	필수	등록 포털에서 앱에 할당된 클라이언트 ID입니다. appId라고도 합니다.
grant_type	필수	권한 부여 코드 흐름에 대한 값이어야 `authorization_code` 합니다.
scope	필수	공백으로 구분된 범위 목록입니다. 앱에서 요청하는 범위는 1단계: 로그인 및 동의에 사용자 보내기에서 요청된 범위의 하위 집합과 동일해야 합니다.
코드	필수	1단계: 로그인 및 동의에 사용자를 보내기에서 얻은 권한 부여 코드입니다.
redirect_uri	필수	1단계: 로그인 및 동의에 사용자 보내기에서 권한 부여 코드를 획득하는 데 사용한 것과 동일한 리디렉션 URI 값입니다.
client_secret	웹앱에 필요	앱에 대한 앱 등록 포털에서 만든 클라이언트 암호입니다.

성공적인 응답에는 다음이 포함됩니다.

access_token:무기명. 일반적으로 약 60분입니다.
refresh_token: 가 요청되었으므로 offline_access 현재입니다.
id_token:선택적. scope openid 요청된 경우 반환됩니다. 자세한 내용은 Microsoft ID 플랫폼 앱 유형 및 인증 흐름 및 Microsoft ID 플랫폼 토큰 새로 고침을 참조하세요.

팁

토큰 클레임에서 TenantID(tid) 값을 저장합니다. 관리 API URL 및 향후 토큰 요청을 구성하려면 이 URL이 필요합니다. 자세한 내용은 앱 유형 및 인증 흐름 Microsoft ID 플랫폼 참조하세요.

3단계: 액세스 토큰을 자동으로 새로 고칩니다(사용자 프롬프트 없음)

액세스 토큰은 수명이 짧으며 앱이 만료된 후 새로 고쳐야 리소스에 계속 액세스할 수 있습니다. 앱은 엔드포인트에 다른 POST 요청을 제출하여 액세스 토큰을 /token 새로 고칩니다.

refresh_token 요청 본문에서 code 대신 을 제공합니다.
대신 를 authorization_code grant_type 지정 refresh_token 합니다.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>
&grant_type=refresh_token
&refresh_token=<refresh_token>
&scope=https://outlook.office365.com/.default offline_access

매개 변수는 다음 표에 설명되어 있습니다.

매개 변수	필수	설명
TenantID	필수	권한을 요청하는 organization. 값은 TenantID GUID 또는 식별 이름일 수 있습니다.
client_id	필수	등록 포털에서 앱에 할당된 클라이언트 ID입니다. appId라고도 합니다.
grant_type	필수	값은 이어야 `refresh_token`합니다.
refresh_token	필수	2단계: 토큰에 대한 권한 부여 코드 사용의 토큰 요청 중에 앱이 얻은 refresh_token.
scope	필수	공백으로 구분된 범위 목록입니다. 앱이 요청하는 범위는 2단계: 토큰에 대한 권한 부여 코드 사용에서 요청한 범위의 하위 집합과 동일해야 합니다.
client_secret	웹앱에 필요	앱에 대한 앱 등록 포털에서 만든 클라이언트 암호입니다.

성공적인 응답에는 다음 결과가 포함됩니다.

새 access_token 반환하고 이전 access_token 대체할 새 refresh_token 반환합니다.
새로 고침 토큰은 액세스 토큰보다 오래 지속됩니다. 기본값은 기밀 클라이언트의 경우 약 90일, SPA 리디렉션 URI의 경우 24시간입니다. 언제든지 해지할 수 있는 토큰이므로 필요할 때 재인증을 처리합니다. 자세한 내용은 Microsoft ID 플랫폼 토큰 새로 고침을 참조하세요.

클라이언트 자격 증명 흐름(앱 전용)

사용자 없이 서비스 대 서비스 호출에 이 흐름을 사용합니다. 관리자가 애플리케이션 권한(예 Exchange.ManageAsAppV2: )에 동의하고 필요한 RBAC 역할을 할당한 후 앱의 자체 자격 증명을 사용하여 토큰을 요청합니다. 새로 고침 토큰이 발급되지 않습니다. 필요에 따라 새 액세스 토큰을 요청합니다.

액세스 토큰을 획득하려면 ID 플랫폼 엔드포인트에 /token POST 요청을 보냅니다. 이 요청에서 클라이언트는 클라이언트 암호를 사용합니다.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                   # or client assertion (certificate)
&grant_type=client_credentials
&scope=https://outlook.office365.com/.default

매개 변수는 다음 표에 설명되어 있습니다.

매개 변수	조건	설명
TenantID	필수	권한을 요청하는 organization. 값은 TenantID GUID 또는 식별 이름일 수 있습니다.
client_id	필수	등록 포털에서 앱에 할당된 애플리케이션 ID입니다.
scope	필수	접미사가 있는 `.default` 리소스의 앱 ID URI입니다. Exchange Online 관리 API의 경우 리소스 앱 ID URI는 `https://outlook.office365.com/`이므로 scope 값은 입니다`https://outlook.office365.com/.default`. 이 값은 관리자가 액세스 토큰에 동의한 모든 앱 수준 권한을 포함하도록 Microsoft ID 플랫폼 엔드포인트에 알릴 수 있습니다.
client_secret	필수	앱 등록 포털에서 앱에 대해 생성한 클라이언트 암호입니다. 값이 URL로 인코딩되었는지 확인합니다.
grant_type	필수	값은 이어야 `client_credentials`합니다.

5단계: 액세스 토큰 사용

4단계: 액세스 토큰 가져오기에 설명된 대로 액세스 토큰을 받은 후 각 후속 API 호출에 대한 권한 부여 헤더에 액세스 토큰을 포함합니다.

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json

 { "CmdletInput": { "CmdletName": "Get-OrganizationConfig" } }

MSAL(Microsoft 인증 라이브러리) 사용

이 문서에는 클라이언트 비밀에 대한 토큰을 가져오는 문제 원시 HTTP 요청을 수동으로 만들 때 필요한 프로토콜 세부 정보가 포함되어 있습니다. 프로덕션 앱에서 기본 제공 또는 지원되는 인증 라이브러리를 사용하여 보안 토큰을 얻고 보호된 웹 API를 호출합니다. 예를 들어 MSAL(Microsoft 인증 라이브러리)입니다.

MSAL 및 기타 지원되는 인증 라이브러리는 세부 정보를 처리하여 프로세스를 간소화하므로 앱의 기능에 집중할 수 있습니다. 예시:

유효성 검사.
쿠키 처리.
토큰 캐싱.
보안 연결.

Microsoft는 Microsoft ID 플랫폼 지원되는 인증 라이브러리를 보여 주는 다양한 코드 샘플을 유지 관리합니다. 이러한 코드 샘플에 액세스하려면 코드 샘플 Microsoft ID 플랫폼 참조하세요.

인증서를 사용하여 토큰을 가져오는 방법에 대한 예제는 Microsoft ID 플랫폼 및 OAuth 2.0 클라이언트 자격 증명 흐름을 참조하세요.

Last updated on 2025-11-17

다음을 통해 공유

Exchange Online 관리 API에 대한 인증 및 권한 부여

1단계: Microsoft Entra ID 앱 등록

2단계: 필요한 API 권한 할당

3단계: RBAC 권한 할당

위임된(사용자) 흐름에 대한 권한

앱 전용 흐름에 대한 권한

4단계: 액세스 토큰 가져오기

새로 고침 토큰을 사용하여 권한 부여 코드 흐름(위임)

1단계: 로그인 및 동의하도록 사용자 보내기

2단계: 토큰에 대한 권한 부여 코드 사용

3단계: 액세스 토큰을 자동으로 새로 고칩니다(사용자 프롬프트 없음)

클라이언트 자격 증명 흐름(앱 전용)

5단계: 액세스 토큰 사용

MSAL(Microsoft 인증 라이브러리) 사용

추가 리소스