Exchange Online 管理 API の認証と承認

注:

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

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

Exchange Online 管理 API は、REST ベースの方法で特定の PowerShell コマンドレットを実行する方法を提供し、従来の Exchange Web サービス (EWS) シナリオを置き換えます。詳細については、「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 クライアントなど)。
- サポートされているアカウントの種類: 次のいずれかの値を選択します。
  - Single-organization apps: [この組織ディレクトリ内のアカウント] のみを選択します。
  - マルチテナント委任シナリオ: 任意の組織ディレクトリ内の [アカウント] を選択します。
- リダイレクト 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 許可されていません」。

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

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

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

メールボックスおよびフォルダー操作の受信者管理。
組織レベルの設定の Organization Management organization-level settings。
読み取り専用の組織操作の表示限定の組織管理。

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

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

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

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

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

エンドポイント	必須の Exchange 役割グループ
/OrganizationConfig /AcceptedDomain	View-Only Organization Management
/Mailbox /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	Recipient Management

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

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

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

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

トークンを要求するときは、リソースの /.default スコープ ( https://outlook.office365.com/.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` ) と、アプリがリソースに長期間アクセスするために更新トークンが必要であることを示す `offline_access` などの OIDC スコープを含めることができます。
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: トークンの認証コードを使う (手順 2: トークンの認証コードを使う) でのトークン要求中にアプリが取得したrefresh_token。
scope	必須	スコープのスペースで区切られた一覧。アプリが要求するスコープは、「手順 2: トークンの認証コードを使用する」で要求したスコープと同等か、スコープのサブセットである必要があります。
client_secret	Web アプリに必須	アプリのアプリ登録ポータルで作成したクライアントシークレット。

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

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

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

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

アクセストークンを取得するには、 /token 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 認証ライブラリ (MSAL) などです。

MSAL およびその他のサポートされている認証ライブラリは、詳細を処理することでプロセスを簡素化するため、アプリの機能に集中できます。例:

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

Microsoft は、Microsoft ID プラットフォームでサポートされている認証ライブラリを示す幅広いコードサンプルを保持しています。これらのコードサンプルにアクセスするには、「Microsoft ID プラットフォームのコードサンプル」を参照してください。

証明書を使用してトークンを取得する方法の例については、「Microsoft ID プラットフォーム」と「OAuth 2.0 クライアント資格情報フロー」を参照してください。

最終更新: 2026-09-25

Exchange Online 管理 API の認証と承認

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

手順 2: 必要な API アクセス許可を割り当てる

手順 3: RBAC アクセス許可を割り当てる

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

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

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

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

手順 1: ユーザーにサインインと同意を促す

手順 2: トークンの認証コードを使う

手順 3: アクセス トークンを暗黙的に更新する (ユーザー プロンプトなし)

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

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

Microsoft 認証ライブラリ (MSAL) の使用

その他のリソース

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

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

手順 3: アクセストークンを暗黙的に更新する (ユーザープロンプトなし)

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