Microsoft Graph の認証と承認の基本方法

Microsoft Graph を呼び出すには、アプリは Microsoft ID プラットフォームからアクセス トークンを取得する必要があります。アクセス トークンには、アプリとアプリに付与されているアクセス許可に関する情報が含まれています。このアクセス許可は、Microsoft Graph を通じて利用できるリソースと API にアクセスするためのものです。アクセス トークンを取得するには、アプリを Microsoft ID プラットフォームで登録し、そのアプリが必要とする Microsoft Graph リソースへのアクセスをユーザーまたは管理者が承認する必要があります。

この記事では、Microsoft ID プラットフォームとアクセス トークンの概要、アプリでアクセス トークンを取得する方法について説明します。 詳細については、「Microsoft ID プラットフォームとは」を参照してください。 アプリを Microsoft ID プラットフォームと統合してトークンを取得する方法を理解している場合は、「次の手順」セクションで Microsoft Graph に特化した情報とサンプルを参照してください。

Microsoft ID プラットフォームにアプリを登録する

アプリが Microsoft ID プラットフォームからトークンを取得する前に、Azure ポータルに登録する必要があります。 登録によりアプリが Microsoft ID プラットフォームと統合され、次のようなトークンを取得する際に使用する情報を確立します。

  • アプリケーション ID: Microsoft ID プラットフォームによって割り当てられた一意の識別子。
  • リダイレクト URI/URL: アプリが Microsoft ID プラットフォームからの応答を受け取る 1 つ以上のエンドポイント (ネイティブ アプリとモバイル アプリの場合、URI は Microsoft ID プラットフォームによって割り当てられます)。
  • クライアント シークレット: アプリが Microsoft ID プラットフォームでの認証に使用するパスワードまたは公開キー/秘密キーのペア (ネイティブ アプリまたはモバイル アプリの場合は不要です)。

登録時には構成済みのプロパティが要求で使用されます。たとえば、次に示すトークン要求の場合、client_idアプリケーション IDredirect_uri はアプリの登録済み リダイレクト URI の 1 つで、client_secretクライアント シークレット です。

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Microsoft Graph のアクセス許可

Microsoft Graph は、アプリがアクセスするリソース (ユーザー、グループ、メールなど) を制御する詳細なアクセス許可を公開しています。開発者は、アプリで要求する Microsoft Graph のアクセス許可を決定します。そのアクセス許可に同意するかどうかは、アプリにサインインするときに、ユーザー (場合によっては管理者) が決定します。ユーザーが同意すると、アプリは、そのアプリが必要としているリソースと API にアクセスできるようになります。サインインしているユーザーが存在しない状態でリソースと API にアクセスするアプリの場合、アプリのインストール時またはサインアップ時に管理者が事前にアクセス許可に同意できます。

アクセス許可を要求するためのベストプラクティス

注意

ベスト プラクティスとして、データにアクセスして正しく機能するためにアプリに必要な最小限のアクセス許可を要求します。 必要以上の権限でアクセス許可を要求することはセキュリティ対策としては不十分であり、ユーザーが同意を控え、アプリの使用に影響を与える可能性があります。

委任およびアプリケーションのアクセス許可

Microsoft Graph には次の 2 つの種類のアクセス許可があります。

  • 委任されたアクセス許可 は、サインインしているユーザーが存在するアプリで使用します。これらのアプリの場合は、ユーザーまたは管理者がアプリの要求するアクセス許可に同意します。アプリには、Microsoft Graph の呼び出し時に、サインインしているユーザーとして動作するためのアクセス許可が委任されます。一部の委任されたアクセス許可は非管理ユーザーの同意によって付与されますが、高度な特権が付与されるアクセス許可には 管理者の同意が必要になります。

  • アプリケーションのアクセス許可 は、サインインしているユーザーが存在しないアプリで使用します。たとえば、バックグラウンド サービスやデーモンなどのアプリです。アプリケーションのアクセス許可は、管理者のみが同意できます。

有効なアクセス許可

有効なアクセス許可 は、アプリが Microsoft Graph に要求を出すときに持つアクセス許可です。 有効なアクセス許可は、アプリに付与した Microsoft Graph アクセス許可 および サインインしているユーザーまたは呼び出し元アプリの特権の組み合わせによって決まります。 組織では、1 つ以上のロールのポリシーまたはメンバーシップによって、サインインしているユーザーまたはアプリの特権が決定されます。 アプリが持つ委任されたアクセス許可とアプリケーションのアクセス許可の違いと、Microsoft Graph を呼び出すときに有効なアクセス許可について理解することが重要です。

委任されたアクセス許可とアプリケーションのみのアクセス許可のシナリオにおける有効なアクセス許可

  • 委任されたアクセス許可の場合、アプリの有効なアクセス許可は、アプリに付与されている委任されたアクセス許可 (同意によって付与) と現在サインインしているユーザーの特権が重なる範囲に収まる最小権限です。サインインしているユーザーよりも高い特権がアプリに付与されることはありません。

    アプリに委任されたアクセス許可として User.ReadWrite.All が付与されており、ユーザーの更新 API を呼び出すとします。 通常、このアクセス許可は、組織内のすべてのユーザーのプロファイルを読み取り、更新するためのアクセス許可をアプリに付与します。 ただし、有効なアクセス許可のため、サインインしているユーザーの特権に次の制限が適用されます。

    • サインインしているユーザーが全体管理者の場合、アプリは、組織内のすべてのユーザーのプロファイルを更新できるようになります。
    • サインインしているユーザーが管理者ロールに含まれていない場合、アプリはサインインしているユーザーのプロファイル だけ を更新できます。 組織内の他のユーザーのプロファイルは更新されません。これは、サインインしているユーザーにそのような権限が付与されていないためです。
  • アプリケーションのアクセス許可の場合、アプリの有効なアクセス許可は、そのアクセス許可が暗示する完全なレベルの権限になります。たとえば、アプリケーションのアクセス許可 User.ReadWrite.All が付与されているアプリは、組織内のすべてのユーザーのプロファイルを更新できます。

委任されたアクセス許可とアプリケーションのアクセス許可の比較

アイテム 委任されたアクセス許可 アプリケーションのアクセス許可
アプリの種類のシナリオ Web / モバイル / シングルページ アプリ (SPA) Web / デーモン
アクセス コンテキスト ユーザーの代わりにアクセスを取得する サービスとしてアクセスを取得する
同意可能なロール
  • ユーザーは自分のデータに対して同意可能
  • 管理者はすべてのユーザーに対して同意可能
  • 管理者だけが同意可能
    その他の名前
  • scopes
  • OAuth2 のアクセス許可
  • アプリの役割
  • アプリのみのアクセス許可
  • 直接アクセスのアクセス許可
  • 同意の結果 oAuth2PermissionGrants appRoleAssignments

    Microsoft Graph は委任されたアクセス許可とアプリケーションのアクセス許可を公開しますが、アプリの有効なアクセス許可に基づいて要求を承認します。

    Microsoft Graph の委任されたアクセス許可とアプリケーションのアクセス許可の詳細なリスト、および管理者の同意が必要なアクセス許可については、「アクセス許可のリファレンス」を参照してください。

    アクセス トークン

    Microsoft ID プラットフォームにより発行されたアクセス トークンは、呼び出し元の検証と、呼び出し元が要求している操作を実行するための適切なアクセス許可が呼び出し元に付与されていることの検証を行うために、Microsoft ID プラットフォーム (Microsoft Graph など) で保護された Web API により使用されます。 トークンのコンテンツは API のみを対象としているため、呼び出し元は、アクセス トークンを不透明として処理する必要があります。 Microsoft Graphを呼び出すときは、トランスポート層セキュリティ (TLS) を使用するセキュリティで保護されたチャネルを介してアクセス トークンを送信することで、アクセス トークンを常に保護します。

    次の例は、Microsoft ID プラットフォームのアクセス トークンを示します。

    EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==
    

    Microsoft Graph を呼び出す場合は、アクセス トークンをベララー トークンとして HTTP 要求の Authorization ヘッダーに添付します。その例として、サインインしているユーザーのプロファイル情報を返す呼び出しを次に示します (読みやすくするために、アクセス トークンは切り詰められています)。

    GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==
    

    アクセス トークンは、Microsoft ID プラットフォームによって提供される一種のセキュリティ トークンです。 存続期間は短いものですが、既定の有効期間は変更可能です。 アクセス トークンとクライアントによるアクセス トークンの使用方法の詳細については、「アクセス トークン」を参照してください。

    アクセス トークンを取得する

    ほとんどの開発者と同じように、Microsoft ID プラットフォームとのトークンの連携を管理するために、認証ライブラリを使用することになります。認証ライブラリは、検証、Cookie の処理、トークンのキャッシュ、安全な接続の維持など、プロトコルの詳細の多くを開発者から取り除き、アプリの機能の開発に集中できるようにします。Microsoft は、オープン ソースのクライアント ライブラリとサーバー ミドルウェアを公開しています。

    Microsoft ID プラットフォームのエンドポイントの場合:

    • Microsoft Authentication Library (MSAL) クライアント ライブラリは、.NET、JavaScript、Android、および Objective-C で利用できます。すべてのプラットフォームが実稼働対応のプレビューであり、大きな変更が導入されていますが、Microsoft によりアップグレードの経路が保証されています。
    • Microsoft のサーバー ミドルウェアは .NET コア、ASP.NET (OWIN OpenID Connect および OAuth)、Node.js (Microsoft ID プラットフォーム Passport.js) で利用できます。
    • Microsoft ID プラットフォームには、多数のサード パーティ製認証ライブラリとの互換性があります。

    Microsoft クライアント ライブラリ、Microsoft サーバー ミドルウェア、および互換性のあるサード パーティ製ライブラリの完全なリストについては、「Microsoft ID プラットフォームの認証ライブラリ」を参照してください。

    認証ライブラリを使用してアクセス トークンを取得する必要はありません。 認証ライブラリを使わずに Microsoft ID プラットフォームのエンドポイントを直接使用する方法については、「Microsoft ID プラットフォーム認証」を参照してください。

    次の手順

    コードの作成準備が整ったら、次に示すリソースを使用できるようになります。これらのリソースは、Microsoft ID プラットフォームによる認証と承認をアプリに実装する際に役立ちます。

    Microsoft Graph のトレーニングとサンプル

    すぐに使用を開始できるように、さまざまなプラットフォームで API を認証して使用する方法を示した、一連のトレーニング モジュールとその他のリソースを作成しました。

    • [概要] ページで、お好みのプラットフォーム向けのライブラリ、サンプル、トレーニング コンテンツなどのリソースを見つけてください。
    • お使いのプラットフォーム向けに構成済みのサンプルをすぐに実行するには、「Microsoft Graph のクイック スタート」を参照してください。
    • GitHub では Microsoft Graph サンプルを公開しています。

    Microsoft ID プラットフォーム サンプルとドキュメント

    Microsoft ID プラットフォームのドキュメントには、特に Microsoft ID プラットフォームでの認証と承認に焦点を合わせた記事とサンプルが含まれています。

    関連項目