Exchange Online 管理 API の認証と承認

注:

この記事で説明されている機能は現在プレビュー段階であり、すべての組織で利用できるわけではありません。変更される可能性があります。

この記事では、Exchange Online 管理 API のエンドポイントを使用するための認証と承認の要件について説明します。

Exchange Online 管理 API は、従来の Exchange Web Services (EWS) シナリオを置き換えて、特定の PowerShell コマンドレットを実行するための REST ベースの方法を提供します。詳細については、「Exchange Online 管理 API の概要」を参照してください。

管理 API にアクセスするには、アプリで ID を確立し、適切なアクセス許可を取得し、セキュリティで保護されたトークン処理のベストプラクティスに従う必要があります。大まかに言うと、このプロセスには次の重要な手順が含まれます。

Microsoft Entra IDでアプリを登録する

アプリの ID を確立し、資格情報 (クライアントシークレットまたは証明書) を構成するためのアプリ登録を作成します。この登録により、アプリはMicrosoft Entra IDからトークンを要求できます。
必要な API アクセス許可を割り当てる

必要な OAuth スコープをアプリ登録に追加します。
- 委任されたフロー: Exchange.ManageV2。
- アプリ専用フロー: Exchange.ManageAsAppV2。
手順 3: RBAC アクセス許可を割り当てる

Exchange Onlineでは、ロールベースのアクセス制御 (RBAC) を使用して、呼び出し元が管理できるエンドポイント、コマンドレット、オブジェクトを決定します。ユーザー (委任されたアクセスの場合) またはアプリのサービスプリンシパル (アプリ専用アクセスの場合) に適切な RBAC ロールを割り当てます。
手順 4: アクセストークンを取得する

OAuth 2.0 フローを使用して、Microsoft Entra IDからトークンを取得します。
- ユーザーベースのアクセスのための委任されたフロー。
- サービス間アクセスのためのアプリ専用フロー。
手順 5: アクセストークンを使用する

手順 1: Microsoft Entra IDでアプリを登録する

Exchange Online 管理 API を呼び出すには、まずアプリをMicrosoft Entra IDに登録する必要があります。アプリはクラスオブジェクトに似ています。サービスプリンシパルは、クラスのインスタンスのようなものです。詳細については、「Microsoft Entra IDのアプリケーションおよびサービスプリンシパルオブジェクト」を参照してください。 Microsoft Entra IDでのアプリケーションの作成に関する詳細なビジュアルフローについては、「https://aka.ms/azuread-app」を参照してください。

https://entra.microsoft.comでMicrosoft Entra 管理センターを開きます。
ページの上部にある検索ボックスに「アプリの登録」と入力し、結果から選択します。
[アプリの登録] ページで、[新規登録] を選択します。
[アプリケーションの登録] ページ で、アプリケーション 設定を構成します。
- [名前]: わかりやすい名前 (Exchange 管理 API クライアントなど) を入力します。
- サポートされているアカウントの種類: 次のいずれかの値を選択します。
  - [単一organization アプリ]: [この組織のディレクトリ内のアカウントのみ] を選択します。
  - マルチテナント委任シナリオ: 任意の組織ディレクトリの [アカウント] を選択します。
- リダイレクト URI (省略可能): 委任されたフローに必要です。
  - [プラットフォーム]: [Web] を選択 します。
  - 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 によって呼び出し元が管理できるコマンドレットとオブジェクトが決まります。適切な RBAC ロールの割り当てがないと、有効なトークンでもエラー 403 Forbidden で失敗します。

アプリの性質に基づいて、次のいずれかのサブセクションの手順を使用します。

委任された (ユーザー) フローのアクセス許可

委任されたシナリオでは、アプリに代わってトークンを取得するユーザーには、Exchange Onlineで必要な RBAC ロールが割り当てられている必要があります。一般的なロールの例:

メールボックスとフォルダーの操作の受信者管理。
organization レベルの設定の組織の管理。
読み取り専用組織操作の表示専用組織管理。

これらのロールは、Exchange 管理センターまたは PowerShell Exchange Online使用して割り当てます。手順については、「Exchange Onlineでの役割グループの管理」を参照してください。

アプリ専用フローのアクセス許可

アプリのみのシナリオでは、アプリを表すサービスプリンシパルに十分なアクセス許可が必要です。以下のオプションがあります。

Microsoft Entraロールを割り当てる (わかりやすくするために推奨) : 組み込みのMicrosoft Entraロールをエンタープライズアプリケーションに付与します。たとえば、Exchange 管理者は完全なExchange Onlineアクセス許可を持ちます。
1. https://entra.microsoft.comのMicrosoft Entra 管理センターで、[ロール] & [管理者] を選択します。
2. [ロールと管理者] |[すべてのロール] ページで、最初の列の横にある [チェック] ボックス以外の行の任意の場所をクリックして、Exchange 管理者ロールを選択します。
3. Exchange 管理者 |開いた [割り当て] ページで、[割り当ての追加] を選択し、アプリを選択して、[確認] を選択します。
組み込みまたはカスタムの Exchange RBAC 役割グループ (最小限の特権) を割り当てる: アプリで必要なコマンドレットのみを含む既存のカスタムロールグループをExchange Onlineで作成または使用し、それらのグループにサービスプリンシパルを追加します。この方法では、広範な特権を回避し、最小限の特権のセキュリティに合わせて調整します。詳細については、「Exchange Online PowerShell でのアプリのみの認証」を参照してください。

次の表に、各エンドポイントに必要な組み込みの RBAC ロールを示します。

エンドポイント	必要な Exchange 役割グループ
/OrganizationConfig /AcceptedDomain	View-Only Organization Management
/メールボックス /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	Recipient Management

さらに詳細な制御を行う場合は、アプリケーションで必要な特定の管理ロール (コマンドレットセット) のみを含むカスタムロールグループの使用を検討してください。この方法は、最小限の特権のセキュリティに従い、Exchange Administrator やグローバル管理者などの広範なロールと比較してリスクを軽減します。これは、一般的な管理 API 操作に必要なスコープを超えています。

手順 4: アクセストークンを取得する

Exchange Online 管理 API を呼び出すには、アプリがMicrosoft Entra IDから OAuth 2.0 アクセストークンを取得する必要があります。前述のように、管理 API では次のフローがサポートされています。

更新トークンを使用した承認コードフロー (委任済み): アプリはサインインしているユーザーの代わりに動作し、要求に offline_access スコープが含まれている場合は、サイレント更新用の更新トークンを取得することもできます。
クライアント資格情報フロー (アプリのみ): アプリはそれ自体として機能します (ユーザーなし)。サービス/バックグラウンドシナリオに使用されます。更新トークンは、このフローでは発行されません。

トークン (https://outlook.office365.com/.default など) を要求するときは、リソースの/.defaultスコープを使用します。このメソッドは、Microsoft Entra IDに、そのリソースに対して以前に付与されたアプリケーションのアクセス許可 (ロール) を含むトークンを発行するように指示します。

更新トークンを使用した承認コードフロー (委任)

ユーザーコンテキストが必要な場合は、このフローを使用します。更新トークンを取得するには、承認要求とトークン要求で offline_access を要求する必要があります。詳細については、「Microsoft ID プラットフォームのトークンの更新」と「Microsoft ID プラットフォームのスコープとアクセス許可」を参照してください。

ユーザーは、アプリが自分の代わりに動作することを承認する必要があります。アプリは、ユーザーをMicrosoft ID プラットフォームの/authorize エンドポイントにリダイレクトします。このエンドポイントを通じて、ユーザー Microsoft Entra IDサインインし、アプリが要求するアクセス許可に対する同意を要求します。同意後、Microsoft Entra IDは承認コードをアプリに返します。その後、アプリは、Microsoft ID プラットフォームの/token エンドポイントでこのコードをアクセストークンに引き換えることができます。

次の例は、 /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 アクセス許可のスペース区切りの一覧。これらのアクセス許可には、リソースのアクセス許可 (このシナリオでは`https://outlook.office365.com/.default` ) や OIDC スコープ ( `offline_access`など) を含めることができます。これは、アプリがリソースへの有効期間の長いアクセスに更新トークンを必要とすることを示します。
response_mode	推奨	結果のトークンをアプリに送信するメソッドを指定します。有効な値は、 `query` または `form_post`です。
state	推奨	トークン応答にも返される要求に含まれる値。任意のコンテンツの文字列を指定できます。通常、クロスサイト要求フォージェリ攻撃を防ぐために、ランダムな一意の値を使用します。このプロパティは、認証要求が発生する前のアプリ内のユーザーの状態に関する情報 (ページやビューなど) もエンコードします。

ユーザーはサインインし、同意します。 Microsoft Entra IDは、?code=<authorization_code>を使用してredirect_uriにリダイレクトします。
offline_accessを使用すると、後で更新トークンを発行できます。詳細については、「Microsoft ID プラットフォームのトークンの更新」と「Microsoft ID プラットフォームのスコープとアクセス許可」を参照してください。

手順 2: トークンの承認コードを使用する

アプリでは、前の手順の承認コードを使用して、 /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>                  # 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: サインインと同意にユーザーを送信する」で要求したスコープと同じか、またはサブセットである必要があります。
code	必須	「手順 1: サインインして同意するユーザーを送信する」で取得した承認コード。
redirect_uri	必須	「手順 1: サインインと同意にユーザーを送信する」で承認コードを取得するために使用したのと同じリダイレクト URI 値。
client_secret	Web アプリに必須	アプリのアプリ登録ポータルで作成したクライアントシークレット。

成功した応答には、次のものが含まれます。

access_token：持参人。通常、約 60 分です。
refresh_token: offline_access が要求されたため、存在します。
id_token：随意。スコープ openid が要求された場合に返されます。詳細については、「Microsoft ID プラットフォームアプリの種類と認証フロー」および「Microsoft ID プラットフォームの更新トークン」を参照してください。

ヒント

トークン要求から TenantID (tid) 値を格納します。管理 API URL と今後のトークン要求を形成するために必要です。詳細については、「アプリの種類と認証フローのMicrosoft ID プラットフォーム」を参照してください。

手順 3: アクセストークンをサイレントモードで更新する (ユーザープロンプトなし)

アクセストークンは有効期間が短く、リソースへのアクセスを継続するには、有効期限が切れた後にアプリを更新する必要があります。アプリは、 /token エンドポイントに別の POST 要求を送信することで、アクセストークンを更新します。

要求本文のcodeではなく、refresh_tokenを指定します。
grant_typeとしてauthorization_codeの代わりに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	Web アプリに必須	アプリのアプリ登録ポータルで作成したクライアントシークレット。

成功した応答には、次の結果が含まれます。

新しいaccess_tokenを返し、多くの場合、古いrefresh_tokenを置き換える新しいrefresh_tokenを返します。
更新トークンは、アクセストークンよりも長く続く。既定値は、機密クライアントの場合は約 90 日、SPA リダイレクト URI の場合は 24 時間です。トークンはいつでも取り消すことができるため、必要に応じて再認証を処理します。詳細については、「Microsoft ID プラットフォームのトークンの更新」を参照してください。

クライアント資格情報フロー (アプリのみ)

このフローは、ユーザーがいないサービス間呼び出しに使用します。管理者がアプリケーションのアクセス許可 ( Exchange.ManageAsAppV2 など) に同意し、必要な RBAC ロールを割り当てた後、アプリ独自の資格情報を使用してトークンを要求します。更新トークンは発行されません。必要に応じて新しいアクセストークンを要求します。

アクセストークンを取得するには、 ID プラットフォームエンドポイントに 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/`されるため、スコープ値が`https://outlook.office365.com/.default`されます。この値は、管理者がアクセストークンに同意したすべてのアプリレベルのアクセス許可を含むように、Microsoft ID プラットフォームエンドポイントに通知します。
client_secret	必須	アプリ登録ポータルでアプリ用に生成したクライアントシークレット。値が URL エンコードされていることを確認します。
grant_type	必須	値は `client_credentials`する必要があります。

手順 5: アクセストークンを使用する

「手順 4: アクセストークンを取得する」の説明に従ってアクセストークンを取得したら、後続の API 呼び出しごとにアクセストークンを Authorization ヘッダーに含めます。

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

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

Microsoft 認証ライブラリ (MSAL) を使用する

この記事では、クライアントシークレットのトークンを取得するために問題の生の HTTP 要求を手動で作成するときに必要なプロトコルの詳細について説明します。運用アプリでは、組み込みまたはサポートされている認証ライブラリを使用してセキュリティトークンを取得し、保護された Web API を呼び出します。たとえば、 Microsoft Authentication Library (MSAL) などです。

MSAL やその他のサポートされている認証ライブラリは、アプリの機能に焦点を当てることができるように、詳細を処理することでプロセスを簡略化します。以下に例を示します。

検証。
Cookie の処理。
トークンキャッシュ。
セキュリティで保護された接続。

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: アクセス トークンを使用する

Microsoft 認証ライブラリ (MSAL) を使用する

その他のリソース

手順 4: アクセストークンを取得する

更新トークンを使用した承認コードフロー (委任)

手順 3: アクセストークンをサイレントモードで更新する (ユーザープロンプトなし)

手順 5: アクセストークンを使用する